Return to profile.doc CVS log

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

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

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