v2.0/bin/PROFILE.DOC

   1                 MS-DOS PROGRAM PROFILER
   2                   FOR .EXE .COM FILES
   3
   4
   5 I. PURPOSE
   6
   7         The PROFIL program is designed to produce an execution
   8     profile of MS-DOS 1.25 or  2.00  .EXE  or  .COM  files  on
   9     8086/8088 systems  which  have a programmable interrupting
  10     clock.  The method employed is  to  chop  the  program  up
  11     into   a  sequence  of  "buckets"  and  to  increment  the
  12     appropriate (based on CS:IP) bucket count when  the  clock
  13     interrupts.  In  addition  there  are  counters  for  hits
  14     in the I/O system and the DOS so  some  idea  of  how  I/O
  15     or DOS  bound  a  program  is.  There is also a bucket for
  16     hits above the program area, you  might  get  counts  here
  17     if your program relocates itself, or goes haywire.
  18
  19         The PROFIL  program  is  not  intended  as an end-user
  20     program, but rather  as  a  developement  tool.   To  this
  21     end it  is  not  particularly robust or friendly, but gets
  22     the job done.  The OEM must write a  PCLOCK  routine  (see
  23     PCLOCK.ASM) which  implements the hardware dependant clock
  24     interrupt.  The  implementation  should  be  evident  from
  25     examining the  source  code,  it  is  quite simple.  There
  26     is a CLOCKON routine  which  sets  up  a  clock  interrupt
  27     to  the  CLK_INTER  routine  every  DX  micro  seconds.  A
  28     CLOCKOFF routine which un-does CLOCKON.  And  a  LEAVE_INT
  29     routine which  is  responsible  for the actual "IRET" from
  30     the clock interrupt.  Also see the PROHIST  documentation.
  31
  32 II. USAGE
  33
  34         The profiler is envoked by uttering:
  35
  36             PROFIL fname.ext
  37
  38     where the  filename  is  completly  specified,   including
  39     extension.  You  will  then  be  prompted  for  the number
  40     of paragraphs in one bucket.  This number  must  be  >  0,
  41     based on  this  number  the  number of buckets is computed
  42     by using the size of the executable file.  Next  you  will
  43     be  prompted  for  the  clock  interval,  and  lastly  for
  44     parameters to  the  program.   Type  the  parameters  just
  45     as if  you  were running the program at the command level.
  46
  47     NOTE: If  a  "bad"  number  is entered for the bucket size
  48         or clock interval, you will be reprompted.
  49
  50         When the program terminates, normally or  by  Cntrl-C,
  51     PROFIL  will  print  a  termination  message  (similar  to
  52     debug).  The output file will  be  fname.PRF  where  fname
  53     is the  same  as  the  file  containing  the program being
  54     profiled.
  55
  56 III. OUTPUT FORMAT
  57
  58         The format of the  output  file  is  the  following  C
  59     type structure.
  60 \f
  61 struct profdata {
  62  short clock_grain;  /* Clock sample interval in
  63                         micro-seconds*/
  64  short bucket_num;   /* The total number of buckets */
  65  short bucket_siz;   /* Number of paragraphs per bucket */
  66  short prog_low_pa;  /* The Paragraph number of the lower
  67                         bound on the sample area */
  68  short prog_high_pa; /* The Paragraph number of the upper
  69                         bound on the sample area */
  70  short dos_pa;       /* The Paragraph number of the I/O DOS
  71                         boundry */
  72
  73 /* When the clock interrupts the current segment is computed
  74 from the CS:IP.  If this is below dos_pa it is an I/O hit,
  75 if between dos_pa and prog_low_pa it is a DOS hit, if between
  76 prog_low_pa and prog_high_pa the appropriate bucket number
  77 is computed and that bucket count is incremented, if above
  78 prog_high_pa then it is a high hit.  */
  79
  80  short hit_io;       /* I/O bucket */
  81  short hit_dos;      /* DOS bucket */
  82  short hit_high;     /* Above program bucket */
  83 };
  84
  85 short buckets[bucket_num];
  86 /* The buckets *****NOTE: You can't declare it this way
  87 (bucket_num is a variable), the size of this area is
  88 determined by the value of bucket_num in the fixed header
  89 */
  90