home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / c / profil.arc / PROFILE.MAN < prev    next >
Text File  |  1989-09-04  |  11KB  |  230 lines
  1. PROFILE(1)        MS-DOS Programmer's Manual         PROFILE(1)
  2.  
  3. NAME
  4.    profile - execution time statistics collector
  5.  
  6. SYNOPSIS
  7.    profile [-adin0] [-#<n>] [-m<mapfile>] [-o<outfile>] <cmdline>
  8.  
  9. DESCRIPTION
  10.    Profile(1) executes a DOS command and gathers information about where in
  11.    the program the execution time is spent. After the command has terminated,
  12.    profile(1) writes a report file where the data is presented.
  13.  
  14.    Current implementations of profile(1) requires that the program under test
  15.    is linked with the MicroSoft LINK or the Borland TLINK linkers, and that a
  16.    standard format map file (as produced by the above linkers) was generated.
  17.    The link command for TLINK must contain the options '/l/c', and for the MS
  18.    LINK linker, the '/MAP' option must be specified.
  19.  
  20.    Normally, profile(1) assumes a linker map file with the same name as the
  21.    executable file (including any pathes) but with the extension '.MAP' in-
  22.    stead of '.EXE'. By default the output file has the same name as the '.EXE'
  23.    file, but with extension '.PRF'. Both these conventions can be overridden.
  24.  
  25.    The profiler will present it's output data summary based on the information
  26.    about public function names and addresses described by the linker map file.
  27.    If the map file is out of date, profiling results may be incorrect. Fur-
  28.    thermore, the profiler only displays public functions. One way to ensure
  29.    that interesting symbols in 'C' programs are public is to temporarily in-
  30.    sert the line
  31.  
  32.        #define    static
  33.  
  34.    at the head of all interesting 'C' modules (this may in some cases cause
  35.    multiple definition errors in the link stage, if different functions and
  36.    variables have the same names in different modules).
  37.  
  38.    In cases where lengthy execution of a command is needed to produce relia-
  39.    ble statistics, an option is available to make the profiled command run
  40.    multiple times.
  41.  
  42.    Profile(1) will not process '.COM' files.
  43.  
  44. INTERNAL FUNCTIONING
  45.    Profile(1) works by first reading the linker map file and collect all the
  46.    function name and address information in memory. It then find out where in
  47.    the physical memory the executable will be loaded, and adjusts table infor-
  48.    mation according to this. Next, it installs it's own handler function for
  49.    for the PC real-time clock interrupt, and loads and executes the program.
  50.    Each time a real-time clock interrupt occurs, the interrupt handler will
  51.    record in which function the CPU was executing. This continues until the
  52.    profiled program terminates. Profile(1) then uninstalls the interrupt
  53.    handler and formats and outputs the results.
  54.  
  55.    All functions described in the map file are classified either as 'intrinsic
  56.    functions' or 'user functions', according to their names: intrinsic func-
  57.    tions are those whose names start with '__', or which contain the charac-
  58.    ters '@' or '$'. All other functions are considered user functions. Apart
  59.    from the functions described in the map file, other interesting memory
  60.    areas are also defined:
  61.  
  62.        'Low Mem'       from 0 to 0x3ff
  63.     'DOS'          from 0x400 to the beginning od the profile itself
  64.     'Profiler'      from the beginning to the end of the profiler
  65.     'EGA BIOS'      from 0xc0000 to 0xc7fff
  66.     'Fixed Disk BIOS' from 0xc8000 to 0xeffff
  67.     'System ROM'      from 0xf0000 to 0xfe000
  68.     'System BIOS'      from 0xfe000 to 0xfffff
  69.  
  70. OUTPUT LISTING FORMAT
  71.    By default, DOS areas and intrinsic functions will not be listed in the
  72.    output report (this can be overridden). Below is an excerpt of a typical
  73.    report:
  74.  
  75.    Function name          Addr      Total    Disp    User
  76.  
  77.    _fclose               41b1c       0.32   50.00   50.00
  78.    _daylight             4a41e       0.00    3.00    3.00
  79.    _edata                4a826       0.00    3.00    3.00
  80.    _end                  4ab60       0.00    3.00    3.00
  81.    _exit                 416fa       0.00    2.00    2.00
  82.    _flushall             41c02       0.00    2.00    2.00
  83.    _fopen                41c46       0.00    1.00    1.00
  84.    _fprintf              41c7e       0.00    0.50    0.50
  85.    _main                 402e0       0.00    0.50    0.50
  86.      ...                  ...         ...     ...     ...
  87.    _timezone             4a41a       0.00    0.40    0.40
  88.    _tzname               4a420       0.00    0/30    0.30
  89.    FIARQQ                50112       0.00    0.10    0.10
  90.    FICRQQ                41112       0.00    0.01    0.01
  91.  
  92.    Statistics based on    309 hits
  93.  
  94.    As can be seen, functions are sorted according to their frequency of occu-
  95.    rence, and secondary by their name. They can also be sorted primarily ac-
  96.    cording to name or execution address. The first column gives name of the
  97.    function, and the second it's address at this particular instance of execu-
  98.    tion. Next is the percentage of each function related to total time, i.e.
  99.    if one adds up all DOS, intrinsic and user function percentages in this
  100.    column, the result will be 100. If DOS and intrinsics are not listed, the
  101.    total will be less than 100%.
  102.  
  103.    In the second column, the percentages relative to all DISPLAYED functions
  104.    are shown. In the third, the percentages relative to all USER functions
  105.    are listed. The two latter columns should always add up very closely to
  106.    100% (the sum may not be exact due to rounding errors).
  107.  
  108.    Functions that did not get any hits are not displayed by default. However,
  109.    you can force them to appear in the output listing by giving the '-0'
  110.    option in the command line.
  111.  
  112.    In the last line is shown the total number of real-time clock interrupts
  113.    that occured during profiling. This value should be as large as possible,
  114.    otherwise it means the statistics is based on too little input data. See
  115.    the '#' option below to make multiple runs of the same command to increase
  116.    the statistical reliability of the data.
  117.  
  118.    In the example above, it can be seen that of the displayed functions, half
  119.    the time (50%) was spent in the _fclose function. Since _fclose is also
  120.    classified as a user function, the value is the same in the third column.
  121.    But only 0.32% of the total time was spent in _fclose, indicating that most
  122.    of the program's execution time is spent doing system calls into DOS or
  123.    other system resources. To find out, one could include DOS and intrinsic
  124.    functions in the output listing by using the '-d' and/or '-i' options.
  125.  
  126. OPTIONS
  127.    -a        Sort the output list in order of execution address, and not
  128.            by frequency.
  129.    -d        Include DOS and BIOS areas, and the profiler itslef, in the
  130.            output list.
  131.    -i        Include intrinsic functions in the output list.
  132.    -n        Sort the output list in order of function name, and not by
  133.            frequency.
  134.    -0        Normally functions that did not get any hits during execution
  135.            are not listed in the output. The '-0' option causes them to
  136.         be listed.
  137.    -#<n>    Execute the profiled command <n> times to increase the relia-
  138.            bility of the statistics (default 1).
  139.    -m<mapfile>    Read the linker map from file <mapfile>. The default is the
  140.            same name as the executable, but with extension '.MAP'.
  141.    -o<outfile>    Write output data to file <outfile>. The default is the same
  142.            name as the executable, but with extension '.OUT'.It is poss-
  143.         ible to write the data directly to 'CON' or to the printer
  144.         device.
  145.    <cmdline>    The normal command line for the profiled command. Note that
  146.            profile(1) will not follow the DOS 'PATH' environment variable
  147.         to find the executable file. If you want to profile a command
  148.         that is in another directory, the explicit path to it must be
  149.         supplied. But the '.exe' extension should NOT be specified.
  150.  
  151.         Example:
  152.  
  153.         C> profile ..\tst\tester junk <cr>
  154.  
  155.         will profile the 'tester.exe' program in directory /..\tst'.
  156.         Note that in this example, the map file is assumed to be in
  157.         the '..\tst' directory too, and the profiler output file will
  158.         also be written to that directory.
  159.  
  160. SPECIAL OPTIONS, NOT NORMALLY USED
  161.    -?        Report the memory address of profile(1)'s own PSP and main()
  162.            function. Used only during development of profile(1).
  163.    -$        Report the memory address of the first free memory (approxi-
  164.            mately where the profiled command will be loaded). Used only
  165.         during development of profile(1). '-$' also causes more infor-
  166.         mation to be included in the output listing.
  167.  
  168. DIAGNOSTICS
  169.     Illegal command line option: `x'
  170.     No command specified for profiling
  171.     Cannot find executable `x'
  172.     `x' is a directory
  173.     Cannot find linker map file `x'
  174.     Output file `x' is write-protected
  175.     Invalid map file format in `x'
  176.     Insufficient memory for function tables
  177.     Not enough function table slots
  178.     Cannot open output file `x'
  179.     Insufficient memory to execute command
  180.     Error executing command `x'
  181.     Invalid EXE file format in `x'
  182.     Program ran too fast - no hits!
  183.  
  184. BUGS
  185.    The method for finding out the address where the profiled command will be
  186.    loaded is compiler specific (to the compiler used to compile profile(1)).
  187.  
  188.    It involves giving the command
  189.  
  190.        C> profile -$ profile -? <cr>
  191.  
  192.    These two (!) instances of profile will produce some special output. The
  193.    one which EXECUTES the other will show what memory address it thinks is the
  194.    lowest free one. The one which IS EXECUTED by the other will report the
  195.    address of it's own Program Segment Prefix and main() function. Naively,
  196.    the two values would be expected to be the same, but they are not.
  197.  
  198.    The discrepancy should be added during the adjustment of function addresses
  199.    to actual execution values. This is a nuisance. The values may even be dif-
  200.    ferent if you change the source code using the same compiler, so if you mo-
  201.    dify profile(1) you should check the address of the real executing main()
  202.    function and the assumed address for it and check that the values agree
  203.    after each change to the sources.
  204.  
  205.    It could be considered to have some kind of regular expression format, per-
  206.    haps read from a specification file, that tells what functions should be
  207.    included in or excluded from the output report.
  208.  
  209.    Other bugs? No doubt!
  210.  
  211. NOTES
  212.    The writing of this command was inspired by a profiler distributed on Use-
  213.    Net by Diomidis Spinellis. Although his profile is very well written and
  214.    performs as described, it has two shortcomings. One is that the profiled
  215.    program has to be modified with a call to a special function that is linked
  216.    into it. Second, and much more serious: if you break out of the profiled
  217.    program with CTRL-C, the interrupt handler will not be restored, and as
  218.    soon as the memory used for it is overwritten by another command, the PC
  219.    dies immediately.
  220.  
  221.    This profile(1) does noit suffer from these problems (but possibly from
  222.    many others...). Although I have taken some ideas from Diomidis' version,
  223.    most of this one is original work. It is hereby placed in the public do-
  224.    main.
  225.  
  226.    Author: Bjorn Larsson        uucp: bl@infovox.se
  227.           Ynglingagatan 5, IV
  228.        S-113 47 Stockholm
  229.        SWEDEN
  230.