home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / utilslib / Profile / Doc < prev    next >
Encoding:
Text File  |  1991-06-02  |  6.1 KB  |  176 lines
  1.  
  2. Execution time profiler for C programs running under RISCOS 2.00
  3. ================================================================
  4. (version 1.00, 04-06-1990)
  5.  
  6. With the -p[x] option Archimedes C programmers are able to see
  7. during program execution how often a function is called. This is
  8. an usefull feature when optimising your code.
  9.  
  10. But sometimes it isn't enough to know how often a function is
  11. called. More interesting is how much time is spend in one
  12. particular function. The function which uses most time is a
  13. candidate for optimising.
  14.  
  15. Unfortunately the Norcroft C 3.00 compiler hasn't a facility to
  16. do execution time profiling, so I had to write it myself.
  17.  
  18.  
  19. How to install it?
  20. ==================
  21.  
  22. Define in your source file where 'main' is defined:
  23.  
  24.      #define EXPRO 1
  25.  
  26. and include then
  27.  
  28.      #include "h.exprofle"
  29.  
  30. Now call as soon as possible in 'main':
  31.  
  32.      exprofle_init("filename");
  33.  
  34. With filename is the file where the execution time profiling
  35. information is written to at the end of program execution.
  36.  
  37. Compile without the -ff option to include functionnames in the
  38. code.
  39.  
  40. After compilation link with the o.exprolib library as the first
  41. library specified.
  42.  
  43.  
  44. How does it work?
  45. =================
  46.  
  47. After calling 'exprofle_init()' the following happens:
  48. - check if running under RISCOS 2.00.
  49. - check if FPEmulator is present and if get its start and end
  50.   address.
  51. - search for all functionnames and save pointers to them.
  52. - intercept the undefined instruction vector with a routine
  53.   that saves the return address.
  54. - register an OS_CallEvery function which is called every 1/100
  55.   of a second.
  56. - register an atexit function.
  57.  
  58. Now the program is interrupted every 1/100 of a second and the
  59. return address is binary searched in an array of functionname
  60. pointers. When the address interval is found a counter for that
  61. function is incremented.
  62. It is possible that the return address lies outside the program
  63. code, i.e. the program is executing some OS routine.
  64. When the program uses floating point arithmetic the return
  65. address could be in the FPEmulator module as well. In that case
  66. the counter for the fpemulator is incremented, and because we've
  67. intercepted the undefined instruction vector we know the address
  68. from where the fpemulator is called. Now this address is binary
  69. searched in the functionpointer array (in this way we can see how
  70. much of the total time is spent with floating point calculations
  71. and at the same time have correct profile values for every
  72. function).
  73. In all other cases we increment the 'greaterthan' entry.
  74.  
  75. When the program exits through 'exit' the execution time
  76. profiling data will be written to the output file.
  77.  
  78. The execution time profiling will be correct in most cases but
  79. you have to be prepared to get some strange results. These
  80. errors are due to the fact that the libraries (Stubs, Ansilib,
  81. RISC_OSlib) are compiled with the -ff option to prevent function
  82. name inclusion.
  83.  
  84. When your program contains pieces of assembly you have to look
  85. after the following points:
  86. - give the code AREA the name: C$$code
  87. - include functionnames as shown below:
  88.  
  89.      foo_X
  90.             DCB     "foo", 0
  91.             ALIGN
  92.      foo_Y
  93.             DCD     &ff000000 + foo_Y - foo_X
  94.  
  95.             EXPORT  foo
  96.      foo
  97.             ect.
  98.  
  99.  
  100. If the program is running under the WIMP environment the
  101. functions: wimp_poll, wimp_pollidle,
  102. wimp_save_fp_state_on_poll and wimp_corrupt_fp_state_on_poll
  103. are rewritten to prevent the interruption of other tasks.
  104. So when linking, o.exprolib has to be earlier in the list of
  105. libraries than o.RISC_OSlib.
  106.  
  107.  
  108. Comments or bug reports may be send to:
  109. =======================================
  110.  
  111.      Ferdinand Oeinck
  112.      Javalaan 25
  113.      9715 GP  Groningen
  114.      The Netherlands
  115.      tel. ++31(0)50 732202
  116.  
  117.  
  118. ------------------------------------------------------------------------------
  119. Added by Paul Moore 02/06/91:
  120.  
  121. Changes introduced for inclusion in my Utils library
  122. ====================================================
  123.  
  124. 1. All internal functions have been renamed, with a prefix of "_profile" in
  125.    place of the previous "expro". This is just cosmetic, and based on my
  126.    belief that the names of functions not available to the user should start
  127.    with an underscore. I also modified the layout of the resulting report
  128.    slightly.
  129.  
  130. 2. Both time profiles (as implemented by the author) and count profiles (as
  131.    built into the C library) are now handled by the same library.
  132.  
  133. 3. To include profiling, you now need the following:
  134.  
  135.     /* if undefined, profile_init() expands to nothing */
  136.     #define PROFILE
  137.     #include "Profile.h"
  138.  
  139.    and then, at the start of main(), call profile_init(filename,type), where
  140.    filename is the name of the file to which profiling statistics will be
  141.    written ("", or an unwritable file, gives stderr), and type is one of the
  142.    two constants Profile_Time and Profile_Count (defined in Profile.h).
  143.  
  144. 4. For time profiling, the profiling library (part of my Utils library) must
  145.    be included in the link command line, PRIOR to Risc_OSLib, as some of the
  146.    standard functions are redefined. No special compiler options are required.
  147.  
  148.    For count profiling, the source files to be profiled must be compiled with
  149.    the -p (function level) or -px (basic block level) compiler option. The
  150.    object must be linked with both the profiling library and AnsiLib (for the
  151.    _mapstore() functions), but it is still possible to link in Stubs in order
  152.    to use the shared C library. There is no ordering restriction on the
  153.    libraries in this case.
  154.  
  155. 5. To include C-style function headers in assembler code (as described
  156.    by Ferdinand, when discussing how to get profiling for assembler functions)
  157.    I have written an ObjAsm macro, which does it all for you. See the
  158.    definition of macro Func, in the source file Asm.ProfileAsm. Feel free
  159.    to copy and use this, if you think it may be helpful.
  160.  
  161. Thanks to Ferdinand for this library. I take no credit for any of the good
  162. ideas in here, but if there are any bugs, you can probably blame me for those.
  163.  
  164.     Paul Moore,
  165.     10, Mulberry Rise,
  166.     Firdale Park,
  167.     Northwich,
  168.     Cheshire
  169.     CW8 4UQ
  170.     England
  171.  
  172. E-Mail:    pmoore@cix.compulink.co.uk
  173. or    pmoore%cix@ukc.ac.uk
  174.  
  175. ------------------------------------------------------------------------------
  176.