TP Keyword

The TP parameter is a required keyword parameter. If TP is specified more than once for a single tracepoint definition, the tracepoint is discarded. TP has three mutually exclusive definitions which can be coded as:

        TP=@STATIC,

where:

STATIC

defines this tracepoint entry to be used only for creating a trace format statement for the TFF file. No tracepoint definition is created for the TDF, and the only other TRACE parameters that will be used are DESC, MINOR and FMT. This is used to create trace formatting information for static tracepoints. If the TSF contains only @STATIC directives, no TDF files are created.

        TP=@filename,linenum,

where:

filename

is an ASCII string specifying the name (including extension) of a source filename used in creating the module. The source filename is stored in the debug information contained in the executable module, so debug information must exist to use this parameter. The filename is not case sensitive.
linenum
is a decimal number specifying the line number in the given source file name to place the tracepoint.

Note: Debug information must exist to use this option. The statement at the given source linenum may have been rearranged during compiler optimization, so the developer must use this with caution. If the linenum is not found in the debug information, the tracepoint is applied at the next linenum defined in the debug information and a warning message is issued to the user.

An example to apply a tracepoint to line 35 of file stubfile.c is:

    TRACE   MINOR=0x700A,              /* puts tracepoint on code at line */            TP=@stubfile.c,35,.....    /*  35 of source file stubfile.c   */

        TP=.name[{+|-}offs][,RETEP],

where:

name

is a public label or an entry point name of a procedure to be traced. The "." preceding name is required. Name must be found in the debug information in the module or name must be a public symbol as found in the MAP file. If debug information is used, the address of this tracepoint will be immediately following the prologue of the procedure. If MAP information is used, this address points to the opcode at the given label.

If the procedure was compiled with debug support, Name is case sensitive. If not, C language functions will be case sensitive and begin with an underscore "_" character unless the function is declared with the Pascal calling convention, in which case the underscore is omitted and the name is capitalized.

offs
(optional) is a decimal (specified as nnnnnnnn) or hex (specified as 0xnnnnnnnn) offset from the entry point address.
RETEP
(optional) specifies that the tracepoint will be inserted at the return address corresponding to this entry point. This is just before the procedure epilogue is executed and at this point the procedure's automatic data is still addressable from register (E)BP and the return code (if any) is set up in (E)AX.

The module must include information supplied by the debug compile option (see Symbolic Debug Support), meaning that the source language must have been C, otherwise an error message will be generated and this tracepoint discarded.

When the RETEP is used, the name must be a valid entry point to a procedure.

Note: The RETEP option depends upon the manner in which a C compiler generates its code. Therefore this option may not work will some of the new compilers.

Note: For ASM functions to accomplish tracing, a label must be made public to have a tracepoint applied. Therefore, to accomplish "POST" tracing, a label must be made public at the return statement.

The following are partial examples of Pre/Post tracing of DosOpen:

      TRACE   MINOR=0x0001,              TP=.DosOpen,.....            /* Pre-invocation tracing */

      TRACE   MINOR=0x8001,
              TP=.DosOpen,RETEP,.....      /* Post-invocation tracing */

It is not possible to set dynamic tracepoints on the following machine instructions:

0x9C

PUSHF
0xCC
INT 3
0xCD
INT n
0xCE
INTO
0x62
BOUND
0x69
IMUL
0x6B
IMUL
0xF6
DIV, IDIV, MUL, IMUL, NEG, NOT, TEST (immediate)
0xF7
DIV, IDIV, MUL, IMUL, NEG, NOT, TEST (immediate)

TRCUST gives an error for these opcodes and the tracepoint is rejected.

In all cases, two tracepoints cannot be applied at the same address.

---

[Back: MINOR Keyword]
[Next: OPCODE Keyword]