home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / diagnostic / hierprof_2 / !HierProf / !Help < prev    next >
Text File  |  1995-11-10  |  11KB  |  396 lines
  1.  
  2.     HierProf 2.06 - Hierachical profiling for C programs
  3.     ••••••••••••••••••••••••••••••••••••••••••••••••••••
  4.  
  5.  
  6.  
  7. Contents
  8. ————————
  9.  
  10. Introduction
  11. How to use HierProf
  12. Contents of the '!HierProf' application-directory
  13. How HierProf works
  14. Manual control of profiling
  15. Timing overheads and restrictions
  16. Use with C++
  17. System variables used/changed
  18. Other things
  19.  
  20.  
  21.  
  22. Introduction
  23. ————————————
  24.  
  25.     The !HierProf application-directory contains a C library and C
  26.     preprocessor which can be used to add time-profiling of
  27.     functions to any C program.
  28.     
  29.     The profiling output is a full hierachical listing of the time
  30.     spent in each function, so you get told how much time was spent
  31.     in function X as percentages of the amount of time spent in all
  32.     other functions that indirectly or directly called X.
  33.     
  34.     For example, here is part of the profiling output from one of
  35.     the programs in the '!HierProf.Examples' directory:
  36.     
  37.        1   Outermost loop                                               
  38.        2   *   99.60%   main                                            
  39.        3       84.98%   *   85.32%   FunctionC                          
  40.        4        0.79%        0.79%   *    0.93%   NullFunction          
  41.        5       60.47%       60.71%   *   71.16%   FunctionA             
  42.        6       30.43%       30.56%       35.81%   *   50.33%   FunctionD
  43.        7       10.67%       10.71%   *   12.56%   FunctionB             
  44.     
  45.     The '*' indicate direct calls, to help you to follow the
  46.     tree-structure.
  47.     
  48.     HierProf works by preprocesing C source code to make calls to
  49.     special timing functions at the start and end of each function.
  50.     This is done by compiling with HierProf's cc-frontend program,
  51.     'HierProfCC', and linking with the HierProf library. This is
  52.     very straightforward - see the next section for the details.
  53.     
  54.     By default, the profiling output is sent to stderr when the
  55.     program finishes, using atexit(). There are functions to send 
  56.     the output to temporary files etc instead.
  57.     
  58.     Demonstration versions of HierProf will ignore any nested function 
  59.     calls beyond 5 levels. The full version copes with up to 62 
  60.     levels.
  61.     
  62.     
  63.  
  64.  
  65.  
  66.  
  67. How to use HierProf
  68. ———————————————————
  69.  
  70.     To make a profiled version of a project, do the following:
  71.     
  72.     
  73.     1)    Ensure that the '!HierProf' application-directory has
  74.         been seen by the Filer.
  75.     
  76.     2)    Compile each C source file by calling 'HierProfCC'
  77.         rather than your normal compiler, passing the full call
  78.         to your compiler as the arguments to HierProfCC.
  79.     
  80.     3)    Link with 'HierProf:o.HPLib'.
  81.     
  82.     
  83.     For example, if you normally build with:
  84.     
  85.         cc -c -I,C: -o o.main c.main
  86.         link -o !RunImage o.main C:o.Stubs
  87.     
  88.     then to include function profiling, do:
  89.     
  90.         HierProfCC cc -c -I,C: -o o.main c.main
  91.         link -o !RunImage o.main HierProf:o.HPLib C:o.Stubs
  92.     
  93.     (Desktop C users should use HierProf:o.HP4Lib)
  94.     
  95.     The 'HierProfCC' command is in the '!HierProf.Bin.' directory,
  96.     which is automatically added to your run-path by
  97.     '!HierProf.!Boot'.
  98.     
  99.     
  100.     
  101.     Examples
  102.     ¨¨¨¨¨¨¨¨
  103.     
  104.     The '!HierProf.Example' directory contains two example projects
  105.     with makefiles that can be used to make normal or profiled
  106.     versions of the project. 
  107.     
  108.     This is done in the makefiles by prefixing the command 'cc' 
  109.     with '$(HierProfCC)'. This AMU macro is not defined in the 
  110.     makefile, so normaly reduced to nothing. To build a profiled 
  111.     version, the makefile is simply called with:
  112.     
  113.         Amu ... HierProfCC=HierProfCC
  114.     
  115.     
  116.     Minor restrictions when using HierProfCC
  117.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  118.     
  119.     HierProfCC has a small restriction compared to a normal C
  120.     compiler - it will only process one .c file in the command line
  121.     parameters, so you will have to compile multiple .c files
  122.     individually.
  123.     
  124.     You should ensure that the C source code will compile ok without
  125.     HierProcCC, because HierProfCC will not be particularly helpful
  126.     if it can't parse the C source.
  127.     
  128.     HierProfCC can fail to correctly parse C source code which omits
  129.     white space between a ')' and a '{'.
  130.     
  131.  
  132.  
  133.  
  134. Contents of the '!HierProf' application-directory
  135. —————————————————————————————————————————————————
  136.  
  137.  
  138.     Some of the following (eg source code) may not be included in
  139.     the distribution.
  140.     
  141.     
  142.     !HierProf.
  143.     
  144.         !Help    This file
  145.         
  146.         History    Some info on HierProf development.
  147.         
  148.         !Boot    Sets HierProf$Dir and HierProf$Path
  149.             Sets Alias$HierProfCC
  150.             Creates the directory <Wimp$ScrapDir>.HierProf.c
  151.             
  152.         !Run    Runs !Boot and opens !Help.
  153.         
  154.         
  155.         o.    
  156.             HPLib    Library to link with profiled programs. 
  157.                 This contains all the time-measuring 
  158.                 code etc.
  159.             
  160.             HP4Lib    As above, except compatible with Acorn's
  161.                 Desktop C (C5 uses new stubs symbols).
  162.             
  163.             HPLibDebug    A version of the HierProf 
  164.                     library which outputs 
  165.                     diagnostics.
  166.             
  167.             Sources.    Source code for HPLib
  168.             
  169.         
  170.         h.
  171.             HierProf    Header file for HPLib. Contains
  172.                     #defines for HierProf_Start etc,
  173.                     and declarations for the 
  174.                     functions in HPLib
  175.             
  176.         
  177.         Bin.
  178.             HierProfCC    Frontend to any C compiler,
  179.                     which adds profile calls to C
  180.                     source code before compilation.
  181.             
  182.             HPCCDebug    HierProfCC compiled with
  183.                     debugging enabled.
  184.             
  185.             Sources.    Source code for HierProfCC
  186.         
  187.         
  188.         Examples.
  189.         
  190.             Simple.        This contains an example C
  191.                     project which can be compiled
  192.                     for normal or profiling use.
  193.                     
  194.                 c.        C source code.
  195.                 h.
  196.                 Makefile.
  197.             
  198.                 !Normal.    Directory containing
  199.                         normally-compiled .o
  200.                         files etc.
  201.                         Double-clicking this
  202.                         directory will (re)build
  203.                         the project.
  204.                                                 
  205.                     RunProg This runs the program.
  206.                     
  207.                 !HierProf.    Directory containing 
  208.                         .o files compiled for
  209.                         profiling.
  210.                         Double-clicking this
  211.                         directory will (rebuild
  212.                         the project.
  213.                         
  214.                     RunProg This runs the program.
  215.             
  216.             
  217.             Recursive.    Another example C project which
  218.                     tests HierProf on recursive 
  219.                     functions.
  220.                 
  221.         
  222.         HierProf    A StrongHelp manual for the HierProf
  223.                 header file.
  224.  
  225.  
  226.  
  227.  
  228.  
  229. How HierProfCC works
  230. ————————————————————
  231.  
  232.     HierProfCC first makes an altered version of the C source file
  233.     it is given, and saves it as '<Wimp$ScrapDir>.HierProf.c.main'.
  234.     It then calls cc (or whatever HierProfCC's first parameter is)
  235.     by sending the string of its arguments to the
  236.     command-line-interpreter.
  237.     
  238.     HierProfCC adds some macros to the source-code at the start and
  239.     end of every function. These macros are defined in the header
  240.     file 'HierProf:HierProf.h', and call functions in the C libraray
  241.     'HierProf:o.HPLib' which store and calculate time intervals. 
  242.     
  243.     HierProf will also add a '#include "HierProf.h"' line to the
  244.     start of the file, and the search path of cc is modified so that
  245.     this header file will be found inside the '!HierProf' directory.
  246.     
  247.     At run-time, when the first HierProf macro is reached, an exit
  248.     handler is registered. When the program finishes, this causes
  249.     the profile output to be printed to stderr. You can change where
  250.     the output goes by calling the various functions declared in
  251.     'HierProf:HierProf.h'. For example, you can send output to a
  252.     filename or a filestream.
  253.     
  254.     You can also tell HierProf to output the data before your
  255.     program has finished. You can send output to one of your own
  256.     functions to display the data in a window if you like, as long
  257.     as the function is similar to fprintf.
  258.     
  259.     The altered version of the C source file is not deleted after it
  260.     has been compiled, so you can have a look at it to get an idea
  261.     of what HierProfCC has done.
  262.  
  263.  
  264.  
  265.  
  266.  
  267. Manual control of profiling
  268. ———————————————————————————
  269.  
  270.     You can manually profile any region of code inside a function by
  271.     adding pairs of the macros 'HierProf_Start( "any text")' and
  272.     'HierProf_Stop()' lines (with no terminating semicolons) around
  273.     the code you want profiled.
  274.     
  275.     These macros will be removed unless compilation is with
  276.     HierProfCC, but you have to explicitly '#include
  277.     "HierProf:HierProf.h"' in your source code for this to work.
  278.     
  279.     You can also make HierProfCC ignore a function by putting
  280.     'HierProf_DontProfile()' immediately after the opening '{' of
  281.     the function.
  282.     
  283.     For example:
  284.     
  285.     int FunctionWeDontWantToProfile( int x)
  286.     {
  287.     HierProf_DontProfile()
  288.     ...
  289.     }
  290.     
  291.     
  292.     There are various functions which can be used to control where 
  293.     profiling is sent to, in 'HierProf:HierProf.h'.
  294.  
  295.  
  296.  
  297.  
  298. Timing overheads and restrictions
  299. —————————————————————————————————
  300.  
  301.     As you may have been thinking, two function calls per profile
  302.     block is going to give a hefty overhead for each profiled block.
  303.     On my 25MHz A5000, this overhead is around 0.15 ms. Hence
  304.     programs compiled with HierProfCC will run rather slowly.
  305.     
  306.     HierProf meausures how long is spent in its start/stop
  307.     functions, and uses this information to correct (as much as
  308.     possible) the timing information.
  309.     
  310.     The actual timing is done with the ANSI C 'clock()' function.
  311.     This has a resolution of 1/100th of a second in RISC OS. Usually
  312.     however, you will be looking at functions that are called many 
  313.     times, so the average time calculated by HierProf will be much 
  314.     more accurate.
  315.     
  316.     You can't have more than 255 different profiled functions or
  317.     blocks. This limitation may be removed in future.
  318.     
  319.     A maximum of 62 nested function levels are handled - higher
  320.     nestings are ignored. HierProf will also ignore all but the
  321.     initial call to a recursive function (including mutually
  322.     recursive functions).
  323.  
  324.  
  325.  
  326.  
  327. Use with C++
  328. ————————————
  329.  
  330.     I've made a few tweaks so that HierProf semi-works with C++
  331.     code and Acorn's C++ compiler 5.06, but this hasn't been tested
  332.     very much. 
  333.     
  334.     Only class-method names are noticed by the source parser, so
  335.     'SomeClass::dosomething(...)' will appear as 'dosomething' in
  336.     the profile output. Similarly, parameter types are ignored.
  337.     
  338.     Owing to the way HierProf works though, methods with the same
  339.     names in different classes will still be individually profiled, 
  340.     even though they have the same name in the output.
  341.     
  342.     Converted C++ files are put into '<Wimp$ScrapDir>.HierProf.c++.'
  343.     - Acorn C++ 5.06 doesn't cope very well with files inside .c
  344.     directories.
  345.     
  346.     Because of (what I think is) a bug in Acorn C++ 5.06, HierProf
  347.     has to use the leafname of the input file as the temporary
  348.     leafname when the input file is in a c++ directory - C++ 5.06
  349.     seems to ignore any -o directive, and always uses the input
  350.     source leafname as the output leafname. This will result in
  351.     '<Wimp$ScrapDir>.HierProf.c++.' filling up with old converted
  352.     files.
  353.  
  354.  
  355.  
  356.  
  357. System variables used/changed
  358. —————————————————————————————
  359.  
  360.     When seen by the Filer, the '!HierProf' application directory
  361.     affects the following system variables:
  362.     
  363.     Run$Path    ('HierProf:Bin.' is added)
  364.     HierProf$Dir
  365.     HierProf$Path
  366.     
  367.     (C$Path is not changed)
  368.     
  369.     Also, the directories <Wimp$ScrapDir>.HierProf.c/c++ are
  370.     created.
  371.  
  372.  
  373.  
  374.  
  375.  
  376. Other things
  377. ————————————
  378.  
  379.     Please feel free to contact me at the address below if you have
  380.     any problems, queries or suggestions.
  381.     
  382.     All the HierProf files are Copyright © Julian Smith 1995.
  383.  
  384.  
  385.  
  386.  
  387. - Julian Smith
  388.  
  389.  
  390.  
  391.  ---------------------------------------------------------------------------
  392.  Julian Smith                              Dept of Experimental Psychology
  393.  julian.smith@psy.ox.ac.uk                 South Parks Road, Oxford, OX1 3UD
  394.  http://cogsci1.psych.ox.ac.uk/~julians/   UK
  395.  ---------------------------------------------------------------------------
  396.