home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_200 / 259_01 / profile.doc < prev    next >
Text File  |  1988-02-25  |  13KB  |  358 lines
  1.  
  2.              PRF - An Application Profile Package
  3.              ====================================
  4.  
  5.  
  6.     PRF is an application profile package which may be used to enhance
  7.     the performance of your 'C' language programs developed under MSDOS
  8.     on an IBM/PC or 100% compatible system.
  9.  
  10.     In general, it is very desirable to have an application program
  11.     execute as fast as possible.  After a program is written and tested
  12.     most programmers go back over the code "one more time" looking for
  13.     areas where the program can be made more efficient.  Obviously,
  14.     improving the performance of an area of the program which is
  15.     executed many times will increase overall performance more than an
  16.     area which is seldom executed.  However, in most large programs it
  17.     is very difficult to guess where the program is spending most of
  18.     its time.  This is where PRF comes into play.  PRF will execute
  19.     along with your program and check on the areas where most of the
  20.     time is being spent.  This allows you to then go back an examine
  21.     these areas for performance improvements.
  22.  
  23.                   Utilities Included
  24.                   ------------------
  25.  
  26.     The following utilities are included in this package:
  27.  
  28.     TIMER.C        A general purpose program timer.  This utility
  29.     TIMER.EXE       can be used without PRF simply to time the
  30.                execution of one of your programs.  Running
  31.                TIMER on a program before and after making
  32.                modifications will tell you how much (if any)
  33.                performance improvement resulted from your
  34.                changes.
  35.  
  36.     MAKEPRF.C       A utility to build a PRF symbol file from the
  37.     MAKEPRF.EXE       information contained in a .MAP file created
  38.                by your linker.  This symbol file is then used
  39.                to monitor the execution of your program and
  40.                report the results.
  41.  
  42.     PRFRPT.C       A reporting utility which will read the output
  43.     PRFRPT.EXE       of a profile session (a .PR1 file) and format
  44.                a report of the results.
  45.  
  46.     CPROFILE.C       The 'C' language portion of the PRF runtime
  47.                module.  This module should be compiled and
  48.                placed in a library where it can automatically
  49.                be picked up as needed by your linker.
  50.  
  51.     APROFILE.ASM       The assembly language portion of the PRF
  52.     APROFILE.OBJ       runtime module.  This module should be placed
  53.                in a library where it can automatically be
  54.                picked up by your linker.
  55.  
  56.               Preparing Your Source Code
  57.               --------------------------
  58.  
  59.     Since the runtime portion of PRF is linked into your .EXE module,
  60.     there are several minor changes you must make to your source code
  61.     to run a profile session.  As mentioned above, PRF obtains all the
  62.     information about your program from the .MAP file produced by the
  63.     linker.  Functions in your code which are declared as "static" will
  64.     NOT be included in the .MAP and PRF will not know about them.
  65.     Therefore, when using PRF all functions in your code should be
  66.     declared public (i.e. not static). Having static modules in the
  67.     program you are running PRF with can distort the statistics for
  68.     those modules which are public.  To avoid this, code all your
  69.     static routines as follows:
  70.  
  71.        #define STATIC         static
  72.  
  73.        STATIC void my_func()
  74.  
  75.     Then when you want to run PRF change the #define STATIC to remove
  76.     the "static" declaration as follows:
  77.  
  78.        #define STATIC
  79.  
  80.     Before running a profile session:
  81.  
  82.     1) Function StartProfile("MYPROG"); should be called at the point
  83.        you want the profile operation to start.  The parameter (MYPROG
  84.        in this example) should be the name of the .MAP file created by
  85.        your linker.  In general, this will be the same root name as
  86.        that of the .EXE file.
  87.  
  88.     2) Function EndProfile(); should be called at the point you wish
  89.        to halt the profile operation.
  90.  
  91.     Usually StartProfile() will be called as the first statement in
  92.     main() and EndProfile() will be called as the last statement before
  93.     program termination.
  94.  
  95.     After making these changes all modules of your program should be
  96.     re-compiled.  If you desire line number statistics be sure to
  97.     include the switch to inform your compiler to generate line number
  98.     information in the .OBJ file.  Once you've compiled all modules of
  99.     your application with "line numbers" link your program.  Be sure
  100.     to use linker switches /MAP (and /LINE if you want line numbers) to
  101.     generate a .MAP file.
  102.  
  103.  
  104.              Sample Session - Microsoft C
  105.              ----------------------------
  106.  
  107.     The following sample session shows the steps required to profile an
  108.     application we will call MYPROG which consists of modules MYPROG.C,
  109.     MYUTIL.C, and MYINIT.C.
  110.  
  111.     1) Edit MYPROG.C and add StartProfile("myprog"); as the first
  112.        statement in main().  Add EndProfile() as the last statement
  113.        in main().
  114.  
  115.     2) Compile the programs:
  116.        cl /c /Zd myprog.c
  117.        cl /c /Zd myutil.c
  118.        cl /c /Zd myinit.c
  119.  
  120.     3) Link the program producing a .MAP file (We are assuming that
  121.        the PRF code resides in library PRF.LIB):
  122.        link /map /line myprog myutil myinit,,,prf;
  123.  
  124.     4) Create a profile symbol table file (this produces a .PRF file):
  125.        makeprf myprog
  126.  
  127.     5) Run the program (this produces the .PR1 file):
  128.        myprog myparms
  129.  
  130.     6) Read the .PR1 file and produce profile report:
  131.        prfrpt myprog
  132.  
  133.  
  134.                Sample Session - Borland Turbo C
  135.                --------------------------------
  136.  
  137.     The following sample session shows the steps required to profile an
  138.     application we will call MYPROG which consists of modules MYPROG.C,
  139.     MYUTIL.C, and MYINIT.C.
  140.  
  141.     1) Edit MYPROG.C and add StartProfile("myprog"); as the first
  142.        statement in main().  Add EndProfile() as the last statement
  143.        in main().
  144.  
  145.     2) Compile the programs:
  146.        tcc -y myprog.c
  147.        tcc -y myutil.c
  148.        tcc -y myinit.c
  149.  
  150.     3) Link the program producing a .MAP file (We are assuming that
  151.        the PRF code resides in library PRF.LIB):
  152.        tcc -ml myprog.obj myutil.obj myinit.obj prf.lib
  153.  
  154.     4) Create a profile symbol table file (this produces a .PRF file):
  155.        makeprf myprog
  156.  
  157.     5) Run the program (this produces the .PR1 file):
  158.        myprog myparms
  159.  
  160.     6) Read the .PR1 file and produce profile report:
  161.        prfrpt myprog
  162.  
  163.                 Reading the PRF Report
  164.                 ----------------------
  165.  
  166.     Following is a sample of the report produced by PRFRPT.EXE.  Due
  167.     to the length of this particular report some portions have been
  168.     removed from this listing.
  169.  
  170.        Segment: _TEXT  Length: 18661 (48E5h)
  171.  
  172.       Public Symbols   Count  Tot%    Hit%
  173.  
  174.      DGROUP@         538   1.2     2.9  *
  175.      _ShowListBox           1   0.0     0.0
  176.      _ScrollWindow           1   0.0     0.0
  177.      _ShowInvertRect       1   0.0     0.0
  178.      _main               8   0.0     0.0
  179.      SCRCLEARRECT          11   0.0     0.1
  180.      SCRINVERTATTR        2254   5.1    12.2  ****
  181.      SCRINVERTBUFFER    2899   6.5    15.6  ******
  182.      _brk               2   0.0     0.0
  183.      _free              23   0.1     0.1
  184.      _getch            1   0.0     0.0
  185.      _getdate        4381   9.8    23.6  *********
  186.      _gettime         147   0.3     0.8
  187.      _int86          288   0.6     1.6
  188.      _int86x         861   1.9     4.6  *
  189.      _IOERROR         212   0.5     1.1
  190.      _LONGTOA           6   0.0     0.0
  191.      LXMUL@          794   1.8     4.3  *
  192.      _malloc          20   0.0     0.1
  193.      _memcpy           2   0.0     0.0
  194.      _movedata         323   0.7     1.7
  195.      _movmem           3   0.0     0.0
  196.      _segread         218   0.5     1.2
  197.      _setvbuf           1   0.0     0.0
  198.      _time            4244   9.5    22.9  *********
  199.      _strcpy           4   0.0     0.0
  200.      _strlen           6   0.0     0.0
  201.      _dostounix         421   0.9     2.3
  202.      _VPRINTER          14   0.0     0.1
  203.  
  204.      Line number statistics for module WINDEMO.C
  205.  
  206.         Line Number    Count  Tot%    Hit%
  207.  
  208.          26         526   1.2     2.8  *
  209.          53           1   0.0     0.0
  210.          76           2   0.0     0.0
  211.          91           2   0.0     0.0
  212.         141           7   0.0     0.0
  213.         164           1   0.0     0.0
  214.         218           1   0.0     0.0
  215.         247           1   0.0     0.0
  216.  
  217.      Line number statistics for module LISTBOX.C
  218.  
  219.         Line Number    Count  Tot%    Hit%
  220.  
  221.          72           2   0.0     0.0
  222.          76           2   0.0     0.0
  223.          77           2   0.0     0.0
  224.          94           2   0.0     0.0
  225.         169           1   0.0     0.0
  226.         181           1   0.0     0.0
  227.         191           1   0.0     0.0
  228.         209           1   0.0     0.0
  229.         224           1   0.0     0.0
  230.  
  231.      Line number statistics for module WIN.C
  232.  
  233.         Line Number    Count  Tot%    Hit%
  234.  
  235.          63           4   0.0     0.0
  236.          65          18   0.0     0.1
  237.          67           4   0.0     0.0
  238.          68           4   0.0     0.0
  239.          83           6   0.0     0.0
  240.          85           2   0.0     0.0
  241.         122           3   0.0     0.0
  242.         124           3   0.0     0.0
  243.         126           3   0.0     0.0
  244.         129           3   0.0     0.0
  245.         131           5   0.0     0.0
  246.         132           3   0.0     0.0
  247.         256           1   0.0     0.0
  248.         280           1   0.0     0.0
  249.         284           3   0.0     0.0
  250.  
  251.      Line number statistics for module SCRIO.C
  252.  
  253.         Line Number    Count  Tot%    Hit%
  254.  
  255.          82           2   0.0     0.0
  256.          86           2   0.0     0.0
  257.         100           1   0.0     0.0
  258.         121          15   0.0     0.1
  259.         122           6   0.0     0.0
  260.         124           3   0.0     0.0
  261.         141          11   0.0     0.1
  262.         142           3   0.0     0.0
  263.         163           3   0.0     0.0
  264.         166           4   0.0     0.0
  265.         168           4   0.0     0.0
  266.         186         313   0.7     1.7
  267.         190         320   0.7     1.7
  268.         191         326   0.7     1.8
  269.         192        1008   2.3     5.4  **
  270.         193         287   0.6     1.5
  271.         213        2899   6.5    15.6  ******
  272.         231          14   0.0     0.1
  273.  
  274.           21673 Hits in MS-DOS
  275.            2673 Hits in ROM BIOS
  276.           18531 Hits in Application Pgm
  277.            1738 Other hits
  278.           44615 Total hits recorded
  279.  
  280.     The report produced by PRFRPT.EXE is contains a section devoted to
  281.     each code segment in your program. This section begins with the
  282.     name and length of the segment.
  283.  
  284.     For each code segment a listing of all public symbols which were
  285.     found to be using time by PRF are listed.  The public symbols are
  286.     reported as follows with a histogram of the "Hit%" shown to the
  287.     right of the statistics.
  288.  
  289.     Public Symbols         - The name of the public routine which
  290.                    contained "hits".
  291.  
  292.     Count             - Total number of hits recorded for this
  293.                    public routine.
  294.  
  295.     Tot%             - Percentage of time this routine used
  296.                    relative to all of the hits recorded.
  297.                    This includes hits that occurred outside
  298.                    of the application program and are,
  299.                    in general, out of the application
  300.                    programmers control.
  301.  
  302.     Hit%             - Percentage of time this routine used
  303.                    relative to the hits recorded within
  304.                    the application code.
  305.  
  306.     If the .MAP file included line number information, additional
  307.     statistics are generated for each source code module for which line
  308.     number information is found.  The statistics for line numbers are the
  309.     same as those for public symbols with the exception that the actual
  310.     source code line number replaces the public symbol name.
  311.  
  312.                  How PRF Works
  313.                  -------------
  314.  
  315.     The runtime portion of PRF uses the clock timer interrupt to get control
  316.     of the system at frequent intervals and examines the CS:IP registers of
  317.     the interrupted code to record a "hit".  Under normal conditions the
  318.     clock timer interrupt is invoked 18.2 times a second.  In order to get
  319.     a better resolution of the running application, PRF speeds up the system
  320.     timer to produce interrupts 582.4 times per second.  This frequency of
  321.     interrupts gives a much better view of the sections of the program which
  322.     are using time.  As usual, however, there is a trade off involved here.
  323.     The more frequently your program is interrupted to "record a hit", the
  324.     slower (elapsed time) your program will run.  You can increase or
  325.     decrease this interrupt frequency in module APROFILE.ASM by setting
  326.     the equates TIMER_INT_CNT and TIMER_INT_WORD.  APROFILE.ASM contains
  327.     a table listing the valid values of these equates. Note that PRF calls
  328.     the ROM BIOS clock interrupt 18.2 times per second no matter how often
  329.     PRF is recording hits.  This assures that your system clock remains
  330.     accurate and is not "speeded up" during a PRF session.
  331.  
  332.                  Development Compilers
  333.                  ---------------------
  334.  
  335.     This code was developed and tested under the following compilers.
  336.  
  337.  
  338.               Borland Turbo-C V1.0
  339.               Microsoft Quick-C V1.0
  340.               Microsoft C V5.00
  341.               Microsoft C V4.00
  342.  
  343.                   Disclaimer
  344.                   ----------
  345.  
  346.     This package has been released into the public domain by the author.
  347.     It is non-supported software and you use it at your own risk.  I have
  348.     tested this package and to the best of my knowledge it contains no
  349.     errors.  However, I do not guarantee that it is error free.
  350.  
  351.     Comments, suggestions, questions, and constructive criticism are
  352.     welcomed by the author:
  353.  
  354.                 Bob Withers
  355.                 649 Meadowbrook St.
  356.                 Allen, Texas   75002
  357.  
  358.