home *** CD-ROM | disk | FTP | other *** search
/ Microsoft Programmer's Library 1.3 / Microsoft-Programers-Library-v1.3.iso / sampcode / os2sdk / os2sdk11 / tk2 / profile.doc < prev    next >
Encoding:
Text File  |  1989-02-20  |  6.3 KB  |  200 lines
  1.  
  2.  
  3.     OS/2 Profiler
  4. ------------------------------------------------------------
  5.  
  6. The OS/2 Profiler allows you to determine where your programs
  7. are spending their time. It will tell you the percentage of execution 
  8. time spent in your program at a function level when used with a .MAP 
  9. file. It will also show what percentage of execution time is being used
  10. by the system.
  11.  
  12. IMPORTANT NOTE: The profiling programming interfaces and tools are
  13. provided here in the Microsoft OS/2 1.1 Software Development Kit as an
  14. aid to developers. These features will NOT be present in the
  15. end-user version of the product. If you insert the profiling calls
  16. into your code during development you must remove them in your
  17. final code otherwise your application will fail to load on the
  18. retail end user system. In addition we will change and improve
  19. these calls over time and future versions may not be compatible
  20. with those in the current kit. These calls are not part of the
  21. standard MS OS/2 Application Programming Interface.
  22.  
  23. The profiling tools requires a special kernel called OS2KRNLP (we have also
  24. included a version of this kernel for PS/2s:  OS2KRNLP.PS2).  To use 
  25. these tools remove the HIDDEN and READ ONLY permission from the retail kernel 
  26. (using the Toolkit tool Chmode like this: chmode -hr OS2KRNL), and then
  27. copy the retail kernel to OS2KRNLR.  Next, copy the appropriate profiling
  28. kernel (OS2KRNLP or OS2KRNLP.PS2) to OS2KRNL and reboot.  The special kernel
  29. is a super set of the retail kernel so it can be used in the same way as the
  30. retail kernel.
  31.  
  32.  
  33. Profile Library Calls:
  34. ======================
  35.  
  36.  
  37. -----------------------------
  38. ProfInit( type, modulelist);
  39.    int        type;         /* type = 0      system          */
  40.                  /*      = 5      PT_USER|PT_USEKP      */
  41.    char far *modulelist;     /* should be NULL for user profiling */
  42.  
  43. ProfInit() initializes internal data space.
  44.  
  45. ProfInit clears the data areas after it has allocated them. In 
  46. addition to the profiling coutner segments, the profiler allocates a 64K
  47. block for internal use. 
  48.  
  49.  
  50. ------------------------------
  51. ProfOn( type);
  52.    int type;        /* type = system or user (0/1) */
  53.  
  54. ProfOn() starts the counters.
  55.  
  56.  
  57. ------------------------------
  58. ProfOff( type);
  59.    int type;        /* type = system or user (0/1) */
  60.  
  61. ProfOff() stops the counters.
  62.  
  63.  
  64. ------------------------------
  65. ProfDump( type, filename);
  66.    int type;        /* type = system or user (0/1) */
  67.    char far *filename;  /* long pointer to ASCIIZ filename */
  68.  
  69.  
  70. ProfDump() dumps the profiling information to the specified filename.
  71. The file is used later as input for the profiling utility PINFO.EXE
  72. which displays the usage statistics.
  73.  
  74. ------------------------------
  75. ProfFree( type);
  76.    int type;        /* type = system or user (0/1) */
  77.  
  78. ProfFree() is the final call in a profiling session. ProfFree frees
  79. all memory used by the profiling data segments and data allocated 
  80. for internal use.
  81.  
  82.  
  83. ------------------------------
  84. ProfClear( type);
  85.    int type;        /* type = system or user (0/1) */
  86.  
  87. ProfClear() Clears all counters. 
  88.  
  89.  
  90.  
  91.  
  92. To use the profiler follow these steps:
  93. ---------------------------------------
  94.  
  95. 1>  a. Copy PINFO.EXE and PSET.EXE into a directory on your path.
  96.     b. Put PROFILE.DLL in a directory in your LIBPATH.
  97.  
  98.  
  99.    USER PROFILING
  100.    --------------
  101.  
  102. 2> a. Get testprof.c, testprof.def, testprof.lrf, profile.h and profile.lib
  103.       from the profiler\example, include, lib directories to use as an 
  104.       example.
  105.    b. Insert calls to the profiling functions in your application,
  106.       using testprof.c as a model.
  107.    c. Build your executable.
  108.    d. Run your executable.
  109.    e. use PINFO to display profiling results   
  110.  
  111.    SYSTEM PROFILING
  112.    ----------------
  113. 3> a. Make a batch file with the following lines:
  114.         pset init
  115.         pset on
  116.         (your commands here...)
  117.         pset off
  118.         pset dump (your filename)
  119.         pset free
  120.    b. Run the batch file.
  121.  
  122. 4>  Using PINFO.EXE with dump files
  123.  
  124.  
  125. (Your results may be different than this example.)
  126.  
  127.     Example 1.    "pinfo testprof.pro"
  128.  
  129.         Module      Segment  Length  Tics      Percent
  130.         --------  -------  ------  --------  -------
  131.         kernel                  9    1.88
  132.         TESTPROF    0001    182c    470   98.12
  133.                        --------
  134.                    Total    479
  135.  
  136.     Example 2.    "pinfo testprof.pro testprof.map"
  137.  
  138.         Module TESTPROF
  139.  
  140.         Segment 1:
  141.         0001:003e       6 (    1.25%)     _main
  142.         0001:0128     464 ( 96.87%)     _inner
  143.  
  144.     NOTE: pinfo extracts data on the segments belonging to the module
  145.           represented in the map file.
  146.  
  147.  
  148. PINFO.EXE   (NOTE: OS/2 Protected mode only)
  149. ---------
  150. USAGE: pinfo [-etz] dump_file [ [-f] file]
  151.          -e : print every tic count (subject to -z)
  152.      -t : print totals for each segment (subject to -z)
  153.          -z : print 0 counts
  154.    dump_file: output of ProfDump() API;
  155.         file: map file to correlate with dump file
  156.      -f file: file is list of map files to correlate with dump file,
  157.         file names listed one per line.
  158.  
  159.     (See above examples)
  160.  
  161. PSET.EXE    (NOTE: OS/2 Protected mode only)
  162. --------
  163. USAGE: pset INIT | CLEAR | ON | OFF | DUMP file | FREE
  164.    CLEAR      reset counts to zero
  165.    DUMP file  dump profile data to <file>
  166.    FREE       deallocate system profiling data space
  167.    INIT       allocate system profiling data space
  168.    OFF        turn off profiling
  169.    ON         turn on profiling
  170.  
  171.     (See the Profile Library function descriptions for further
  172.         detail.)
  173.  
  174.  
  175. Misc. Info
  176. ----------
  177.  
  178. ProfInit() initializes the segment selector table used to determine later
  179. if the interrupted CS has a corresponding data area and then allocates
  180. the data areas. For each CS in the LDT, a parallel data segment is
  181. allocated with the same size as the CS. The IP from the IRET frame
  182. has the lower two bits masked off for DWORD resolution and is then used 
  183. as an offset into this data segment to increment a DWORD. This gives
  184. a profiling granularity of a DWORD. The overhead of the profiler is
  185. less than 5% of non-profiling execution. 
  186.  
  187.  
  188. The profiler uses Timer 0 of the 8243 Timer Chip. Any applications that
  189. use this timer will not profile correctly. 
  190.  
  191. Real mode profiling is NOT supported. Since real mode uses Timer 0 for
  192. other things, real mode should not be used.
  193.  
  194. The profiler supports nested calls to ProfOn() and ProfOff(). There must
  195. be a matching ProfOff() call for every ProfOn() call.
  196.  
  197.  
  198.  
  199.  
  200.