                MS-DOS PROGRAM PROFILER
                  FOR .EXE .COM FILES


I. PURPOSE

        The PROFIL program is designed to produce an execution
    profile of MS-DOS 1.25 or  2.00  .EXE  or  .COM  files  on
    8086/8088 systems  which  have a programmable interrupting
    clock.  The method employed is  to  chop  the  program  up
    into   a  sequence  of  "buckets"  and  to  increment  the
    appropriate (based on CS:IP) bucket count when  the  clock
    interrupts.  In  addition  there  are  counters  for  hits
    in the I/O system and the DOS so  some  idea  of  how  I/O
    or DOS  bound  a  program  is.  There is also a bucket for
    hits above the program area, you  might  get  counts  here
    if your program relocates itself, or goes haywire.

        The PROFIL  program  is  not  intended  as an end-user
    program, but rather  as  a  developement  tool.   To  this
    end it  is  not  particularly robust or friendly, but gets
    the job done.  The OEM must write a  PCLOCK  routine  (see
    PCLOCK.ASM) which  implements the hardware dependant clock
    interrupt.  The  implementation  should  be  evident  from
    examining the  source  code,  it  is  quite simple.  There
    is a CLOCKON routine  which  sets  up  a  clock  interrupt
    to  the  CLK_INTER  routine  every  DX  micro  seconds.  A
    CLOCKOFF routine which un-does CLOCKON.  And  a  LEAVE_INT
    routine which  is  responsible  for the actual "IRET" from
    the clock interrupt.  Also see the PROHIST  documentation.

II. USAGE

        The profiler is envoked by uttering:

            PROFIL fname.ext

    where the  filename  is  completly  specified,   including
    extension.  You  will  then  be  prompted  for  the number
    of paragraphs in one bucket.  This number  must  be  >  0,
    based on  this  number  the  number of buckets is computed
    by using the size of the executable file.  Next  you  will
    be  prompted  for  the  clock  interval,  and  lastly  for
    parameters to  the  program.   Type  the  parameters  just
    as if  you  were running the program at the command level.

    NOTE: If  a  "bad"  number  is entered for the bucket size
        or clock interval, you will be reprompted.

        When the program terminates, normally or  by  Cntrl-C,
    PROFIL  will  print  a  termination  message  (similar  to
    debug).  The output file will  be  fname.PRF  where  fname
    is the  same  as  the  file  containing  the program being
    profiled.

III. OUTPUT FORMAT

        The format of the  output  file  is  the  following  C
    type structure.

struct profdata {
 short clock_grain;  /* Clock sample interval in
                        micro-seconds*/
 short bucket_num;   /* The total number of buckets */
 short bucket_siz;   /* Number of paragraphs per bucket */
 short prog_low_pa;  /* The Paragraph number of the lower
                        bound on the sample area */
 short prog_high_pa; /* The Paragraph number of the upper
                        bound on the sample area */
 short dos_pa;       /* The Paragraph number of the I/O DOS
                        boundry */

/* When the clock interrupts the current segment is computed
from the CS:IP.  If this is below dos_pa it is an I/O hit,
if between dos_pa and prog_low_pa it is a DOS hit, if between
prog_low_pa and prog_high_pa the appropriate bucket number
is computed and that bucket count is incremented, if above
prog_high_pa then it is a high hit.  */

 short hit_io;       /* I/O bucket */
 short hit_dos;      /* DOS bucket */
 short hit_high;     /* Above program bucket */
};

short buckets[bucket_num];
/* The buckets *****NOTE: You can't declare it this way
(bucket_num is a variable), the size of this area is
determined by the value of bucket_num in the fixed header
*/
                                                              