View source for SMPProgAdd - Software Trace Facility (STRACE)

{{IBM-Reprint}}
{{SMPProgAdd}}
[[Category:WorkToDo]]
STRACE is a software tracing mechanism that runs on OS/2 Warp Server for SMP. The following conditions must be met in order to enable software tracing:

* '''TRACE=OFF''' must be specified in the CONFIG.SYS file. This is a requirement of the existing TRACE command in OS/2.
* OS/2 Warp Server for SMP must be running on a Pentium, Pentium Pro, or better processor, since the 64-bit Time Stamp Counter is used as the timing mechanism.

Once data has been collected using STRACE, it may be copied to another OS/2 Warp or later system (along with the '''STRACE.EXE''' file from the '''OS2''' directory on the boot drive) and processed using STRACE.

== STRACE Overview ==

STRACE uses software trace hooks to collect data. Trace hooks are identified by both a major code and a minor code. Major code 1 is reserved for exclusive use by IBM. Major codes 0x00b8 (184) and 0x00b9 (185) have been reserved for customer use. A listing of major and minor codes associated with OS/2 Warp Server for SMP can be found in [[#System Trace Hook Definitions|System Trace Hook Definitions]].

For major codes other than 0x00b8 and 0x00b9 mentioned above, the user identifies the major codes to be traced with the '''TRACE''' command.

To turn tracing on for events with major codes of 0x0002, 0x0013, and 0x0042:
<pre>
  TRACE ON 2 19 66
</pre>

'''Note:''' The TRACE command requires decimal arguments.

If '''TRACE ON''' is specified without one or more major codes, tracing for all major codes, except 1, is enabled.

STRACE.EXE uses the general purpose performance function [[#DosPerfSysCall|DosPerfSysCall]] to access the software trace buffer. When STRACE is turned on, it allocates the required buffers (one per processor) in the kernel space and starts tracing immediately. A user may turn off STRACE (to stop collecting trace data), copy the buffers to the user's buffer, flush the buffer to restart tracing, or reset STRACE (turn off and free the allocated buffers).

== STRACE Syntax ==

<pre>
         ON
         OFF
         INIT
         RESET
         FLUSH
         INFO
         GET
STRACE   POST       /S=ssss /R=rrrrrrrr /M=mmmmmmm /O=oooooooo /N=nnnnnnnn /A=a
         MAJOR
         VERSION
         MTE
         INSERT
         REMOVE
         NRM
</pre>

=== STRACE Arguments ===

One of the following arguments is required. The first valid command is used. All others will be ignored and a warning is issued to the user.

* '''ON''' Turns STRACE ON. If STRACE is off, this command causes the buffers to be allocated if needed and turns tracing on. If STRACE is currently on, this command has no effect. The default buffer size per processor is 3 MB which can be changed by using the /S option described below. Note that if buffers exist at the time of this command, no new buffers will be allocated. Tracing is simply turned on using the existing buffers, whatever size they may be. Tracing will be automatically turned off when any buffer on any processor is full.
* '''OFF''' Turns STRACE OFF. If STRACE is on, this command turns tracing off. The buffers are not freed. If STRACE is currently off, this command has no effect.
* '''INIT''' Initializes STRACE. This command causes the buffers to be allocated if necessary, but does not turn tracing on. If STRACE is currently on, this command has no effect. The default buffer size per processor is 3 MB, which can be changed using the /S option. Note that if buffers exist at the time of this command, no new buffers will be allocated.
* '''RESET''' Resets STRACE. If STRACE is on, this command turns tracing off. Whether STRACE was on or off, any allocated trace buffers will be freed and the contents discarded.
* '''FLUSH''' Flushes STRACE buffers. This command causes all data in the trace buffers to be discarded. The buffers remain allocated if they exist. This command does not alter the state of tracing. If STRACE is on, it will remain on and tracing continues into an empty buffer. If STRACE is off, it remains off.
* '''INFO''' Returns the status of STRACE. Indicates whether STRACE is active or not, the current buffer allocation, and data collection statistics, such as number of bytes collected. This command does not alter the state of tracing.
* '''GET''' Returns a copy of the trace buffers. This command returns all trace data to the user in a binary file in the current directory called '''STRACE.RAW'''. Use the /R option to direct the output to a different file and path. This file is processed using the '''POST''' option of STRACE, to convert it to a readable format. This command does not alter the state of tracing. Trace major codes should be disabled prior to issuing STRACE GET.
* '''POST''' Processes the binary file returned from the '''GET''' option and produces two files: an integrated ASCII dump of the trace and an MTE (module table entry) loader dump output file. The default input file is '''STRACE.RAW''', the default ASCII dump output file is '''STRACE.OUT''', and the default MTE dump output file is '''STRACE.MTE'''. Use the /R, /O, and /M options respectively to specify a different file name, or fully-qualified path and file name, for each. This command does not alter the state of tracing.
* '''MAJOR''' Displays the active STRACE major codes being traced. This command does not alter the state of tracing.
* '''VERSION''' Displays the current version of STRACE. This command does not alter the state of tracing.
* '''MTE''' Captures Module Table Entry data and writes it to the MTE loader dump file. Use the /M option to direct the output to a file other than '''STRACE.MTE'''. Module Table entry data provides information about loaded memory objects, their sizes, addresses and process affiliations.
* '''INSERT''' Dynamically inserts trace hooks into the kernel. The user can insert a major code group. For example for major code 19, '''strace insert 19'''. The user can insert a particular major/minor code. For example, 19/1, '''strace insert 19 1'''. Very few software trace hooks are dynamic; most are already inserted, and the '''strace insert''' and '''strace remove''' commands have no affect. At present, only hooks associated with major code 0x0013 (19) can be inserted with this capability.
* '''REMOVE''' Dynamically remove trace hooks from the kernel. The user can remove a major code group. For example for major code 19, '''strace remove 19'''. The user can remove a particular major/minor code. For example, 19/1, '''strace remove 19 1'''. At present, only hooks associated with major code 0x0013 (19) can be removed with this capability.
* '''NRM''' For IBM Use Only.

=== STRACE Options ===

The following options can be used to alter the default behavior of the STRACE command:

* '''/S=ssss''' Specifies the buffer size for each processor in megabytes (MB). The default is '''/S=3''', which results in a trace buffer of 3 MB for each processor.
* '''/R=rrrrrrrr''' Specifies the drive, path, and name for the file containing the data returned by the '''GET''' and '''POST''' arguments, and is ignored otherwise. The default is '''/R=STRACE.RAW'''.
* '''/M=mmmmmmmm''' Specifies the drive, path, and name for the MTE loader dump file produced by the '''POST''' and '''MTE''' arguments, and is ignored otherwise. The default is '''/M=STRACE.MTE'''.
* '''/O=oooooooo''' Specifies the drive, path, and name of the ASCII output file created with the '''POST''' option, and is ignored otherwise. The default is '''/O=STRACE.OUT'''.
* '''/A=a''' Controls whether the adjustment of time stamps for processors with different initial Time Stamp Counter values should be performed during '''STRACE POST''' processing. The default is '''/A=1''' which performs the adjustment. Specify '''/A=0''' to suppress this adjustment.

=== STRACE Command Examples ===

* '''TRACE ON''' This activates all trace major codes (except major code 1, which is for IBM use only).
* '''STRACE ON /S=4''' This will allocate a trace buffer of 4 MB per processor and turn software tracing on.
* '''STRACE OFF''' This will turn tracing off. Once tracing is off, the user may then process the trace data contained in the trace buffer without having additional data written to the buffer.
* '''STRACE GET /R=MYTRACE.RAW''' This will extract the trace buffer into the file '''MYTRACE.RAW'''.
* '''STRACE POST /R=MYTRACE.RAW /O=E:\TRACE\MYTRACE.OUT''' This will process the RAW file '''MYTRACE.RAW''' and generate an ASCII version in '''E:\TRACE\MYTRACE.OUT'''.
* '''STRACE RESET''' This will turn tracing off and free any STRACE buffers.
* '''TRACE OFF''' This will deactivate all trace major codes.

=== Sample Use of STRACE ===

Let's say you are running a program called '''COLLIE.EXE''' which uses queues to fetch data from another program. You could use STRACE to gather performance data on how the semaphore operations associated with the queuing activities are handled, or you could use it to monitor what semaphore operations are done to help diagnose a hang in the program. The control program semaphore functions use major code 0x0018 (see [[#Dos Functions - 2 of 12|Dos Functions - 2 of 12]]), therefore the following sequence of commands could be used:

<pre>
 1. Turn trace on for the desired major code,      TRACE ON 24
    0x0018 in this case.

 2. Turn on STRACE                                 STRACE ON

 3. Run the desired program.                       START COLLIE

 4. When program completes, or at the appropriate  STRACE OFF
    time, turn off STRACE.                         TRACE OFF

 5. Get a copy of the trace information from all
    processors.                                    STRACE GET /R=RUN1.RAW

 6. Clear the trace buffers in preparation for
    running the program again.                     STRACE FLUSH

 7. Turn on STRACE again.                          TRACE ON 24
                                                   STRACE ON

 8. Run the program again.                         START COLLIE

 9. Turn off STRACE at the appropriate time.       STRACE OFF
                                                   TRACE OFF

 10. Copy the trace buffers to another file.       STRACE GET /R=RUN2.RAW

 11. If all tracing is complete, you could now     STRACE RESET
     delete the trace buffers.

 12. Generate readable trace data and explicitly   STRACE POST /R=RUN1.RAW
     name all output files.                        /M=RUN1.MTE
                                                   /O=RUN1.OUT
</pre>

== STRACE POST Processing ==

The '''STRACE POST''' option processes the binary file returned from the '''GET''' option and produces two files:

* ASCII dump output file, described in [[#STRACE ASCII Dump Format|STRACE ASCII Dump Format]].
* MTE loader dump output file, described in [[#STRACE MTE Dump Format|STRACE MTE Dump Format]].

Sample output from running an STRACE POST is shown here:
<pre>
RAW file    = strace.raw
Output file = strace.out
MTE file    = strace.mte
Adjust time = TRUE

    CPU 0 Rating 89.997898 Mhz
    CPU 1 Rating 89.995955 Mhz
    CPU 2 Rating 89.996197 Mhz
    CPU 3 Rating 90.005302 Mhz

Working ...
hooks processed: 575779

    CPU 0 Start time stamp :(531:fa721cba)
          End time stamp   :(535:5b3f6e10)
          Drift ratio      :0.000000e+000
          Number of hooks  :159367

    CPU 1 Start time stamp :(8:45ea9f53)
          End time stamp   :(b:a6b8945c)
          Drift ratio      :2.888343e-006
          Number of hooks  :128142

    CPU 2 Start time stamp :(8:45de419e)
          End time stamp   :(b:a6abcb34)
          Drift ratio      :9.924885e-007
          Number of hooks  :145038

    CPU 3 Start time stamp :(8:45d4207a)
          End time stamp   :(b:a6a2318d)
          Drift ratio      :3.383068e-006
          Number of hooks  :143232
</pre>

On rare occasions, a start or end time stamp may be shown as ffffffff:ffffffff. This occurs when STRACE processing was unable to gain synchronous access to one or more processors to get their time stamps. When this occurs, you will need to recollect the STRACE data by turning off STRACE, flushing the STRACE buffers, and then restarting STRACE.

== STRACE ASCII Dump Format ==

The format of the ASCII dump file produced by the '''STRACE POST''' command is described below. Each hook is listed on a single line containing information about the hook type, major code, minor code, time stamp, processor ID, and hook-specific data.

A sample '''STRACE.OUT''' file is shown here:
<pre>
 102   13   29 9450:1545341324 0 fff37182 fff05c9c
 102   13   2b 9450:1545341598 0 fff37198 fff05c9c
 102   13   29 9450:1545342287 0 fff371a3 fff05c9c
 102   13   2b 9450:1545342546 0 fff371ae fff05c9c
 104   13   4b 9450:1545343593 0 00000001 00000004 fff05d1c fff405a3
 100    4   89 9450:1545343975 0
3401   a8    3 9450:1546123683 2 -- strace.mte --
 104   13    9 9450:1546180366 2 00000000 00000001 fff05f58 fff47a71
 101   15    1 9450:1546183708 0 fff48224
 100   15   81 9450:1546184199 0
 101   15    1 9450:1546184525 1 fff48224
 100   15   81 9450:1546184847 1
 101   15    1 9450:1546185450 3 fff48224
 104   13   4b 9450:1546185848 2 00000001 00000004 fff05f58 fff47f38
 100   15   81 9450:1546185851 3
 100   13   3b 9450:1546189361 2
 100   13   39 9450:1546189762 0
 104   13    9 9450:1546191925 2 00000000 00000001 fff05ed8 fff6e0d5
 104   13   4b 9450:1546193003 2 00000001 00000004 fff05ed8 fff6e136
 100   13   3b 9450:1546193765 0
 100   13   39 9450:1546194102 1
 100   13   3b 9450:1546194683 1
 100   13   3a 9450:1546194745 2
 104   13    9 9450:1546194789 0 00000000 00000040 fff05d40 fff42840
 100   13   39 9450:1546195040 2
 104   13    9 9450:1546197102 2 00000000 00000001 fff05ed8 fff6e467
</pre>

The general format for trace output is:
<pre>
tttt MM mm TTTTTTTT:tttttttt p dddddddd...ddd
|    |  |  |        |        | |
|    |  |  |        |        | +--- Data in hex, described below, and hook type specific
|    |  |  |        |        |
|    |  |  |        |        +----- Processor ID in decimal (0,1,2,3,...,63)
|    |  |  |        |
|    |  |  |        +-------------- Low-order 32 bits of Time Stamp (Pentium cycle counter)
|    |  |  |                        (in decimal)
|    |  |  |
|    |  |  +----------------------- High-order 32 bits of Pentium cycle counter (in decimal)
|    |  |
|    |  +-------------------------- Minor Code (in hex)
|    +----------------------------- Major Code (in hex)
|
+---------------------------------- Hook Type (in hex)
</pre>

=== Hook Types ===

The different hook types are:

* '''SFT_HOOK_32BIT (0x0100)''' Each data item is a [[#ULONG|ULONG]]. The low 8 bits of the hook type indicate the total number of data items. The maximum number of data items is 255.
* '''SFT_HOOK_DATA (0x0200)''' Data is a buffer of 0 to 255 bytes. The low 8 bits of the hook type indicate the length of the buffer.
* '''SFT_HOOK_VARDATA (0x0400)''' Data consists of variable length items. Low 8 bits of the hook type indicate the number of data items. Each data item is preceded by a [[#ULONG|ULONG]] length indicator. The maximum number of data items is 255. Length indicators are removed as part of '''STRACE POST''' processing.
* '''SFT_HOOK_VARDATA2 (0x0800)''' Data consists of variable length items. Low 8 bits of the hook type indicate the number of data items. Each data item is preceded by a [[#USHORT|USHORT]] length indicator. The maximum number of data items is 255. Length indicators are removed as part of '''STRACE POST''' processing.
* '''SFT_HOOK_TIMEHI (0x1100)''' Occurs when the high 32-bits of the time stamp changes.
* '''SFT_HOOK_STARTUP (0x2200)''' Occurs when STRACE is started.
* '''SFT_HOOK_MTE (0x3400)''' Occurs when STRACE is started. Used by trace post-processors to get information about loaded memory objects.

Hook examples are provided below. Entries from an '''STRACE.OUT''' file, or other ASCII dump of the trace data generated by the '''STRACE POST''' command is as follows:

==== Timer high order 32 bits change hook (SFT_HOOK_TIMEHI) ====

This hook is produced whenever the high order 32 bits of the time stamp changes. The '''STRACE POST''' command normalizes the time stamps and accounts for potential clock drift across the processors in the system. The time stamp shown in each hook reflects this normalization.

<pre>
 1101   a8    1   254:3417264209    0 000000fe
 |      |     |    |                | |
 |      |     |    |                | +---- High 32 bits of timer (unnormalized)
 |      |     |    |                +------ Processor ID (0,1,2,3,...,63)
 |      |     |    +-------------- Normalized Time Stamp (high32bits:low32bits)
 |      |     +------------------- Minor Code = 0x01
 |      +------------------------ Major code = 0xa8
 +----------------------------- Type Indicator (SFT_HOOK_TIMEHI | 1)
</pre>

==== Startup Hook (SFT_HOOK_STARTUP) ====

This hook is produced on STRACE startup. It contains information about the system on which trace is operating, initial time of day information, and number of processors in the system. The data returned is mapped by [[#SFTSTARTUP|SFTSTARTUP]].

<pre>
 2218   a8    2   254:3417264209    0 141e000708000000cc0715390703000001000000598d9303
   |    |    |    |                 |    |
   |    |    |    |                 |    +---Data as follows:
   |    |    |    |                 |              UCHAR      VerMajor
   |    |    |    |                 |              UCHAR      VerMinor
   |    |    |    |                 |              UCHAR      RevLettr
   |    |    |    |                 |              UCHAR      DayDate
   |    |    |    |                 |              UCHAR      MonDate
   |    |    |    |                 |              UCHAR      pad1[3]
   |    |    |    |                 |              USHORT     YrsDate
   |    |    |    |                 |              UCHAR      HrsTime
   |    |    |    |                 |              UCHAR      MinTime
   |    |    |    |                 |              UCHAR      SecTime
   |    |    |    |                 |              UCHAR      HunTime
   |    |    |    |                 |              UCHAR      pad2[2]
   |    |    |    |                 |              ULONG      ulNumCPUs
   |    |    |    |                 |              ULONG      ulCPURate[]
   |    |    |    |                 |
   |    |    |    |                 +-----  Processor ID (0,1,2,3,...,63)
   |    |    |    +-------------- Normalized Time Stamp (high32bits:low32bits)
   |    |    +---------------------------- Minor Code = 0x02
   |    +--------------------------------- Major Code = 0xa8
   +-------------------------------------- Type Indicator/Length (SFT_HOOK_STARTUP | 0x18 bytes)
</pre>

==== Module Table Entry Hook (SFT_HOOK_MTE) ====

This hook is also produced at STRACE startup. The data is used by trace post-processors for information about loaded memory objects.

<pre>
 3401   a8    3   254:3418461893    0  -- see strace.mte --
   |    |    |    |                 |    |
   |    |    |    |                 |    +---- MTE data (not directly reported;
   |    |    |    |                 |          but see the STRACE.MTE file for an example)
   |    |    |    |                 |
   |    |    |    |                 +--- Processor ID (0,1,2,3,...,63)
   |    |    |    +-------------- Normalized Time Stamp (high32bits:low32bits)
   |    |    +---------------------------- Minor Code = 0x03
   |    +--------------------------------- Major Code = 0xa8
   +-------------------------------------- Type Indicator/# of buffers (SFT_HOOK_MTE | 1)
</pre>

==== Hook logging 1 32-bit value ====

<pre>
  101   14    9   254:3419280448    1   0000000c
  | |   |     |   |                 |   |
  | |   |     |   |                 |   +-------------------- 32-bit value
  | |   |     |   |                 +------------------------ Processor ID (0,1,2,3,...,63)
  | |   |     |   +-------------- Normalized Time Stamp (high32bits:low32bits)
  | |   |     +---------------------------- Minor code = 0x09
  | |   +---------------------------------- Major code = 0x14
  | +-------------------------------------- Total Number of 32-bit values = 1
  +---------------------------------------- Type Indicator - (SFT_HOOK_32BIT | 1)
</pre>

==== Hook logging 4 32-bit values ====

<pre>
  104   13   12   254:3419275789    0   00c10000 00000001 fff04248 fff3f5c7
  | |   |    |    |                 |     |         |         |       |
  | |   |    |    |                 |     |         |         |       +-- 4th 32-bit value
  | |   |    |    |                 |     |         |         +------- 3rd 32-bit value
  | |   |    |    |                 |     |         +---------------- 2nd 32-bit value
  | |   |    |    |                 |     +------------------------ 1st 32-bit value
  | |   |    |    |                 +---------------------------- Processor ID
  | |   |    |    +------------- Normalized Time Stamp (high32bits:low32bits)
  | |   |    +---------------------------- Minor Code = 0x12
  | |   +--------------------------------- Major Code = 0x13
  | +------------------------------------- Total number of 32-bit values = 4
  +--------------------------------------- Type indicator -  (SFT_HOOK_32BIT | 4)
</pre>

==== Hook logging 3 2-byte buffers ====

Note that '''STRACE POST''' processing removes the data item length information and simply lists each entry in little-endian (reverse byte) order.

<pre>
  803   12    1   254:3419280201    2   2600 0100 0002
  | |    |    |    |                |   |    |    |
  | |    |    |    |                |   |    |    +------- Data item 3
  | |    |    |    |                |   |    +------------ Data item 2
  | |    |    |    |                |   +----------------- Data item 1
  | |    |    |    |                +------  Processor ID (0,1,2,3,...,63)
  | |    |    |    +-------------- Normalized Time Stamp (high32bits:low32bits)
  | |    |    +--------------------------- Minor Code = 0x01
  | |    +-------------------------------- Major Code = 0x12
  | +----------------------------------- Total number of buffers = 3
  +------------------------------------- Type indicator - (SFT_HOOK_VARDATA2 | 3 )
</pre>

== STRACE MTE Dump Format ==

The '''STRACE POST''' and '''STRACE MTE''' commands produce an MTE dump output file. The format of each line in the file is shown here:

<pre>
0002 00020000 00004000 0000000d fb1e0828 E:\OS2\EPWMP.EXE
 |     |       |        |        |         |
 |     |       |        |        |         +--- Module name
 |     |       |        |        |
 |     |       |        |        +- PTDA Address
 |     |       |        |
 |     |       |        +---------- PID (process identifier)
 |     |       |
 |     |       +------------------- Size in bytes
 |     |
 |     +--------------------------- Linear Load Address
 |
 +--------------------------------- Segment number
</pre>

A portion of an '''STRACE.MTE''' file is shown below:

<pre>
0001 00010000 00003190 00000008 fb1de424 E:\OS2\SYSTEM\LOGDAEM.EXE
0002 00020000 000007f0 00000008 fb1de424 E:\OS2\SYSTEM\LOGDAEM.EXE
0003 00030000 000072d0 00000008 fb1de424 E:\OS2\SYSTEM\LOGDAEM.EXE
0001 00010000 000000c8 00000007 fb1ddcf0 E:\IBMLAN\NETPROG\LSDAEMON.EXE
0002 00020000 00002010 00000007 fb1ddcf0 E:\IBMLAN\NETPROG\LSDAEMON.EXE
0003 00030000 00000030 00000007 fb1ddcf0 E:\IBMLAN\NETPROG\LSDAEMON.EXE
0001 00010000 000000e2 00000006 fb1dd5bc E:\IBMCOM\PROTOCOL\LANDLL.EXE
0002 00020000 00000436 00000006 fb1dd5bc E:\IBMCOM\PROTOCOL\LANDLL.EXE
0001 00010000 00001d82 00000005 fb1dce88 E:\MPTN\BIN\CNTRL.EXE
0002 00020000 0000020a 00000005 fb1dce88 E:\MPTN\BIN\CNTRL.EXE
0003 00030000 00007260 00000005 fb1dce88 E:\MPTN\BIN\CNTRL.EXE
0001 00010000 000010c4 00000004 fb1dc754 E:\IBMCOM\LANMSGEX.EXE
0002 00020000 00000291 00000004 fb1dc754 E:\IBMCOM\LANMSGEX.EXE
0001 00010000 00000a40 0000000a fb1df28c E:\OS2\PMSHELL.EXE
0002 00020000 00000070 0000000a fb1df28c E:\OS2\PMSHELL.EXE
0003 00030000 0000fa50 0000000a fb1df28c E:\OS2\PMSHELL.EXE
0001 00010000 0000cbbb 00000086 fb1e48fc E:\OS2\APPS\KLONDIKE.EXE
0002 00020000 0000e710 00000086 fb1e48fc E:\OS2\APPS\KLONDIKE.EXE
0003 00030000 00000a32 00000086 fb1e48fc E:\OS2\APPS\KLONDIKE.EXE
0004 00040000 0000eec0 00000086 fb1e48fc E:\OS2\APPS\KLONDIKE.EXE
0005 00000000 0000d808 00000086 fb1e48fc E:\OS2\APPS\KLONDIKE.EXE
0006 00000000 0000ff44 00000086 fb1e48fc E:\OS2\APPS\KLONDIKE.EXE
0001 00010000 0000cbbb 00000085 fb1e41c8 E:\OS2\APPS\KLONDIKE.EXE
</pre>

== Differences Between TRACE and STRACE ==

There may be some confusion between the existing OS/2 Trace facility and the new software tracing provided by STRACE, especially since STRACE uses the OS/2 Trace facility control utility. First the OS/2 Trace facility will be described, then the differences between it and software tracing will be outlined.

=== OS/2 Trace Facility ===

The OS/2 Trace facility is an important RAS mechanism in the OS/2 product. It allows specific events within the operating system, in system extensions, and in applications to be recorded in a circular System Trace buffer. Software developers can create tracepoints that are used to monitor the execution of software modules.

The OS/2 Trace facility includes two important utility programs. The OS/2 Trace control utility, TRACE.EXE, is used to enable and disable the tracing of events. Entries within the System Trace buffer can be formatted for viewing by using the OS/2 Trace Formatter utility, TRACEFMT.EXE. The Trace Formatter can also be used to copy the contents of the System Trace buffer to disk for processing on another system.

The general categories of events that are traced in OS/2 are:

* External application program interfaces (APIs)
* Internal interfaces
* Other internal events.

For an interface or event, there are generally two tracepoints. A pre-invocation trace and a post-invocation trace. One can determine the action taken by the system for a particular event by matching the two corresponding trace events in the trace output.

For more information on the OS/2 Trace facility, refer to the ''OS/2 Command Reference'' and the ''OS/2 Warp System Trace Facility'' online books. (The latter book is shipped as part of OS/2 Warp Version 4. It may or may not be part of the OS/2 Warp Server for SMP online documentation.)

=== How STRACE is Different ===

Software Tracing uses the OS/2 Trace facility control utility, TRACE.EXE, to enable and disable the tracing of events.

Software Tracing is performed to special trace buffers which are allocated, one per processor, when STRACE is initialized or turned on. Thus, the information recorded by Software Trace does not go into the OS/2 Trace facility's System Trace buffer and the recording can be efficiently done in a multiprocessing environment. The user can alter the size of the buffers with the STRACE command to collect much more data than TRACE can.

The trace hooks placed in the kernel for software tracing are there for performance use, as opposed to the ones for TRACE which are positioned primarily as debugging aids. Software Tracing utilizes the 64-bit Pentium Time Stamp Counter to provide precise time stamping of events.

Software trace information is formatted by using the '''POST''' option of STRACE. STRACE also permits the transfer of trace data to disk for processing on other systems, provided, of course, that '''STRACE.EXE''' has been copied to the other system.

== System Trace Hook Definitions ==

The following sections outline the trace hook major and minor codes for various functions in OS/2. The information in these tables is subject to change as new hooks are added and obsolete ones are removed. The mention of a hook for a specific function does not necessarily mean that the hook actually records data in the current version of OS/2.

Major codes of 0xb8 and 0xb9 have been reserved for use by customers for trace hooks.

It is the intent of IBM to document the format of the trace data associated with each implemented trace hook in OS/2 in the future.

=== Exceptions and Interrupts ===

{| class="wikitable"
|-
! Hook ID (Major/Minor Code) !! Event Name !! Description
|-
| 03/01 || Exception 0 || Divide By Zero
|-
| 03/02 || Exception 1 || Debug Exception
|-
| 03/03 || Exception 2 || NMI
|-
| 03/04 || Exception 3 || Breakpoint
|-
| 03/05 || Exception 4 || Overflow
|-
| 03/06 || Exception 5 || Bounds Check
|-
| 03/07 || Exception 6 || Invalid Opcode
|-
| 03/08 || Exception 7 || NPX Not Available
|-
| 03/09 || Exception 8 || Double Fault
|-
| 03/0A || Exception 9 || NPX Segment Overrun
|-
| 03/0B || Exception A || Invalid TSS
|-
| 03/0C || Exception B || Segment Not Preset
|-
| 03/0D || Exception C || Stack Fault
|-
| 03/0E || Exception D || General Protection Fault
|-
| 03/0F || Exception E || Page Fault
|-
| 04/01 || Interrupt IRQ 0 ||
|-
| 04/02 || Interrupt IRQ 1 ||
|-
| 04/03 || Interrupt IRQ 2 ||
|-
| 04/04 || Interrupt IRQ 3 ||
|-
| 04/05 || Interrupt IRQ 4 ||
|-
| 04/06 || Interrupt IRQ 5 ||
|-
| 04/07 || Interrupt IRQ 6 ||
|-
| 04/08 || Interrupt IRQ 7 ||
|-
| 04/09 || Interrupt IRQ 8 ||
|-
| 04/0A || Interrupt IRQ 9 ||
|-
| 04/0B || Interrupt IRQ A ||
|-
| 04/0C || Interrupt IRQ B ||
|-
| 04/0D || Interrupt IRQ C ||
|-
| 04/0E || Interrupt IRQ D ||
|-
| 04/0F || Interrupt IRQ E ||
|-
| 04/10 || Interrupt IRQ F ||
|-
| 04/11 || Interrupt IRQ 10 ||
|-
| 04/12 || Interrupt IRQ 11 ||
|-
| 04/13 || Interrupt IRQ 12 ||
|-
| 04/14 || Interrupt IRQ 13 ||
|-
| 04/15 || Interrupt IRQ 14 ||
|-
| 04/16 || Interrupt IRQ 15 ||
|-
| 04/17 || Interrupt IRQ 16 ||
|-
| 04/18 || Interrupt IRQ 17 ||
|-
| 04/19 || Interrupt IRQ 18 ||
|-
| 04/1A || Interrupt IRQ 19 ||
|-
| 04/1B || Interrupt IRQ 1A ||
|-
| 04/1C || Interrupt IRQ 1B ||
|-
| 04/1D || Interrupt IRQ 1C ||
|-
| 04/1E || Interrupt IRQ 1D ||
|-
| 04/1F || Interrupt IRQ 1E ||
|-
| 04/20 || Interrupt IRQ 1F ||
|}

* [[SMPProgAdd - STRACE - Dos Functions]]

=== Dos Functions - 2 of 12 ===

{| class="wikitable"
|-
! Hook ID (Major/Minor Code) !! Event Name
|-
| 4/01 || DosLoadModule
|-
| 4/02 || DosFreeModule
|-
| 4/04 || DosQueryModuleHandle
|-
| 4/05 || DosQueryModuleName
|-
| 4/06 || DosGetEnv
|-
| 4/07 || DosGetMachineMode
|-
| 4/08 || DosGetVersion
|-
| 4/09 || DosQueryAppType
|-
| 4/0A || DosScanEnv
|-
| 4/0B || DosQueryProcAddr
|-
| 8/01 || DosHoldSignal
|-
| 8/02 || DosSendSignal
|-
| 8/03 || DosSetSigHandler
|-
| 8/04 || DosCreatePipe
|-
| 8/05 || DosSemClear
|-
| 8/06 || DosSemRequest
|-
| 8/07 || DosSemSet
|-
| 8/08 || DosSemSetWait
|-
| 8/09 || DosSemWait
|-
| 8/0A || DosMuxSemWait
|-
| 8/0B || DosCloseSem
|-
| 8/0C || DosCreateSem
|-
| 8/0D || DosOpenSem
|-
| 8/0F || DosAddMuxWaitSem
|-
| 8/10 || DosCallNPipe
|-
| 8/12 || DosCloseEventSem
|-
| 8/13 || DosCloseMutexSem
|-
| 8/14 || DosCloseMuxWaitSem
|-
| 8/15 || DosConnectNPipe
|-
| 8/16 || DosCreateEventSem
|-
| 8/17 || DosCreateMutexSem
|-
| 8/18 || DosCreateMuxWaitSem
|-
| 8/19 || DosDisconnectNPipe
|-
| 8/1A || DosCreateNPipe
|-
| 8/1B || DosOpenEventSem
|-
| 8/1C || DosOpenMutexSem
|-
| 8/1D || DosOpenMuxWaitSem
|-
| 8/1E || DosPeekNPipe
|-
| 8/1F || DosQueryNPHState
|-
| 8/20 || DosQueryNPipeInfo
|-
| 8/21 || DosQueryNPipeSemState
|-
| 8/23 || DosQueryEventSem
|-
| 8/24 || DosQueryMutexSem
|-
| 8/25 || DosQueryMuxWaitSem
|-
| 8/27 || DosReleaseMutexSem
|-
| 8/29 || DosRequestMutexSem
|-
| 8/2B || DosSetNPHState
|-
| 8/2C || DosSetNPipeSem
|-
| 8/2D || DosTransactNPipe
|-
| 8/2E || DosWaitEventSem
|-
| 8/2F || DosWaitMuxWaitSem
|-
| 8/30 || DosWaitNPipe
|}

=== Dos Functions - 3 of 12 ===

{| class="wikitable"
|-
! Hook ID (Major/Minor Code) !! Event Name
|-
| 8/31 || DosFSRamSemClear
|-
| 8/32 || DosFSRamSemRequest
|-
| 8/33 || DosDeleteMuxWaitSem
|-
| 8/34 || DosPostEventSem
|-
| 8/35 || DosRawReadNPipe
|-
| 8/36 || DosRawWriteNPipe
|-
| 8/37 || DosResetEventSem
|-
| 8/39 || DosSetKBDSigFocus
|-
| 8/40 || MemWaitEventSem
|-
| C/01 || DosError
|-
| C/02 || DosSetVec
|-
| C/05 || DosSysTrace
|-
| C/06 || DosErrClass
|-
| C/07 || DosLogRead
|-
| C/08 || DosLogRegister
|-
| C/09 || DosDynamicTrace
|-
| C/0A || DosRaiseException
|-
| C/0B || DosSetExceptionHandler
|-
| C/0C || DosUnsetExceptionHandler
|-
| C/0D || DosUnwindExceptionHandler
|-
| C/0E || DosSetTraceInfo
|-
| C/0F || DosSystemService
|-
| 0/11 || MAllocMem
|-
| 0/12 || MFreeMem
|-
| 0/13 || MLock
|-
| 0/14 || MUnlock
|-
| 0/15 || MInitTask
|-
| 0/16 || MFreeTask
|-
| 0/17 || MAttach
|-
| 0/18 || M32ApiAliasMem
|-
| 0/19 || M32ApiAllocMem
|-
| 0/1A || M32ApiAllocSharedMem
|-
| 0/1B || M32ApiGetNamedShared
|-
| 0/1C || M32ApiGetSharedMem
|-
| 0/1D || M32ApiGiveSharedMem
|-
| 0/1E || M32ApiFreeMem
|-
| 0/1F || M32ApiSetMem
|-
| 0/21 || M32ApiQueryMem
|-
| 0/22 || GPageFault
|-
| 0/24 || GReloadFrame
|-
| 0/25 || GGetPF
|-
| 0/26 || GIdle
|-
| 0/27 || ELInitLDT
|-
| 0/28 || ELAllocLDT
|-
| 0/29 || ELFreeLDT
|-
| 0/2A || MSwapIn
|-
| 0/2B || MSwapOut
|}

=== Dos Functions - 4 of 12 ===

{| class="wikitable"
|-
! Hook ID (Major/Minor Code) !! Event Name
|-
| 4/01 || [[DosAllocSeg]]
|-
| 4/02 || [[DosAllocShrSeg]]
|-
| 4/03 || [[DosGetShrSeg]]
|-
| 4/04 || [[DosReallocSeg]]
|-
| 4/05 || [[DosFreeSeg]]
|-
| 4/06 || [[DosAllocHuge]]
|-
| 4/07 || [[DosReallocHuge]]
|-
| 4/08 || [[DosCreateCSAlias]]
|-
| 4/09 || [[DosGiveSeg]]
|-
| 4/0A || DosAllocMem
|-
| 4/0B || DosAllocSharedMem
|-
| 4/0C || DosFreeMem
|-
| 4/0D || DosGetHugeShift
|-
| 4/0E || DosGetNamedSharedMem
|-
| 4/0F || Dos32GetResource
|-
| 4/10 || DosGetSharedMem
|-
| 4/11 || DosGetSeg
|-
| 4/12 || DosGiveSharedMem
|-
| 4/13 || DosLockSeg
|-
| 4/16 || DosMemAvail
|-
| 4/17 || DosQueryMem
|-
| 4/18 || DosSetMem
|-
| 4/19 || DosSizeSeg
|-
| 4/1A || DosUnlockSeg
|-
| 4/1B || DosSubAlloc
|-
| 4/1C || Dos32SubAlloc
|-
| 4/1D || DosSubFree
|-
| 4/1E || Dos32SubFree
|-
| 4/1F || DosSubSet
|-
| 4/20 || Dos32SubSet
|-
| 4/21 || DosAliasMem
|-
| 4/22 || DosAllocProtectedMem
|-
| 4/23 || DosAllocProtHuge
|-
| 4/24 || DosAllocProtSeg
|-
| 4/25 || DosAllocShrProtSeg
|-
| 4/26 || DosQueryMemState
|-
| 4/27 || DosSubUnSet
|}