home *** CD-ROM | disk | FTP | other *** search
/ Really Useful CD 1 / ReallyUsefulCD1.iso / extras / progutils / profiler / doc < prev    next >
Encoding:
Text File  |  1990-06-10  |  3.7 KB  |  116 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 useful 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.