

	The 'gangtest' package is a suite of scripts and programs that
facilitate testing of the gang scheduler. The purpose of the package
is to make it easy to generate gang groups, run and then visualize the
results of the gangs. 
 
USE: 
 First compile all the files using the Makefile in src, by typing 
 'make' and then 'make install'.
 1. Use 'driver <out_file> ' to generate input files for gendata.scr
    The <out_file> must be of the format gtest.tst.* if
    gendata.scr is to be used. To test the gang scheduler 
    create different tests with the same number of total threads
    or 'thread number' but different gang sizes.

 2. Use gendata.scr <directory> to generate output from gtest.
    Where <directory> is the location of the files for generated
    using 'driver'. gendata.scr will put the output from each run
    of gtest in a file <directory>/gtest.out.<n> 

 3. Use genout.scr <directory> to parse the data 
    where <directory> is the location of the files generated by
    gendata

 4. Use gst.scr <directory>  or tst.scr <directory>
    to visualize the data. 
    <directory> is the location of the files generated by genout.scr

    gnuplot must be installed.

 To test the gang scheduler use 'driver' to generate input files
 for gtest such that the total number of threads is constant
 but the number of gangs change. The graphs you see will be a series
 of straight lines for each 'thread number' you graph.

PROGRAMS:

 gtest <in_file> <out_file>:
   <in_file> 
     The format of the infile is
     #of gangs
     '-'
     <A/M> output <A>ll thread times or only gang times <M>
     <E/F/G/S> Schedule using Gang, Free, Single or Equal mode
     # of gang members
     # of iterations
     delay in seconds before next gang launched

   As an example here is test file that specified a test consisting of
   2 gangs with 4 members each using gang scheduling mode with all output and having 100
   iterations and no delay:

      2
      -
      A
      G
      4
      100
      0
      -
      A
      G
      4
      100
      0

   <out_file> is where the output goes 
              if no output file is specified then output goes to stdout.

   gtest works by first reading in the input file. It then starts the
   requested number of gangs, with the requested number of
   members. Each member performs the following loop for as many iterations as
   specified in the input file. For a 150MHz machine a value of 100
   usually takes about 2.5 minutes to complete.

  //  The purpose of the loop is to be a sufficiently long computation
  //  that does not involve waiting on any locks.
  //  num = iterations specified in input file
    for(int l = 0; l < 5; l++){
      for(int i = 0; i < num_; i++){
        for(k = 0; k < num_*num_; k++)
         c = tan(cos(sin(log ((double) k) * atan((double) i)) * cos(k*k)));
       };
    } 

 driver <out_file>
  'driver' generates input files name <out_file>  for 'gtest'. 
  You can also use 'driver' to generate an input file for 'gtest' and then
  execute 'gtest' immediately.
    
  If you want to use gendata you have to specify your <out_file> to
  be of the format gtest.tst.*

 ginput <input_file> [<gangs> <threads>] | <out_file>
  Takes the output of gtest and parses it so it is useable
  for graphing.
  If a gang file and threads file is specified gang and thread
  data is separated otherwise all the output is put in <out_file> or stdout
 
SCRIPTS


 gendata.scr <directory>
  Uses the files in <directory> as inputs for gtest. The output of 
  each run of gtest is put <directory>/gtest.out.<n>.

 genout.scr <direcrory>
  genout.scr is a script that parses the data generated by gendata.scr 
  using ginput. For each file gtest.out.<n> in the <directory> it generates a 
  threads.<n> file and a gangs.<n>.

  The threads.<n> files are of the format:
           For each thread that generated output:
           "threads <thread num> <gang num> <time to complete>"

  The gangs.<n> files are of the format:
           For each gang that generated output:
           "gangs <gang num> <num gang mems> <time to complete>

 gst.scr <directory>
  uses the output of genout.scr to graph  gangs vs time

 tst.scr <directory
  uses the output of genout.scr to graph threads vs time



EXAMPLE:
  You will find actual tests run on borris and their outputs in the 'example' directory.
  borris was a 30 processor machine and so I did tests with 120, 90,60 and 30 threads.
  If you execute tst.scr or gst.scr on any of the subdirectories (t120,t90,t60 or t30)
  you will straight lines for each set of gangs with the same number of threads in that
  gang which is the correct output.


     






