Return to profile.doc CVS log

Up to [OS/2 SDKs] / pmsdk / profiler

Annotation of pmsdk/profiler/profile.doc, revision 1.1

1.1     ! root        1:  
        !             2: 
        !             3:        OS/2 Profiler
        !             4: ------------------------------------------------------------
        !             5: 
        !             6:   The OS/2 Profiler will allow 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 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: In this release, kernel support profiling. So, you don't need a special
        !            23: kernel to run your profilling program.
        !            24: 
        !            25: Profile Library Calls:
        !            26: ======================
        !            27: 
        !            28: 
        !            29: -----------------------------
        !            30: ProfInit( type, modulelist);
        !            31:    int     type;            /* type = 0      system              */
        !            32:                             /*      = 5      PT_USER|PT_USEKP    */
        !            33:    char far *modulelist;     /* should be NULL for user profiling */
        !            34: 
        !            35: ProfInit() initializes internal data space.
        !            36: 
        !            37:   ProfInit clears the data areas after it has allocated them. In 
        !            38: addition to the profiling coutner segments, the profiler allocates a 64K
        !            39: block for internal use. 
        !            40: 
        !            41: 
        !            42: ------------------------------
        !            43: ProfOn( type);
        !            44:    int type;           /* type = system or user (0/1) */
        !            45: 
        !            46: ProfOn() starts the counters.
        !            47: 
        !            48: 
        !            49: ------------------------------
        !            50: ProfOff( type);
        !            51:    int type;           /* type = system or user (0/1) */
        !            52: 
        !            53: ProfOff() stops the counters.
        !            54: 
        !            55: 
        !            56: ------------------------------
        !            57: ProfDump( type, filename);
        !            58:    int type;           /* type = system or user (0/1) */
        !            59:    char far *filename;  /* long pointer to ASCIIZ filename */
        !            60: 
        !            61: 
        !            62: ProfDump() dumps the profiling information to the specified filename.
        !            63: The file is used later as input for the profiling utility PINFO.EXE
        !            64: which displays the usage statistics.
        !            65: 
        !            66: ------------------------------
        !            67: ProfFree( type);
        !            68:    int type;           /* type = system or user (0/1) */
        !            69: 
        !            70: ProfFree() is the final call in a profiling session. ProfFree frees
        !            71: all memory used by the profiling data segments and data allocated 
        !            72: for internal use.
        !            73: 
        !            74: 
        !            75: ------------------------------
        !            76: ProfClear( type);
        !            77:    int type;           /* type = system or user (0/1) */
        !            78: 
        !            79: ProfClear() Clears all counters. 
        !            80: 
        !            81: 
        !            82: 
        !            83: 
        !            84: To use the profiler follow these steps:
        !            85: ---------------------------------------
        !            86: 
        !            87: 1>  a. Copy PINFO.EXE and PSET.EXE into a directory on your path.
        !            88:     b. Put PROFILE.DLL in a directory in your LIBPATH.
        !            89: 
        !            90: 
        !            91:    USER PROFILING
        !            92:    --------------
        !            93: 
        !            94: 2> a. Get testprof.c, testprof.def, testprof.lfr, profile.h and profile.lib
        !            95:       from the profiler\example, include, lib directories to use as an example.
        !            96:    b. Insert calls to the profiling functions in your application.
        !            97:       Use testprof.c as a model.
        !            98:    c. Build your executable.
        !            99:    d. Run your executable.
        !           100:    
        !           101: 
        !           102:    SYSTEM PROFILING
        !           103:    ----------------
        !           104: 2> a. Make a batch file with the following lines:
        !           105:         pset init
        !           106:         pset on
        !           107:         (your commands here...)
        !           108:         pset off
        !           109:         pset dump (your filename)
        !           110:         pset free
        !           111:    b. Run the batch file.
        !           112: 
        !           113: 3> a. use PINFO.EXE on your dump file.
        !           114: 
        !           115: 
        !           116: (Your results may be different than this example.)
        !           117: 
        !           118:     Example 1. "pinfo testprof.pro"
        !           119: 
        !           120:                Module    Segment  Length  Tics      Percent
        !           121:                --------  -------  ------  --------  -------
        !           122:                kernel                            9    1.88
        !           123:                TESTPROF    0001    182c        470   98.12
        !           124:                                           --------
        !           125:                                   Total        479
        !           126: 
        !           127:     Example 2. "pinfo testprof.pro testprof.map"
        !           128: 
        !           129:                Module TESTPROF
        !           130: 
        !           131:                Segment 1:
        !           132:                0001:003e          6 (  1.25%)   _main
        !           133:                0001:0128        464 ( 96.87%)   _inner
        !           134: 
        !           135:     NOTE: pinfo extracts data on the segments belonging to the module
        !           136:           represented in the map file.
        !           137: 
        !           138: 
        !           139: PINFO.EXE   (NOTE: OS/2 Protected mode only)
        !           140: ---------
        !           141: USAGE: pinfo [-etz] dump_file [ [-f] file]
        !           142:          -e : print every tic count (subject to -z)
        !           143:         -t : print totals for each segment (subject to -z)
        !           144:          -z : print 0 counts
        !           145:    dump_file: output of ProfDump() API;
        !           146:         file: map file to correlate with dump file
        !           147:      -f file: file is list of map files to correlate with dump file,
        !           148:                file names listed one per line.
        !           149: 
        !           150:        (See above examples)
        !           151: 
        !           152: PSET.EXE    (NOTE: OS/2 Protected mode only)
        !           153: --------
        !           154: USAGE: pset INIT | CLEAR | ON | OFF | DUMP file | FREE
        !           155:    CLEAR      reset counts to zero
        !           156:    DUMP file  dump profile data to <file>
        !           157:    FREE       deallocate system profiling data space
        !           158:    INIT       allocate system profiling data space
        !           159:    OFF        turn off profiling
        !           160:    ON         turn on profiling
        !           161: 
        !           162:        (See the Profile Library function descriptions for further
        !           163:                detail.)
        !           164: 
        !           165: 
        !           166: Misc. Info
        !           167: ----------
        !           168: 
        !           169: ProfInit() initializes the segment selector table used to determine later
        !           170: if the interrupted CS has a corresponding data area and then allocates
        !           171: the data areas. For each CS in the LDT, a parallel data segment is
        !           172: allocated with the same size as the CS. The IP from the IRET frame
        !           173: has the lower two bits masked off for DWORD resolution and is then used 
        !           174: as an offset into this data segment to increment a DWORD. This gives
        !           175: a profiling granularity of a DWORD. The overhead of the profiler is
        !           176: less than 5% of non-profiling execution. 
        !           177: 
        !           178: 
        !           179: The profiler uses Timer 0 of the 8243 Timer Chip. Any applications that
        !           180: use this timer will not profile correctly. 
        !           181: 
        !           182: Real mode profiling is NOT supported. Since real mode uses Timer 0 for
        !           183: other things, real mode should not be used.
        !           184: 
        !           185: The profiler supports nested calls to ProfOn() and ProfOff(). There must
        !           186: be a matching ProfOff() call for every ProfOn() call.
        !           187: 
        !           188: 
        !           189: 
        !           190: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.