Note:
The from OS/2 2.11 fix pack 91 and OS/2 3.0 fix pack 8 the format of the STDA has changed to allow more meaningful time-stamp information. See New STDA Format at the end of this section for details.
Circular Trace Buffer (STDA)
Pointer to Pointer to Pointer to
First (#1) Next (#3) Last (#2)
│ │ │
Entry #3 Entry #10
┌────────┬──┬──┬──┐ ┌──┬──┬──┬──┬──┬──┐ ┌──┬──┬──┬──┬──┬──┬──┬─────┐
│SYSTRACE│ │ │ │.│ │ │ │ │ 0│ │...│ │ │ │ │ │ 2│ │... │
└────────┴──┴──┴──┘ └──┴──┴──┴──┴──┴──┘ └──┴──┴──┴──┴──┴──┴──┴─────┘
Pointer 1 ───┘ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─ Major Code
Pointer 2 ──────┘ │ │ │ │ │ │ │ │ │ │ │ │ └──── Length
Pointer 3 ─────────┘ │ │ │ │ │ │ │ │ │ │ └─────── Minor Code
│ │ │ │ │ │ │ │ │ └────────── Process ID
Timestamp ─┘ │ │ │ │ │ │ │ └───────────── Flags
Flags ────┘ │ │ │ │ │ └──────────────── Timestamp
Process ID ───────┘ │ │ │ └─────────────────── Data (2 bytes)
Minor Code ──────────┘ │ │
Length ─────────────┘ │
Major Code ────────────────┘
Field Descriptions: Trace Control Record
┌─────────────────────────┬──────┬────────────────────────────────────────┐ │Name │#Bytes│Description │ ├─────────────────────────┼──────┼────────────────────────────────────────┤ │ID of Data Area │8 │Contains ASCII 'SYSTRACE' │ ├─────────────────────────┼──────┼────────────────────────────────────────┤ │Pointer 1 │2 │Offset of first byte of the trace buffer│ ├─────────────────────────┼──────┼────────────────────────────────────────┤ │Pointer 2 │2 │Offset of last byte of the trace buffer │ ├─────────────────────────┼──────┼────────────────────────────────────────┤ │Pointer 3 │2 │Offset of next available byte in the │ │ │ │trace buffer │ └─────────────────────────┴──────┴────────────────────────────────────────┘
Field Descriptions: Trace Event Trailer Record (with Timestamp)
┌─────────────────────────┬──────┬────────────────────────────────────────────────────────────┐ │Name │#Bytes│Description │ ├─────────────────────────┼──────┼────────────────────────────────────────────────────────────┤ │Timestamp │2 │Timestamp in seconds and hundredths of seconds (Conditional │ │ │ │on bit 1 in the Flags byte) │ ├─────────────────────────┼──────┼────────────────────────────────────────────────────────────┤ │Flags │1 │Trace record flag │ │ │ │Bit 0: 0 indicates an internal kernel generated trace │ │ │ │record. │ │ │ │Bit 1: 0 indicates that a time-stamp is present. │ │ │ │Bit 2: 1 signifies that the trace record was generated in │ │ │ │protect mode. │ │ │ │Bit 3: 0 signifies a static trace record, 1 a dynamic trace │ │ │ │record. │ │ │ │Bit 4: 1 indicates an incomplete dynamic trace record. │ │ │ │Bit 5 - 7: reserved. │ ├─────────────────────────┼──────┼────────────────────────────────────────────────────────────┤ │PID │2 │ID of the process calling the API being traced │ ├─────────────────────────┼──────┼────────────────────────────────────────────────────────────┤ │Minor Code │2 │Minor Event Code │ ├─────────────────────────┼──────┼────────────────────────────────────────────────────────────┤ │Length │2 │Length of data for the traced API │ ├─────────────────────────┼──────┼────────────────────────────────────────────────────────────┤ │Major Code │1 │Major Event Code │ └─────────────────────────┴──────┴────────────────────────────────────────────────────────────┘
Remarks
The buffer returned by DosGetSTDA is a simple circular buffer that is a snapshot of the OS/2 System Trace buffer at the time that the API was called. The actual System Trace buffer is emptied by the call. The buffer contains a header record that has pointers to the FIRST, LAST and NEXT bytes in the buffer. The offsets of the FIRST and LAST bytes are constant and the offset to NEXT is used to indicate the last (most recent) trace record in the buffer. This pointer is logically moved backwards as the buffer is traversed. Since it is possible for a trace record to wrap back to the end of the buffer, it is necessary to look at each part of the data individually (trailer, timestamp and data) to determine whether the length of the data is greater than the distance between NEXT and FIRST. If the length is greater, then the data is continued at the offset to LAST.
For example (see figure below), the buffer has been traversed until the pointer to NEXT is at byte 26. The event trailer record is 8 bytes and the distance from NEXT to FIRST is 12, so the trailer is in contiguous memory. The pointer to NEXT is then set to byte 18. There is a timestamp which is two bytes. Our distance to FIRST is now 4 so the timestamp is contiguous and the pointer to NEXT is reset to 16. This record has 4 bytes of data attached to it. The distance to FIRST at this point is 2, so the data is wrapped: 2 bytes are adjacent to the NEXT, and the other 2 bytes begin at the pointer to LAST.
First (Byte 14) Next (byte 26) Last
│ │ │
┌────────────┬────┬──┬──────────────┬──┬──────────────┬─────────────┬────┐
│TRACE HEADER│ │T │EVENT TRAILER │T │EVENT TRAILER │(other trace │ │
│ (14 BYTES) │DATA│ S│DATA LENGTH: 4│ S│DATA LENGTH: 0│ records) │DATA│
└────────────┴────┴──┴──────────────┴──┴──────────────┴─────────────┴────┘
│ │
2 Bytes 2 Bytes
End of data in the trace buffer is indicated by a trace event trailer that contains a major code field of zero and a length field of zero.
The display format of the OS/2 system supplied tracepoint data is described in the System Tracepoints Reference chapter. Note that for data using the '%S' (ASCIIZ string) format type, the first byte of the data is reserved, bytes two and three contain the actual length of the string and the string begins at byte 4.
TRACEFMT Unformatted Trace Buffer
The trace formatter (TRACEFMT) is able to save the unformatted STDA buffer for formatting at a later date. The format of this buffer is as follows:
File Header ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐ │STDA LN│ D A T E T I M E │ C H E C K K E Y │ └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘ 0 4 f 1a STDA ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬──────────────────────── │S Y S T R A C E│STA│END│NXT│ TRACE RECORDS ..... └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴──────────────────────── 1a 22 24 26 28
Remarks
STDA LN
Note:
DosGetSTDA resets the internal start, end and next offsets after the STDA has been read. This allows trace formatting programs to detect an empty buffer.
For GA OS/2 2.x and 3.x the default start offset is 0x000e.
After fix pack 91 (OS/2 2.11) and fix pack 8 (OS/2 3.0) the the default start offset is 0x001e.