========================================================================================
                                    SEEKER
                            Performance based scheduler
                           Copyright 2009 Amithash Prasad
                                                                                
     Seeker is free software: you can redistribute it and/or modify         
     it under the terms of the GNU General Public License as published by   
     the Free Software Foundation, either version 3 of the License, or      
     (at your option) any later version.                                    
                                                                        
     This program is distributed in the hope that it will be useful,        
     but WITHOUT ANY WARRANTY; without even the implied warranty of         
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          
     GNU General Public License for more details.                           
                                                                        
     You should have received a copy of the GNU General Public License      
     along with this program.  If not, see <http://www.gnu.org/licenses/>.  

   All documentation is licensed under the creative common license, *except*
   C2D_EVENTS.pdf which is the copyright of Intel Corporation, and K8_EVENTS.pdf
   which is the copyright of Advanced Micro Devices ( added here for 
   convenience ) and thesis/* and thesis_eqno/* for which I hold a restrictive non-copy
   non-distribute rights. But this restriction will be removed as soon as I 
   publish upon which the document will become public domain and all have 
   the same rights as other academic publications. This is currently not in
   git HEAD, as I am using a separate repository for it. 

========================================================================================

WARNINGS
--------

This work may destroy your computer and perform unquestionable acts upon your pets.

This is not a production tool, but a research project. There were bad design choices
to enhance development speed -- A tendency which is usually avoided in production grade
software and rampant in research projects (This is because in research, the code is
irrelevant and the _idea_ is everything). 

This project comprises of various kernel modules and may have bugs. I am not Linus,
I am an average Joe the developer. A direct consequence of bugs in kernel modules, is that
you will probably have to learn to do _everything_ from the command prompt. 

If all this does not scare you (Or your adviser is not giving up), welcome my friend.
Welcome to hell. 

========================================================================================
PROJECT DIRECTORY ORGANIZATION
------------------------------
$SEEKER_HOME
        All scripts run scripts and shared headers.
$SEEKER_HOME/Module
        Linux kernel Modules
        $SEEKER_HOME/Module/pmu
                The performance monitoring counter driver
        $SEEKER_HOME/Module/seeker-cpufreq
                The seeker cpufreq governor.
        $SEEKER_HOME/Module/seeker-scheduler
                The meat of this project!
$SEEKER_HOME/Patches
        The patches which needed to be applied for the above modules to work.
$SEEKER_HOME/Scripts
        The scripts/utils which act as support user space applications for the Modules
$SEEKER_HOME/lib
        Libraries which were written to use the seeker syscall interface (And benchmarks
        which does not count)
$SEEKER_HOME/utils
        Utulities (multi-launcher) which is useful to run experiments.
$SEEKER_HOME/SyntheticBenchmarks
        synthetic benchmark to test the system's capibility.
$SEEKER_HOME/MiscScripts
        Scripts to run experiments (Low use for anyone other than people in CU)
        No help section for these. Use by reading the code.
$SEEKER_HOME/AnalysisScripts
        Scripts to analyze data. (Low use for anyone other than myself)
        No help section for these. Use by reading the code.

PRE-SETUP / PRE-REQS:
--------------------

I have done everything on the Linux 2.6.28 kernel. I must warn you that there are changes
to the Linux kernel (from 2.6.29 onwards?) which make some of the modules,  err, not compile.
If you want to get it to work -- seeker-cpufreq -- is the culprit. 

If you want to work on kernel 2.6.24 and earlier, well go to hell! They have separate i386 and
x86_64 branches in arch/ for those cave man kernels and my patches will just FUBAR the kernel
source. 

In order for the modules to work, I had to patch the kernel (Trust me I tried to avoid
this as much as possible. So these are the steps) 


OBVIOUS and other non obvious DEPENDENCIES 
------------------------------------------

software:

1. gcc, g++, perl, make, bash shell (Yes some shell scripts explicitly require bash)
2. Vanilla kernel source (from kernel.org) with my patches installed (Refer next section)
3. If you want to use my R-scripts, R
4. If you want to use my matlab scripts, Octave 

hardware:

1. Intel or AMD architecture WITH performance counter support. Please refer to your
   manual to verify this.
   1a. Number of counters:
       i. Core - 2 programmable counters (pmu), 3 fixed counters (fpmu)
       ii. AMD  - 4 programmable counters no fixed counters. 
   1b. Register (Model specific registers) address values 
       Check Module/pmu/pmu_internal.h describe the correct values.
       Check Module/seeker-scheduler/hwcounters.h to use the correct event select values.

2. Support for DVFS exsits for the current processor in the Linux kernel.
  2a. If AMD - Check powernow-k8 works (loads)
  2b. If Intel, check acpi-cpufreq works (loads)

3. Check if DVFS _really_ works! 
   Note: Intel fuc*ed me on this. The acpi-cpufreq loaded, but DVFS really did not work! 
   Guess it was a BIOS thing. But it took me a while to figure this out. 
   In this dir, I have added a Synthetic benchmark - 
   cd /path/to/this/dir
   cd SyntheticBenchmarks
   make
   ./synth_bench cpu
   Check the execution time, if it is way too small (Ran very fast)
   Increase the trials. 
  ./synth_bench cpu 200

   Now run synth_bench on all "displayed" CPU frequencies. There must be obvious 
   changes like if you doubled the clock speed, your execution time must be cut to half. 
   If not the DVFS mechanism does not work and is just for show, it really really
   does not work. Get another machine! :-)
   PS: Make sure to change the frequency of ALL cores for each experiment. 

4. Each core/virtual processor can transition to clock speeds independently of one another.
   This is currently possible only for the AMD Barcelona processors. There are rumors
   that this support was removed for the later released AMD Barcelona. The Intel Nehelam
   obviously does not have this support as it introduces SMT. 
   I used the AMD Barcelona for my tests, so I did not have to worry about the extra
   complications. If you want to add this support make sure you use one more level
   of hierarchy. Instead of STATE -> CPU GROUP -> CPU, use
   STATE -> CPUSET GROUP -> CPUSET -> CPU


INSTALLING THE PATCHES TO A VANILLA KERNEL
------------------------------------------

1.  Download the kernel from kernel.org.
2.  unzip, untar.
3.  move the linux-2.6.x.x dir to /usr/src
4.  cd to the kernel dir (cd /usr/src/linux-2.6.x.x)
5.  Apply the patches:
   5a. patch -p1 < /path/to/this/dir/Patches/seeker-kernel-2.6.28.patch
   5b. patch -p1 < /path/to/this/dir/Patches/schedmod-kernel-2.6.28.patch
 
6.  Copy /boot/config-2.6.y.y to /usr/src/linux-2.6.x.x/.config where, 
    2.6.y.y is the current booted, working kernel.
7.  cd /usr/src/linux-2.6.x.x
8.  make menuconfig
9.  Select Load alternate config file and select .config

CONFIGURE THE KERNEL
--------------------

10. Make sure you change the following options:
  10a. General Setup -> Local Version   and add any text to it example: "-seeker" sans quotes
       NOTE: This will help you in knowing what is the patched kernel. 
  10b. Make sure General Setup -> Kprobes is selected. 
  10c. Make sure Enable loadable module support is checked. 
  10d. Processor Type and features->  (Make sure are checked - or given value is selected)
       Sub Architecture -> PC Compatible
       Symmetric Multi-Processing support
       Processor Family -> <Whatever your processor is>
            AMD Opteron: Processor Family -> Opteron/Athlon64Hammer/K8
            Intel Core:  Processor Family -> Core 2/Newer Xeon
       Maximum Number of CPUS -> <Set exactly the number of cores/threads you have>
                                 The default can make the memory consumption of 
                                 seeker quite high.
       Feel free to change things here. But know what you are changing.
  10e. Power Management and ACPI Options ->
         Power Management support
         CPU Frequency Scaling ->
             Just check almost everything. 
             I had a problem with the cpufreq drivers built into the kernel. So I kept them as modules
             and made sure they are loaded. 
             MAKE SURE THE CPUFREQ DRIVER FOR YOUR ARCH IS At least a module!
  10f. That's it. If you want you can remove unnecessary, but be very careful. 
       I prefer to get a working boot-able kernel before tweaking it. 

BUILD THE KERNEL
----------------

11. make (This takes a while, so go get a coffee) 
    Recommendation: For every core X on the system you can use up to 10X threads! 
    (Yes I have tried.)
    make -j10X
12. make modules_install install
13. mkinitrd -o /boot/initrd-2.6.x.x.img 2.6.x.x 
    NOTE: Only for Ubuntu. SuSE seems to do this step in make install. 
14. Open /boot/grub/grub.conf and copy the section of your working kernel to a 
    new place and change the title and others to reflect your new compiled kernel.
    NOTE: Again only for Ubuntu. SuSE does this in make install. 

REBOOT INTO THE KERNEL
----------------------

15. Reboot to the new kernel. 
16. Kernel Panic?? Oops... This is why they ask you NOT to over write your existing
    kernel, boot into the working kernel and google! Once everything works fine,
    you can make this kernel the default (Especially if this is a "research test
    machine"!)

SHELL ENVIRONMENT 
-----------------

Yes I am a moron. My build system is FUBAR'ed. My scripts are FUBAR'ed. 
I need a environment variable. Add this to your .bashrc:

export SEEKER_HOME=/path/to/where/seeker/source/code/is

and restart the shell. If you have other shell (Most notably the C-Shell) google
on how to set their environment variables.

18. Make sure you have perl, gcc (Of course!) and  g++ installed. To use the plotting
    scripts, you will need gnuplot 4.2 installed. and for the matlab scripts, do install
    octave.

========================================================================================

For the rest of this document, I will take a man-page approach. Explaining each and every 
module/daemon/script. 

========================================================================================
PATCHES
-------
seeker-kernel-2.6.28.patch
  Tested on the 2.6.28 kernel (Must be obvious from the naming)
  Patches to get pmu interrupt feature like interrupt handling
  Seeker scheduler does not use this feature, but it is a very
  good addition in case you want to extend it. 

  If you _really_ want to use another kernel, you have no option
  but to study the patch. get the 2.6.28 kernel and apply it
  and get an idea what it does. And what it modifies. 
  You can drop me an email: amithash@gmail.com if you need more
  help. But note that I might have forgotten most of the things
  by then. 

schedmod-kernel-2.6.28.patch  
  Tested on the 2.6.28 kernel (Must be obvious from the naming)
  This is a very simple patch which
  1. adds a system call called sys_seeker. 
  2. Adds extra members to task_struct.
  3. Exports a few functions to be used from the module.

========================================================================================
KERNEL MODULES:
--------------

After a make.

All modules are in Module/

pmu/
    The performance monitoring counter driver for AMD and Intel 
    Also supports (Provides interfaces) to talk to the fixed
    performance monitoring counters present in modern Intel Architectures.

    insmod $SEEKER_HOME/Build/pmu.ko

seeker-cpufreq/
    The cpufreq governor which exposes the set_freq interface to seeker-scheduler
    insmod $SEEKER_HOME/Build/seeker_cpufreq.ko
    After this run `$SEEKER_HOME/Scripts/seeker_cpufreq.pl start` to select it.

    OPTIONS: 
      allowed_states=<list of comma separated states>
      example, if the system has 5 states:
      0 - 1100MHz
      1 - 1400MHz
      2 - 1700MHz
      3 - 2000MHz
      4 - 2200MHz
      Then, if you do
      insmod $SEEKER_HOME/Build/seeker_cpufreq.ko allowed_states=0,1,4
      from there on, it internally will transition only to these states
      and any logging will report the following:
      Total of 3 states:
      0 - 1100MHz
      1 - 1400MHz
      2 - 2200MHz

seeker-scheduler/
    The mother module. This depends on the above 3 modules.
    insmod $SEEKER_HOME/Build/seeker_scheduler.ko

    OPTIONS:
      change_interval - Here you can assing the mutation interval in milli-seconds.
                        Default: 1000

      delta           - the mutation constraint. (delta constraint)

      mutation_method - 0 - Delta (Default)
                        1 - dynamic programing (Does not work)
                        2 - Ondemand
                        3 - Conservative
                        4 - Static layout (No mutation)

                        This is just so that I could simulate these governors
                        in my infrastructure so I can gather the same logs. 

      base_state     -  The state (0,1,2,...) which the scheduler will place
                        tasks upon their start. 

      allowed_cpus   - The number of cpus allowed by seeker-scheduler.
                       Cpus 0 - allowed_cpus - 1 will be enabled, and
                       tasks from now on will NOT execute on other 
                       cpus (Other than black listed tasks of course)
     
     scheduling_method  - 0 - Ladder scheduling
                          1 - Select scheduling
                          2 - adaptive ladder scheduling
                          3 - disable scheduling

     init_layout   - Provide a comma separated list of the performance state
                       of cpus starting from 0.
                       so static_layout=0,0,0,0,4,4,4,4 
                       will set cpu 0 to 3 to state 0 
                       and cpu 4-7 to state 4

    PS: Read thesis.pdf :-) 
        mutation interval -> change_interval
        delta             -> delta
        scheduling_method -> evaluation

seeker scheduler exposes a dev interface
/dev/seeker_log which when opened, it will start collecting logs and dumping
the binary logs through this interface. There are already daemons to get
these logs and convert them. So do not worry (Next section)

Example:
insmod $SEEKER_HOME/Build/seeker_scheduler.ko delta=4 change_interval=125 \
                                              allowed_cpus=4 base_stat=3 

Some of these options are not discussed in the thesis as these were used
to enable comparison. 

========================================================================================
INTERFACE TO SEEKER SCHEDULER (Daemons and utils and scripts, Oh My!):
----------------------------------------------------------------------

DAEMONS:
--------

seekerlogd - Is the user space daemon which sucks the binary logs from 
/dev/seeker_log and dumps it into a binary file. 

  USAGE:
  $SEEKER_HOME/Scripts/seekerlogd <LOG FORMAT> <SAMPLE TIME>
    LOG FORMAT:
      This is the format to the output name. If it is:
        ~/log_
        then the first binary file written will be ~/log_0
        The reason will become obvious when you read about send.pl.
    SAMPLE TIME:
        The time interval in seconds. debug will wake up every "SAMPLE TIME" seconds
        and copies data from /dev/seeker_log and dump it into the output file. 

  Make sure that <LOG_FORMAT><NUM> does not exist. seekerlogd will chock and die
  at start. Worse if it happens in the middle!

  Sometimes it takes a few seconds after a process ends for that event
  to make it into the log, so I generally wait about 10-20s after I
  think a process/experiment is done to swap out logs.

----------------------------------------------------------------------------------------
UTILS:
------

decodelog - Is the util to decode the binary log to get the ASCII (Human readable)
            log
  USAGE:
    $SEEKER_HOME/Scripts/decodelog < IN_BIN_FILE > OUT_ASCII_FILE
    Note: Those (< and >) are IO redirects. 

    Decodes the binary log. 

----------------------------------------------------------------------------------------
SCRIPTS:
--------

send.pl  - Instructs seekerlogd daemon to stop writing to the current binary log and start
           writing to the next binary log. Or to kill seekerlogd

  USAGE:
    $SEEKER_HOME/Scripts/send.pl [-t]
      -t - terminate seekerlogd. 

           so if seekerlogd is given a format: ~/log_
           and starts writing to ~/log_0,
           executing send.pl 
           makes it to close ~/log_0 and start to write to ~/log_1
           Using the -t option will cause seekerlogd to close the current binary log and 
           the input /dev/seeker_log and terminate.

----------------------------------------------------------------------------------------

change_speed.pl - Script to manually change the speed with the seeker cpufreq governor.
                  PS: You need the seeker_cpufreq.ko inserted and have enabled
                  seeker_cpufreq governor by running

  USAGE:
    $SEEKER_HOME/Scripts/change_speed.pl -p=PATTERN
    PATTERN - A comma separated ordered list of performance states for cpu 0 through
              sizeof(PATTERN). 

      Example:
                  insmod $SEEKER_HOME/Build/seeker_cpufreq.ko
                  $SEEKER_HOME/Scripts/seeker_cpufreq.pl start
                  $SEEKER_HOME/Scripts/change_speed.pl -p=0,0,0,1,1,1,2,2
            
              Sets performance state of cpu 0-2 to 0, 3-5 to 1 and 6-7 to 2

----------------------------------------------------------------------------------------

pattern_speed.pl - Script to change clock speed with a pattern. 
              
  USAGE:
    $SEEKER_HOME/Scripts/pattern_speed.pl -p=PATTERN -i=INTERVAL [-c=CORE]
      PATTERN - A comma separated list of performance states. 
      INTERVAL - A comma separated list of intervals for the equivalent performance
                 state in PATTERN in milli seconds. 
      CORE     - If provided, the pattern is performed on core CORE, else it is
                 performed on all cores.

      example: 
        insmod $SEEKER_HOME/Build/seeker_cpufreq.ko
        $SEEKER_HOME/Scripts/seeker_cpufreq.pl start
        $SEEKER_HOME/Scripts/pattern_speed.pl -p=0,1,2,3,4 -i=100,200,300,400 
        This will cause all cpus to be transitioned first to 0, then after 100ms,
        will transition to 1 then wait for 200ms and so on. This process is 
        repeated infinitely. 
        $SEEKER_HOME/Scripts/pattern_speed.pl -p=0,1,2,3,4 -i=100,200,300,400 -c=4
        this will do the same, but only to core 4.

========================================================================================
ASCII LOG FORMAT
----------------

There are 4 unique kinds of lines in the log files:
SCH,PID,MUT,STATE

SCH format
----------
s,<interval>,<pid>,<cpu>,<instructions>,<Real IPC>,<state requested>,<state given>,<current state>,<reference cycles>
  interval         - The mutation interval number. 
  pid              - The current task's pid
  cpu              - The cpu on which the current task was executing on.
  instructions     - The total amount of instructions the task executed from the last log.
  Real IPC         - Instructions / Real Clocks (Real clocks vary with different clock speeds)
  state requested  - The state which the PDS (Performance directed scheduler) requested.
  state given      - The state which was given to PDS (Can be different because the requested state was overloaded)
  current state    - The state in which the task executed with from last time.
  reference cycles - The total number of reference cycles from last time (Reference cycles count at a constant 
                     rate irrespective of clock speed).

PID format
----------
p,<pid>,<name>
  pid  - The pid of the task
  name - The name of the task with pid = <pid>
  Used to know what task a SCH line belongs to.

MUT format
----------
m,<interval>,r,<req cpus for state 0>,<req cpus for state 1>...,g,<giv cpus for state 0>,<giv cpus for state 1>...
  interval - The mutation interval number 
  req cpus for state X - The requested number of cpus for performance state X
  giv cpus for state X - The number of cpus given to performance state X by the mutator.

STATE format
------------
t,<cpu>,<state>,<residency time>
  cpu - The cpu 
  state - The state with which cpu was executing
  residency time - The time in millisecond's which cpu - cpu spent in performance state - state

========================================================================================
LOG MANAGEMENT UTILS
--------------------

csv2tsv.pl 
----------
  Convert comma separated file to tab separated file
  Note: This is because some tools (Hear matlab?) make it such a bit*h to handle
  comma separated files, that I had to add this. 

  USAGE:
    csv2tsv.pl input.csv output.tsv
    NOTE: Lines which do not start with a number are automatically prefixed
    with a comment character '#'.

pull.pl
-------
  This should make your life easier with the output ASCII files from decodelog.

USAGE: 
  $SEEKER_HOME/Scripts/pull.pl --input  INPUT_ASCII_FILE \
                               --output OUTPUT_DIR       \
                               --bench  APP_NAME         \
                               --what   WHAT_TO_PULL     \
                               --cpus   TOTAL_CPUS       \
                               --benchlist APP_LIST_FILE 

  INPUT_ASCII_FILE - The file which is got by decodelog.
  OUTPUT_DIR       - The dir to place all these logs. 
  WHAT             - sch,mut,st or all 
                     sch - pull only SCH lines
                     mut - pull only MUT lines
                     st  - pull only STATE lines
                     all - pull all (sch,mut & st) lines. 
  TOTAL_CPUS       - The total number of cpus you want ST information. 
  OPTIONAL:
    APP_NAME   - Pull only information pertaining to application with name APP_NAME
    APP_LIST_FILE - If you need more than one app to pull, keep that in a list (One in each line)
                    and use the --benchlist option.
    If neither --bench or --benchlist option is specified, then all logged tasks are outputted.

  OUTPUT DIR LAYOUT:
  ------------------
  *.sch - One comma separated file for each found task.
  FORMAT: <total instructions> <total reference cycles> <interval> <instructions> <reference cylces> <cpu> <IPC> <state> <req state> <given state>
      total instructions     - The cumulative instructions from the start of the task
      total reference cycles - The cumulative instructions from the start of the tasks
      NOTE: First two is to make your plotting needs easier. 

      interval               - The current mutation interval.
      instructions           - Total instructions executed in this sample. 
      reference cycles       - The total reference cycles in this sample (Note reference cycles are not affected by clock speed changes)
      cpu                    - The cpu on which the task executed.
      IPC                    - The Real IPC with which this task executed with
      state                  - The performance state with which this task executed with in this sample.
      req state              - The state which the PDS requested.
      giv state              - The state the PDS was given (Can be different due to the state being overloaded).

  MUT_GIV
  <interval> <cpus given to state 0> <cpus given to state 1> ...
  (Same as MUT format
   
  MUT_REQ
  <interval> <cpus requested for state 0> <cpus requested for state 1> ...
  same as MUT format.

  CPUST_X
  CPU State residency information for CPU X
  <state> <residency time in ms>
   - Self explanatory. 

========================================================================================

DATA MANIPULATION UTILS
-----------------------

interp
------
  A compile time configurable linear spline interpolation tool. I had to write this
  as R just took ages to process each data file. 
  
  USAGE: interp /path/to/input/csv/file /path/to/output/csv/file. INTERVAL(Millions of instructions)

  The configuration is in iconfig.h
  Yes. This is a C++ header. No, this is not a configuration file. The configuration
  is _compiled_ in. This is to improve the speed of the operations. 

  For configuration help refer to iconfig.h. It is well documented. 


smooth
------
  To smooth out data files using the moving window averaging algorithm.
  Actual window length = 2 * WINDOW_LENGTH + 1
    
  USAGE: smooth /pathto/inerp/csv/data /path/to/op/smooth/csv/data WINDOW_LENGTH

  The file is assumed to be run through interp. That is each sample (Line) is assumed
  to be equal in length. 

maxmin
------
  To find a timeline max and min for a bunch of timeline data. Useful when you are plotting
  the max and min time series plots for data from a bunch of experiments.

  USAGE: maxmin /path/to/op/csv/data /path/to/indata1 /indata2 [/indata3 ....]

  The input files are assumed to to run through interp. That is each sample (Line) is assumed
  to be of equal length.

========================================================================================
OTHER DATA COLLECTION TOOLS
---------------------------

powersample.pl
--------------

USAGE: $SEEKER_HOME/Scripts/powersample.pl <OUTPUT FILE>
    OUTPUT FILE - The output file to save the samples. 

  NOTES:
          1. This is a custom hacked script. You will have to modify it for each machine.. (Sorry)
          2. It probes ipmitool, so it must be installed.
          3. Not only that the ipmitool must be working. Try `ipmitool sensors` to check if everything
             is smooth.

========================================================================================
LIBRARIES
---------

state_recommendations
---------------------

This is the libc equivalent to talk to the syscall interface of seeker scheduler. 
make
export LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH
then you can include the header "state_recommendations.h" in  your runtime, and you
get the following functions:

low_freq() - From now on, you will be executing with the lowest frequency.
mid_freq() - From now on, you will be executing with the frequency inbetween low and high
high_freq() - From now on you will be executing with the highest frequency. 
continue_dynamically() - Stop the recommendations, and let seeker decide your frequency.
ignore_task() - From now on, seeker should not do anything to this task. It is free to 
                roam! :-)

For an example use case, check out:
$SEEKER_HOME/Scripts/test_recommendations.c
and check out the Makefile in 
$SEEKER_HOME/Scripts/Makefile:43


seeker.pm
---------
A set of functions I found rewriting for each perl script I wrote. So it is here.
I do not know if I use it anymore... but it is there.

benchmarks.pm
-------------
A set of perl subroutines to help me with the IBS - Iyyer benchmark suite. 
(This is the DRACO benchmark suite, so if you do not know what they are, it is probably
useless to you)

This is used to create the run scripts. 

========================================================================================
Synthetic Benchmarks
--------------------

cd $SEEKER_HOME/SyntheticBenchmarks
make

USAGE:
  $SEEKER_HOME/SyntheticBenchmarks/synth_bench [cpu|mem] [trials]

  cpu|mem - Exercise cpu or memory. 
  trials  - The number of trials. If it runs too fast or too slow, this is the knob.
            Default: 100

========================================================================================
RUNTIME UTILS
-------------

launch
------

refer to 
$SEEKER_HOME/utils/README

========================================================================================
OTHER SCRIPTS
-------------

$SEEKER_HOME/MiscScripts
These were written to create and run experiments using a home bred benchmark suite
called the Iyyer benchmark suite (IBS) or the DRACO Benchmark Suite which is internal
to CU's system's lab which is just a reorganized and generic collection of various
benchmark systems like the SPEC suite. So if you are not part of CU, this will be 
useless to you.

Everything in $SEEKER_HOME/AnalysisScripts

These were _hack_ scripts written to get my analysis done. It may not be useful to
anyone but me. I just needed to version control them too. So, here they are. 

========================================================================================
FULL SYSTEM USE CASE:
---------------------

# Compile ON THE SYSTEM to be loaded on
cd $SEEKER_HOME
make

# Insert the PMU Drivers.
insmod $SEEKER_HOME/Build/pmu.ko

# Insert the seeker cpufreq governor. Note: The cpufreq driver must be in!
insmod $SEEKER_HOME/Build/seeker_cpufreq.ko

# Pick the seeker governor as the current governor.
$SEEKER_HOME/Scripts/seeker_cpufreq.pl start

# load the seeker scheduler
insmod $SEEKER_HOME/Build/seeker_cpufreq.ko  # And other options.

# Start the logging daemon.
$SEEKER_HOME/Scripts/seekerlogd ~/logs/log_

# Do whatever experiments you want 

sleep 20

# Terminate the logging daemon
$SEEKER_HOME/Scripts/send.pl -t

# Remove the seeker scheduling module.
rmmod seeker_scheduler

# Remove seeker as the current cpufreq governor.
# This is important to remove the module.
$SEEKER_HOME/Scripts/seeker_cpufreq.pl stop

# Remove the seeker cpufreq governor.
rmmod seeker_cpufreq

# Remove the PMU drivers.
rmmod pmu   # if AMD
rmmod fpmu  # if Intel

# Decode the logs.
$SEEKER_HOME/Scripts/decodelog < ~/logs/log_0 > ~/logs/log_0.txt

# Pull from the logs
$SEEKER_HOME/Scripts/pull.pl --input ~/logs/log_0.txt --output ~/APP_logs --bench APP --cpus 4

# Enjoy! 
========================================================================================
========================================================================================
REFERENCE:
----------

1. p4sampler, Author: Tipp Moseley, Graduate Student, Department of Computer Science,
University of Colorado, Boulder pmu driver was a derivative work of this.
Also the log interface of seeker is a derivative work of his use to log the system.

2. INTEL IA32/64 system programmers reference manual.

3. INTEL forums.

4. AMD BIOS developers guide. 

5. AMD Forums.

========================================================================================

AUTHOR:
-------

Amithash Prasad, Graduate Student, Department of Electrical and Computer Engineering,
University of Colorado, Boulder
Email: amithash.prasad@colorado.edu, 
       amithash@gmail.com (I am not going to have the above mentioned id forever!)

========================================================================================