.T - Dump the System Trace Buffer

Dumps the system trace buffer.

Syntax:

────.T ─────┬───────────┬─┬───────────────────────────┬───────
              ├── count ──┘ └── MAJ=mm ────┬────────────┤
              │                            └── MIN=nn ──┘
              │
              └──── S ────── filespec ──────────────────────────

Parameters:

count

The number of trace entries to print, starting with the most recent. If not specified then the entire trace buffer will be dumped.
MAJ=mm
Specifies that only trace events with major code mm should be displayed.

See System Trace Facility - Major Code Assignments for a information on the deployment of trace major and minor codes in OS/2.

Warning: The Kernel Debugger may fail to process the MAJ= parameter correctly. Under some circumstances the debug kernel may hang. Use this option advisedly!


MIN=nn
Specifies that only trace events with minor code nn should be displayed.

This option required the specification of a major code using the MAJ= parameter.

See System Trace Facility - Major Code Assignments for a information on the deployment of trace major and minor codes in OS/2.

Warning: The Kernel Debugger may fail to process the MAJ= parameter correctly. Under some circumstances the debug kernel may hang. Use this option advisedly!


S
Specifies that the trace buffer should be saved to a file named in filespec.

This option is only available to the Dump Formatter.

The saved trace file may be subsequently formatted using the OS/2 TRACFMT command.

filespec
The file specification for the saved trace buffer.

The filespec may be fully qualified. The path defaults to the current directory.

Results & Notes:

The trace is activated using the OS/2 TRACE command.

If the trace is not active then the following message is generated:

    Trace not on

The trace buffer is allocated in a single segment (STDA) whose selector may be located from global symbol ras_stda_addr. The STDA is a circular buffer whose entries are recorded in reverse order. The header gives the offsets to the first, last and current entires. The format of the trace buffer is described under System Trace Data Area..

The major codes being traced are recorded in a bit string located at label ras_mec_table. Each active major code has its corresponding bit set.

The minor codes being traced are recorded in a bit string whose selector is located at label ras_min_table. The minor code table contains 32 byte entries, each corresponding to a major code. Each bit of each entry corresponds to a minor code within the major. If the bit is set then the minor code is traced.

When tracing by Pid is active then the ptda_rasflag (PTDA +0x39a) is set to 0xff.

The status of system tracing is recorded in status byte at label ras_systr_flags. The following flags are defined:

┌───────────────┬──────────┬──────────────────────────────┐
│name           │bit mask  │description                   │
├───────────────┼──────────┼──────────────────────────────┤
│RF_TRCAVAIL    │0x80      │System Trace Available        │
├───────────────┼──────────┼──────────────────────────────┤
│RF_TRCPAUSED   │0x40      │Trace paused                  │
├───────────────┼──────────┼──────────────────────────────┤
│RF_TRCPID      │0x20      │Trace by PID                  │
├───────────────┼──────────┼──────────────────────────────┤
│RF_TRCERRCOUNT │0x10      │Tracing until error count     │
├───────────────┼──────────┼──────────────────────────────┤
│RF_TRCSUSPEND  │0x08      │Suspend due to error count    │
├───────────────┼──────────┼──────────────────────────────┤
│RF_TRCMINORCD  │0x04      │Tracing by Minor Code         │
└───────────────┴──────────┴──────────────────────────────┘

Under the kernel debugger the system trace buffer cannot be saved directly. However by setting the RF_TRCPAUSED bit in ras_systr_flags flag byte, the trace may be suspended and saved at a later time by using one of the system trace utilities (TRSPOOL, TRACEFMT or TRACEGET) or from a system dump. When setting RF_TRCPAUSED be certain to OR in the flag bit.

.T command output appears as follows (see note at the end of this section for information on recent changes to the format of trace output):

  MAJ=04  MIN=0089  PID=0006  CONTEXT=KERNEL:PROTECT
  MAJ=06  MIN=008c  PID=0000  CONTEXT=KERNEL:PROTECT
     00 00                                             ..
  MAJ=06  MIN=000c  PID=0000  CONTEXT=KERNEL:PROTECT  TS=1336
     08 00                                             ..
  MAJ=04  MIN=0009  PID=0006  CONTEXT=KERNEL:PROTECT
  MAJ=04  MIN=0089  PID=0006  CONTEXT=KERNEL:PROTECT

Each of the fields is defined as follows:

MAJ=

The traced event major code.
MIN=
The traced event minor code.
PID=
The current Pid when the event occurred. See .P command for information on displaying active Pids.
CONTEXT=system:processor
The system and processor context under which the event was traced.

system context may be:

KERNEL

If the trace record was created internally by a kernel routine.
API
If the trace record was created externally by use of the DosDynamicTrace or DosSysTrace APIs.

See Dynamic Trace Customiser for information on creating dynamic trace records (via DosDynamicTrace).

See DosSysTrace (Static Trace Event Recording) for information on creating static trace records.

processor context may be:

PROTECT

If the trace record was created when the system was running in protect mode.
REAL
If the trace record was created when the system was running in real mode.
TS=hhss
The system timestamp where hh is 100th seconds and ss is seconds.

The timestamp is taken from the Global Information Segment (GISEG+0xa). It is only recorded in the trace record if the time has changed since the previous timed stamped record was recorded.

Note: TRACEFMT treats this value as a word length fixed number of two decimal places.

trace data
Additional trace data.

A trace event may be accompanied with additional trace data, in which case it is dumped in hexadecimal and ASCII format on the following line.

Related information on the system trace facility may be found in:

System Trace Facility

Dynamic Trace Customiser

OS/2 Command reference - TRACE Command

OS/2 Command reference - TRACEFMT Command

OS/2 Command reference - TRACEBUF CONFIG.SYS statement

New Trace Format

From OS/2 2.11 fix pack 91 and OS/2 3.0 fix pack 8, the system trace has been enhanced to include more useful timestamp information. The Kernel Debugger and Dump Formatter were updated in fix packs 16 (OS/2 3.0) and 105 (OS/2 2.11) to take account of the new format.

Warning:

The use of the .T command after the new trace format was implemented, but before the Kernel Debugger and Dump Formatter were updated, caused the Kernel Debugger and Dump Formatter to trap.

The following is an example of the new format:

#Trace On at 0000,0000,0000,0000,0000,0000,0000
Trace Off at 0000,0000,0000,0000,0000,0000,0000
  MAJ=03  MIN=0009  PID=0000  CONTEXT=KERNEL:PROTECT  TS=3611,382e
     00 00 00 00 bd 55 f5 ff 60 01 00 00 02 00 01 00   ....=Uu.`.......
  MAJ=03  MIN=000f  PID=0000  CONTEXT=KERNEL:PROTECT  TS=3611,382e
     00 00 cc cc f1 27 00 00 00 10 00 00 06 02 01 00   ..LLq'..........
     c8 3c f2 ab                                       H<r+
  MAJ=03  MIN=0008  PID=0017  CONTEXT=KERNEL:PROTECT  TS=3611,252d
     00 00 00 00 93 86 e5 1b 5b 00 00 00 02 22 01 00   ......e.[...."..
  MAJ=03  MIN=0008  PID=0017  CONTEXT=KERNEL:PROTECT  TS=3611,222d
     00 00 00 00 93 86 e5 1b 5b 00 00 00 02 22 01 00   ......e.[...."..
  MAJ=03  MIN=0008  PID=0017  CONTEXT=KERNEL:PROTECT  TS=3611,222d
     00 00 00 00 93 86 e5 1b 5b 00 00 00 02 22 01 00   ......e.[...."..

The formatted trace is headed by a pair of time-stamps that give the time tracing was initiated and terminated. These are of the form:

          YYYY,xxMM,xxDD,xxHH,xxmm,xxss,xxhh

where:

YYYY

is years,
MM
is Months
DD
is Days,
HH
is hours,
mm
is minutes,
ss
is seconds.
hh
is 1/100th seconds,
xx
ignore.

The time-stamp of each trace record is now shown as a pair of word values of the form:

           TS=MMHH,hhss

where

MM

is minutes,
HH
hours,
hh
1/100s seconds and
ss
seconds.

Note:

The byte reversal occurs because the time values are originally byte values which are displayed as words.

---

[Back: .SYSDUMP - Force a System Dump and Restart the System]
[Next: System Trace Facility - User Guide]