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 (or dynamic tracepoints generated directly by the DTRACE command). If the TSF contains only @STATIC directives, no TDF files are created and MODNAME is then not required.
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.
Note:
path information may be specfied with filename when also specified at compilation time.
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 */
Use of line number refernece affords great flexibility is tracepoint location, however the user will need to modify the TSF file every time referenced source files are updated. To facilitate this the MAKETSF utility may be used to generate line number references automaticaly from TSF statements embeeded as comments in C or Assembler source.
TP=.name[{+|-}offs][,RETEP[=retopt[+retopt...]]],
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 unless the /PREINV command line switch is specified. In this case TRCUST attempts to locate the instruction following the
MOV EBP,ESP
or
MOV BP,SP
instructions as with done when debug information is used. Use of /PREINV
allows parameter and local variable references to be made relative to
EBP in non-optimised code.
See Source Level Symbolic Support and MAP File Support for information on using symbolic references. offs
is a decimal (specified as nnnnnnnn) or hex (specified as 0xnnnnnnnn) offset from the entry point address.
specifies that the tracepoint will be inserted at the return address corresponding to this entry point.
Default criteria for specifying the return point are specified by the /RM RETEP mode command line option. TRCUST will search back from the end of the routine for the instruction sequence matching the RETEP mode. The length of the search is governed by the /RS command line option. The default RETEP mode may be overridden per tracepoint by coding one or more optional retopt keywords, separated by a + sign with RETEP. The following keywords are allowed:
CV
Note: to reduce the hazard of generting a tracepoint on a non-instruction boundary, JMP instructions with 0xFF opcodes are not selected.
If more than one option is specified the RETEP uses the following order of precidence: CV, LRET, RET, LEAVE, JMP.
When the RETEP is used, the name must be a valid entry point to a procedure.
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 newer compilers or with code optimisation.
Warning:
Use of RETEP can run the risk of having a tracepoint not generated on an
insruction boundary. The result of which would be unpredictable and probably
cause the traced program to trap. This risk is grealty reduced by allowing
the RETEP mode to default to /RM2. If the user chooses to widen the
RETEP criteria then appropriate validation of the resulting tracepoints
must be made.
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.
Partial examples of Pre/Post tracing of DosOpen follows:
TRACE MINOR=0x0001, TP=.DosOpen,..... /* Pre-invocation tracing */
TRACE MINOR=0x8001,
TP=.DosOpen,RETEP,..... /* Post-invocation tracing */
Note: It is not possible to set dynamic tracepoints on the following machine instructions:
0x9C
TRCUST gives an error for these opcodes and the tracepoint is rejected.
Note: No more than one tracepoint may be applied to a given address.