trcfmt File Format

Purpose

Stores trace templates.

Description

The trcrpt command, which formats trace reports, uses trace templates to determine how the data contained in trace entries should be formatted. All trace templates are stored in the master template file, /etc/trcfmt. Trace templates identify the trace hook ID, the version and release number, the indentation level, the event label, and data description fields. The data description fields contain formatting information for the trace entry data and can be repeated as many times as is necessary to format all of the trace data in the trace entry.

Modifying this File

The trcfmt file should only be modified using the trcupdate command. Trace hooks with values less than 010 are for internal use by the trace facilities. If these hooks are changed, the performance of trace, in particular trcrpt, is unpredictable.

Trace Entries

The data that is recorded for each traced event consists of the following elements in the following order:
  • A hook word containing a trace hook identifier and the hook type or size.
  • A variable number of words of trace data.
  • A timestamp.

The organization of the hook word depends on whether the application that produces the hook word is a 32-bit application or a 64-bit application.

32-bit trace hook words:

Item Description
HookWord The first two bytes of a HookWord contain the HookID and HookType. The contents of the second two bytes depends on the value of the HookType.
HookID The HookID is represented in the trace entry as 3 hexadecimal digits. For user programs, the hook id may be a value ranging from 0x010 to 0x0FF. HookIDs are defined in the /usr/include/sys/trchkid.h file.
HookType The HookType is a 4-bit value that identifies the format of the remainder of the trace entry. You specify the HookType when you record the trace entry.
Value
Trace Entry Format
1
The trace entry consists of only the HookWord. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine.
2
The trace entry consists of the HookWord and one additional word of trace data. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine.
6
The trace entry consists of the HookWord and up to five additional words of trace data. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine.
8
The trace entry consists of the HookWord and a data word followed by a variable number of bytes of trace data and a timestamp. The third and fourth bytes of the HookWord contain the number of bytes of trace data which follows the trace word. Trace entries of this type are recorded using the trcgent subroutine or the trcgenkt kernel service.
9
The trace entry consists of the HookWord and a timestamp. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine.
A
The trace entry consists of the HookWord, one additional word of trace data, and a timestamp. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine.
E
The trace entry consists of the HookWord, up to five additional words of trace data, and a timestamp. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine.
0
The trace entry consists of the HookWord and a data word followed by a variable number of bytes of trace data. The third and fourth bytes of the HookWord contain the number of bytes of trace data which follows the trace word. Trace entries of this type are recorded using the trcgen subroutine or the trcgenk kernel service.

64-bit trace hook words:

Item Description
HookWord The first two bytes of a HookWord contain internal trace meta-data. The second two bytes contain the size of the trace entry minus the hook word and any internal data (such as timestamps or CPU ID). The third two bytes contain the hook ID that can use the full two bytes. A 12-bit hook ID valid in a 32-bit application of the form 0xhhh is equivalent to the 16-bit hook ID 0xhhh0 in a 64-bit application. The last two bytes represent the sub-hook ID.
HookID The HookID is represented in the trace entry as three or four hexadecimal digits. Four-digit hook IDs are valid only in AIX® 6.1 and later releases. For releases earlier than AIX 6.1, the hook ID can be a value ranging from 0x010 to 0xFFF. For user programs in AIX 6.1 and later releases, the hook ID can be a value ranging from 0x0100 to 0xFFFF. However, if the first hexadecimal digit is zero, the last digit must also be zero. For example, HookID 0AA0 is legal, but 0AAA is not. Many of the AIX system hook IDs are defined in the /usr/include/sys/trchkid.h file.

Data Pointer

The DATA POINTER is a pointer to the current position in the trace entry. The DATA POINTER is changed by the trcrpt as it interprets the template and formats the trace entry. The initial position of the DATA POINTER is the third byte of the HookWord for HookTypes 1, 9, 2, A, 6, and E and the first byte after the HookWord for HookTypes 0 and 8.

Trace Data Formatting

Indentation Level

The formatted trace data is aligned in columns corresponding to the source of the trace event. This is identified in each template using the L=X descriptor. The possible values of the L=X command are as follows:

Item Description
L=APPL Outputs the trace data in the APPL (application) column.
L=SVC Outputs the trace data in the SVC (system call) column.
L=KERN Outputs the trace data in the KERN (kernel) column.
L=INT Outputs the trace data in the INT (interrupt)column.

Continuation Character

A \ (backslash) at the end of a line must be used to continue a template on the next line.

Labels or Text Strings

Individual strings (or labels) can be separated by any number of spaces or tabs, but all excess spacing is compressed to one blank on the trace report unless other format structures are put into effect. Labels are enclosed in double quotes (" ").

Item Description
\n Outputs to a new line. Data on the new line is left-justified according to the value set in the INDENTATION LEVEL.
\t Inserts a tab. Tabs are expanded to spaces, using a fixed tabstop separation of 8.

Format Codes

DATA POINTER Position Format Codes

Item Description
Gm.n Sets DATA POINTER to byte.bit location m.n.
Om.n Advances DATA POINTER by m.n byte.bits.
Rm Decrements DATA POINTER by m bytes.

Output Format Codes

Item Description
Bm.n Sends output in Binary format where m is the length of the data in bytes and n is the length in bits. Unlike the other printing format codes, the DATA POINTER can be bit aligned and is not rounded up to the next byte boundary.
D2, D4 , D8 Converts data to signed decimal format. The length of the data is two, four, or eight bytes, and the DATA POINTER is advanced by the same number of bytes.
F4 Converts data to C type 'float' floating point format. The length of the data is 4 bytes, and the DATA POINTER is advanced by 4 bytes.
F8 Converts data to C type 'double' floating point format. The length of the data is 8 bytes, and the DATA POINTER is advanced by 8 bytes.
S1, S2, S4 Left-justifies ASCII strings. The length of the string is in the first byte (half-word, word) of the data. The length of the string does not include this byte.
T4 Outputs the next 4 bytes as a date and time string.
U2, U4 , U8 Converts data to unsigned decimal format. The length of the data is two, four, or eight bytes, and the DATA POINTER is advanced by the same number of bytes.
Xm Converts data to hexadecimal format. The DATA POINTER is advanced by m bytes.

Interpreter Format Codes

Item Description
E1, E2, E4 Outputs the next byte (half_word, word) as an 'errno' value, replacing the numeric code with the corresponding #define name in the /usr/include/sys/errno.h file. The DATA POINTER is advanced by 1, 2, or 4 bytes.
P4 Uses the next word as a process ID, and outputs the pathname of the executable with that process ID. Process IDs and their pathnames are acquired by the trace command at the start of a trace and by the trcrpt command via a special EXEC tracehook. The DATA POINTER is advanced by 4 bytes.

Switch Statements

A SWITCH statement is a format code followed by a comma. Each CASE entry of the SWITCH statement consists of:

  1. A 'MatchValue' with a type (usually numeric) corresponding to the format code.
  2. A simple 'String' or a new 'Descriptor' bounded by braces. A descriptor is a sequence of format codes, strings, switches, and loops.
  3. A comma delimiter.

The switch is terminated by a CASE entry without a comma delimiter. The CASE entry is selected as the first entry whose MatchValue is equal to the expansion of the format code. The special matchvalue '\*' is a wildcard and matches anything.

The DATA POINTER is advanced by the format code.

LOOP Statements

Loops are used to output binary buffers of data; therefore, the descriptor for a LOOP is usually X0 or X1. The syntax of a loop is LOOP format_code {descriptor}. The descriptor is executed N times, where N is the numeric value of the format code.

The DATA POINTER is advanced by the format code and by the operations of the descriptor.

Macros

Macros are temporary variables that work like shell variables. They are assigned a value with the syntax:

{{ $xxx = EXPR }}

where EXPR is a combination of format codes, macros, and constants. The operators + (addition), - (subtraction), / (division), and * (multiplication). are permissible within macros.

Predefined Macros

Macro Name Description
$BASEPOINTER Marks the starting offset into an event. The default is 0, but the actual offset is the sum of the values of DATA POINTER and BASE_POINTER. It is used with template subroutines when the parts of an event have same structure and can be printed by same template but may have different starting points into an event.
$BREAK Ends the current trace event.
$D1 - $D5 Dataword 1 through dataword 5. The DATA POINTER is not moved.
$DATAPOINTER Activates the DATA POINTER. It can be set and manipulated like other user macros.
$DEFAULT Uses the DEFAULT template 008.
$ERROR Outputs an error message to the report and exit from the template after the current descriptor is processed. The error message supplies the logfile, the logfile offset of the start of that event, and the trace ID.
$EXECPATH Outputs the pathname of the executable for the current process.
$HB Number of bytes in trcgen subroutine variable length buffer. This is also equal to the 16-bit hook data.
$HD Hook data (lower 16 bits).
$HT Allows for multiple, different trchook subroutine call with the same template. The return values of the $HT macro are:
Value
Description
1
hook word
2
hook word and one additional word
6
hook word and up to five data words
9
hook word and a timestamp
A
hook word, one data word, and a timestamp
E
hook word, up to five data words, and a timestamp.

The DATA POINTER is not changed.

$L1-$L2 Long (64-bit) dataword 1, or 2. For example, $L1 is the concatination of $d1 and $d2. The 64-bit values would most likely have been traced with the TRCHK64L1 or TRCHK64L2 macros. No change to data pointer.
$LOGID0 Current logfile offset at the start of the event.
$LOGIDX Current logfile offset into this event.
$LOGFILE Returns the name of the logfile being processed.
$MCR0, $MCR1, $MCRA Machine MCR registers 0, 1, and A.
$PID Outputs the current process ID.
$PMC1 - $PMC8 Machine PMC registers 1 through 8.
$PURR Machine PURR register.
$RELLINENO Line number for this event. The first line starts at 1.
$SKIP Ends the current trace event without printing.
$STOP Immediately ends a trace report.
$SVC Outputs the name of the current system call.
$TID Outputs the current kernel thread ID.
$TRACEID Returns the trace ID of the current event.

Built-in Macros

The built-in macros are:

Item Description
buftofilename (bp) Looks up filename by buf struct.
fdinstall ( ) Installs the file descriptor and the current v-node from lookuppn as a file_descriptor/v-node pair for this process ID.
fdtofilename ( ) Looks up the filename for the given file descriptor for this process ID. If the filename is not found, nothing is output.
flih ( ) Advances the Interrupt Depth.
lookuppninstall1 Installs the filename as the current file with the trcrpt command.
lookuppninstall2 Install the v-node as the current v-node. It also installs the current_v-node/current_file as a v-node/filename par.
pfsrdwrinstall1 (vp) Sets the current v-node of this process to vp.
pfsrdwrinstall2 (VA.S, count) Creates a virtual address/v-node structure to be filled in be VMM hooks if a page fault occurs.
resume ( ) Decrements the Interrupt Depth.
setdelim ( ) Inhibits spaces between characters.
slihlookup ( ) Looks up the second level interrupt handler.
sidtofilename (sid) Looks up filename by segment ID.
vmbufinstall ( ) Looks up the v-node of the file through the virtual page/sid and install the v-node and buf as a v-node/bp pair. This will be used by lvm on down.
v-nodetofilename (vp) Looks up filenames by v-node.
vpagetofilename (vpage, sid) Looks up filenames by vpage and segment ID.

Files

Item Description
/etc/trcfmt Stores trace templates.
/usr/include/sys/trchkid.h Defines hook identifiers.
/usr/include/sys/trcmacros.h Defines trace macros.