OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dumptool.zip / TRUTILS.ZIP / trctools.doc < prev next >

Wrap

Text File | 1998-11-11 | 41KB | 1,136 lines

TRCTOOLS: System Trace Tools Authors: Richard Moore & Pete Guy Version: 1.14 Date: 11th Nov 1998 This package comprises a consolidated set of the latest (beta test) system trace customisation utiltities. This package consolidates and replaces the following OS2TOOLS packages: DTRACE, TRSPOOL The utilities supplied in this edition of TRCTOOLS are: SYSSPLIT: Breaks up a SYSTEM.TDF or SYSTEM.TFF file into its constituent *.TDF and *.TFF files. TDFLST: Formats a TDF file (except SYSTEM.TDF) into a readable listing that may be used as input to DTRACE, either to re-generate the TDF or to apply the tracepoints. TFFLST: Formats a TFF file (except SYSTEM.TFF) into a readable listing that may be processed by TRCUST to re-generate the TFF. TRCUST: Latest version of the Trace Cusomizer. TRACE: Latest version of the Trace Command. TRACEFMT: Latest version of the Trace Formatter. TRSPOOL: Latest version of the Trace Spooler. TRSTOP: Termination utility for TRSPOOL. DTRACE: Latest version of the DTRACE utility. DYNDD: A sample dynamic trace device driver exit. SAMPLRPN: Sample RPN files for DTRACE. MAPTSF: Generates a TSF from a MAP file. MAKETSF: Extracts trace definiitons from source files and generates line number information. SELTSF: Extracts a subset if tracepoints from TFFLST output. SELRPN: Extracts a subset if tracepoints from TDFLST output. TRACEF: Extracts (filtres) a subset of formatted trace entries. The last three commands have been supplied by Pete Guy. All utilities are described in detail below. An example of the use of TFFLST and TDFLST is given at the end of this document. Descriptions of TRCTOOLS Utilities ---------------------------------- TRACEFMT -------- TRACEFMT contains a number of string formatting fixes and also fixes two traps (a floating-point exception and an access exception). This version of TRACEFMT is compatible with the Warp 3.0 Fix Pack 35 trace enhancments. TRACEFMT now supports the %C formatting control character. See TRACE.DOC for details of additional enhancements specific to OS2 Warp V3 Fix Pack 35 in TRACECMD.ZIP. Version 2.3 fixes problems with selection criteria where <, <=, > or >= comparisons were used. It also handled time comparisions incorreclty. Time specified in an abbreviated form as follows in now handled correctly: Abbreviated form Equivalent form h h:0:0.0 h:m h:m:0.0 h:m:s h:m:s.0 TRACE ----- Version 2.4 contains adds syntax help. The TRACE command contains support for non-DLL modules, which was regressed when WARP 3 was released. TRACE ON|OFF <module_name> | <tdfname> now supports a fully qualified module name including path. If a short name with no extension is supplied the name.DLL is assumed. The TDF for the module must contain the same name with the extension TDF. TDFs are searched for in the following order: Current directory + DPATH OS2\SYSTEM\TRACE OS2\SYSTEM\TRACE\SYSTEM.TDF module directory If no load module is found then TRACE searches for a TDF file with name specified, if found uses the module name embedded within the TDF. Thus for private TDFs, the TDF file may be stored in the same directory as the traced module. If the module path information is not supplied then TRACE uses LIBPATH for DLLs and PATH for other module types. See TRACE.DOC for details of additional enhancements specific to OS2 Warp V3 Fix Pack 35 in TRACECMD.ZIP. TRCUST ------ The base version of TRCUST shipped with the Warp 3.0 and 4.0 ToolKits is 2.0. TRCUST 3.05 provides the following enhancements and fixes since version 2.0: Regression for NE modules, which may result in a TRAP D but also results in an invalid TDF being generated. MODNAME is not required for Static Tracepoints. Supports MAXDATALEN may be specified upto 4099. Note, MAXDATALEN above 512 is permissible only on Warp 3.0 Fix Pack 35 and higher. MAXDATALEN defaults to 512 Allows formatting controls to be specified in lower case. Supports Major codes up to 0xffff. Note, MAJOR code above 255 are permissible only on Warp 3.0 Fix Pack 35 and higher. Fixed problems with keyword order on the TRACE statement. Allows the %C formatting control to specify an ASCII character interpretation of a byte of trace data. Allows the /NODE switch to bypass module debug information processing. RETEP has been extended to work with MAP files and HLL version 4 style debugging information. Case insensitive references to MAP file symbols is allowed. Line number support for HLL 4 (VisualAge C++) All TSF keywords are case insensitive. All TRCUST parameters are case insensitive. TSF TRACE statement keywords are now order independent. /L= parameter introduce to allow MODNAME to specify a different filespec to the load module read by TRCUST. /P allows the path information specified with MODNAME to be retained in the built TDF. Fixes a TRAP caused by large line number tables with HLL3 (CSET++ 2.01) Fixes a TRAP caused by using non-code DLLs. Fixes a problem where TEST, NOT and NEG instructions with opcode byte 0XF6 or 0XF7 were disallowed as tracepoints. Fixes a problem with RETEP compatibility processing with previous versions, adds the /RP parameter and extends /RM options. The syntax for TRCUST 3.05 is as follows: Usage1: Trcust filename1 filename2 /M=mapfile /W{0|1|2} /D + /L=loadmod /NODE /NOLN /RM{0-6} /RSnnn /I /P filename1 is Trace Source File filename2 is Trace Defintion File (Optional) /M=mapfile is map filename to use (Optional) /W{0|1|2} is warning level to use (Optional) /D allows duplicate minors (Optional) /L=loadmod is file name of load module (Optional) /NODE ignore debug information (Optional) /NOLN ignore line numbers (Optional) /RM{0-7} RETEP match criteria (Optional) /RSnnn RETEP search range (Optional) /RP RETEP Pascal returns allowed (Optional) /I Case insensitive map symbols (Optional) /P Retain MODNAME Path Info (Optional) Usage2: Trcust filename1 /C=dest_tff /W{0|1|2} filename1 is Trace Combine File containing TFF filenames dest_tff is destination TFF name for combined records /W{0|1|2} is warning level to use (Optional) Usage 1 has introduced sever new parameters and some previouly undocumented parameters, which are now described: /L=loadmod allows TRCUST to use a different file specification to the name specified by the MODNAME TSF statement. TRCUST needs to exctract information from the load module to generate the TDF. The module name is also required by the TRACE command and so is recorded in the TDF from the MODNAME statemenmt. /L is useful in cases where a module is built using one name and subsequenlty renamed when installed, or where the load module is built in a target directory which differs from that of the TSF. /NODE forces TRCUST to ignore debugging information even if present. This is provide for cases where a) the user wishes to use MAP symbols in preference to debugging info. b) the level of debugging info in not supported by TRCUST and errors are produces if it is used. NB debugging information is not a public standard. Some compilers may appear to emulate Code View level 0, HLL 3 or HLL4, which not actually doing so. /NOLN forces TRCUST to ignore module line number records but honor any other debugging informantion present. This option is provided for cases where line number information does not conform to supported specifications. N.B /NODE implies /NOLN /I allows MAP file references to public symbols to be made case insensitively. /RM{0-7} specfifes the default Return Entry Point (RETEP) match criteria. By default, RETEP will use mode 2, however the following modes may be specified: 0 - Disallow RETEP. 1 - Take RETEP from Code View symbol records only. NB HLL does not provide return information. 2 - Use mode 1 then search for a LEAVE+RET or POP EBP instruction sequence near the end of the routine. 3 - Use mode 2 then search for an isolated LEAVE instruction near the end of the routine. 4 - Use mode 2 then search for an isolated RET instruction near the end of the routine. 5 - Use modes 2 and 3 combined. Version 2.0 of TRCUST uses this search mode. 6 - Use mode 4 then search for an isoloted JMP instruction near the end of the routine. 7 - Use mode 6 but search for an isolated LEAVE instruction near the end of the routine, before searching for JMP. NB Determination of RETEP is subject to the following limitations: 1 - Only the last return from a routine is located. 2 - Only mode 1 can accurately determine the last return, however this is only available to code-view version 0 modules. 3 - Searching for instruction sequences may result in a tracepoint erroneously being placed within an instruction. 4 - It may not be possible to use RETEP to define the return tracepoint for modules that use private (particularly optimised) calling conventions. 5 - The default mode is 2. This reasonably safe. Higher modes are less safe. 6 - Use mode 5 for compatible behaviour with earlier versions of TRCUST. However, note that earlier versions of TRCUST erroneously permitted certain tracepoints which are not permitted using mode 5. 7 - To avoid possible errors, JMP instructions with opcode 0xff are not selected. /RP modifies RETEP processing to allow Pascal Return instructions (RET n) to be included in the search criteria with normal returns. Use this with 16-bit code where you know pascal returns are generated. /RSnnn specifies how far RETEP will search from the end of a routine to find the return instruction sequence. This defaults to 18 bytes however RETEP will not search before the start of the routine. The RETEP keyword of the TSF TRACE statement has been extended to allow specific RETEP search criteria to be specified per tracepoint. The syntax for RETEP is: RETEP[=options] where options may be a combination of the following keywords separated by + signs: CV - use CV information LRET - search for a LEAVE+RET or POP EBP + RET sequence near the end of the routine. RET - search for RET instruction near the end of the routine. JMP - search for JMP instruction near the end of the routine. LEAVE - search for a LEAVE instruction near the end of the routine. If more than one option is specified the RETEP uses the following order of precidence: CV, LRET, RET, LEAVE, JMP DTRACE ------ See DTRACE.DOC for a full description of DTRACE 4.3 TRSPOOL ------- See TRSPOOL.DOC for a full description of TRSPOOL 4.0 DYNDD ----- See DYNDD.TXT for a description of this sample device driver. SAMPLRPN -------- See SAMPLRPN.DOC for a full description. SYSSPLIT -------- Syntax: SYSSPLIT <input_file> Trace definition files - SYSTEM.TDF: When applying tracepionts to a DLL, TRACE.EXE will search the current path, then the DPATH for the dll_name.TDF file. If not found it searches OS2\SYSTEM\TRACE\SYSTEM.TDF and finally, OS2\SYSTEM\TRACE\dll_name.TDF. If the system trace definitions for a particular module needs to be replaced or modified then SYSSPLIT may be used to split SYSTEM.TDF into its constituent TDF files. The resultant *.TDF files may be saved in OS2\SYSTEM\TRACE. Because of the search order employed by TRACE.EXE it is recommended that SYSTEM.TDF be renamed after being split. The file names of the split *.TDFs will be chosen to be the original names used to create SYSTEM.TDF. N.B. The trace definitions for the OS2KRNL may be in OS2KRNL.TDF or DOSCALLS.TDF. The TRACE command recognises the keyword KERNEL as an alias for each of the kernel TDF names. TRACE.EXE searches the DPATH for DOSCALLS.TDF, but due to a bug only \OS2\SYSTEM\TRACE of the current drive (as opposed to the boot drive) for OS2KRNL.TDF. The result of this latter point is that TRACE ON KERNEL will only work for OS2KRNL.TDF if a directory from the boot drive is curent. The TDFLST utility mat be used with each of the resultant TDFs to format the trace point definitions. Trace formatting files - SYSTEM.TFF: When formatting the system trace, TRACEFMT.EXE will search OS2\SYSTEM\TRACE\SYSTEM.TFF for the formatting templates for each major code encountered in the trace buffer. If a major code is not found in SYSTEM.TFF then TRACEFMT will search for a file named TRC00xx.TFF, where xx is the major code number in hexadecimal. If the formatting templates for a particular module needs to be replaced or modified then SYSSPLIT may be used to split SYSTEM.TFF into its constituent TFF files. The resultant *.TFF files may be saved in OS2\SYSTEM\TRACE. Because of the search order employed by TRACEFMT.EXE it is recommended that SYSTEM.TFF be renamed after being split. The file names of the split *.TFFs will be chosen to be the original names used to create SYSTEM.TDF, that is names formed from their major codes. The TFFLST utility mat be used with each of the resultant TFFs to format the trace point definitions. N.B. TRCUST has the ability to combine TFFs for the same major code. This is not to be confused with the special SYSTEM.TFF and SYSTEM.TDF files that are concatenations of dissimilar major code definitions. TDFLST ------ Syntax: TDFLST <tdf_file> TDF list formats a TDF as DTRACE compatible trace program file. The output is directed to STDOUT, which may be captured in a file using the redirection operator (>). Trace definitions may be modified or supplemented using an editor and the TDF rebuilt using DTRACE BUILDTDF. TFFLST ------ Syntax: TFFLST <tdf_file> TFF list formats a TFF as TRCUST compatible source. The output is directed to STDOUT, which may be captured in a file using the redirection operator (>). Trace formatting templates may be modified or supplemented using an editor and the TFF rebuilt using TRCUST. N.B. TRCUST is used for generating TDFs and TFFs. The keyword, TP=@STATIC directs TRCUST solely to generate TFFs. Normally this is used with static trace but equally valid for dynamic trace where the tracepoints have already been defined. N.B. Large TDF and TFF files may take a minutes or two to list. A degree of searching and cross-referencing has to take place before the listing is produced. Consequently the may be a considerable pause before the listing is produced. MAPTSF 1.7 ---------- Syntax: MAPTSF map_file [/MAJOR=major_code] [/MODNAME=name] [/MAXDATALENGTH=max_data_length] [/MINORSTART=minor_code] [/TEMPLATE=template_file] [/LOGSTACK=stack_bytes] [/EXCLUDE=string[*][,....]] [/INCLUDE=string[*][,....]] [/REGISTERS=reg[,reg]...] [/LOGRETURN] [/RETEP] [/CASESENSITIVE] [/TYPES] [/GROUPS=string[,.....]] This utility will generate a TSF from a MAP file. One tracepoint is generated for each public code symbol. Optionally a return tracepoint may be generated for each public code symbol. map_file is the only required parameter. The remaining optional parameters have the following meaning: /MAJOR specifies the major code to be used in the MAJOR= statement of the TSF . If omitted, TRCUST will select the default major code of 1 when compiling the TSF. /MODNAME specifies the module name to be used in the MODNAME= statement of the TSF. If omitted, MAPTSF will use the module name that appears in the second line of the MAP file. Note, the MAP file excludes the module extension. TRCUST will assume an extension of .DLL if not specified. /MAXDATALENGTH specifies the MAXDATALENGTH= statement of the TSF. If omitted, TRCUST will assume the default of 512 when compiling the TSF. /MINORSTART specifies the first minor code. Subsequent tracepoints have incremental minor codes. If omitted, the MINOR= statement is not generated. TRCUST will assume an initial minor code of 1 and increment for each tracepoint. /INCLUDE specifies a comma delimited list of case insensitive strings used as inclusion criteria for public symbols. An optional trailing * signifies a generic match. If both /INCLUDE and /EXCLUDE are specified then the logical OR of their criteria is used for selection. For example: /I=dos*,strupr inludes all public symbols beginning 'dos' or equal to 'strupr'. /E=s* /I=strupr excludes all public symbols beginning 's' except for 'strupr' and includes everything else. /EXCLUDE specifies a comma delimited list of case insensitive strings used as exclusion criteria for public symbols. An optional trailing * signifies a generic match. If both /INCLUDE and /EXCLUDE are specified then the logical OR of their criteria is used for selection. For example: /E=_*,dos* excludes all public symbols beginning '_' or 'dos'. /E=s* /I=strupr excludes all public symbols beginning 's' except for 'strupr' and includes everything else. /CASESENSITIVE switch applies to /INCLUDE and /EXCLUDE. If specified then the inculde and exclude strings will be match on a case-sensitve basis. /LOGSTACK=n specifies the number of bytes of stack to log for entry tracepoints. This causes the following TSF statements to be generated for each entry tracepoint: for 16-bit code - REGS=(SP,SS), FMT="Stack pointer SS:SP=%A->", MEM=(RSS+SP,D,n), FMT="%R%W" for 32-bit code - REGS=(ESP), FMT="Stack pointer ESP=%F->", MEM32=(FESP,D,n) FMT="%R%F" If /LOGSTACK is specified without a value then 16 bytes is assumed. /LOGRETURN specifies that for each return tracepoint, the return value in AX/EAX should be logged. This causes the following TSF statements to be generated: for 16-bit code: REGS=(AX) FMT="Returns (ax) %W" for 32-bit code: REGS=(EAX) FMT="Returns (eax) %F" /REGISTERS specifies one or more processor registers to be logged, each separated by a comma. The following register mnemonics are supported: AX,BX,CX,DX,CS,DS,ES,FS,GS,IP,SI,DI,SP,BP,FLAGS, EAX,EBX,ECX,EDX,EIP,ESI,EDI,ESP,EBP,EFLAGS /REGS may be used as a synonym for /REGISTERS. /RETEP specifies that for each public entry-point in the MAP file, a return tracepoint should be generated using the RETEP parameter of the TRACE statement in the TSF. Note: RETEP is only processed by TRCUST if the module has debugging information present. If this is not the case then TRCUST (2.20) will ignore the RETEP parameter and a warning message will be issued for the associated tracepoint. /TYPES pre-defined types: PUB = Public routines - names the begin upper case (ignoring leading underscores) PRIV = Private routines - names the begin lower case (ignoring leading underscores) PRE = Entry tracepoint. POST = Exit tracepoint. /GROUPS Requests that each of the strings listed be used to define a group. Tracepoints are assigned to a group according to whether a group name matches the beginning of the tracepoint name, ignoring case and leading underscore characters /TEMPLATE specifies a file where up to four template tracepoint definitions may be specified, one for each of the following categories: 16-bit entry points 16-bit return points 32-bit entry points 32-bit return points The definitions are in a shortened form of the TRCUST TRACE statement syntax. They are appended to each tracepoint of the category to which they apply. All parameters other than MINOR and DESC are permissible. TP and RETEP are specified as follows: TP=@16 signifies a 16-bit entry-point TP=@16,RETEP signifies a 16-bit return-point TP=@32 signifies a 32-bit entry-point TP=@32,RETEP signifies a 32-bit return-point Only TP and RETEP may appear on the same line as the TRACE keyword. For example: TRACE TP=@16 MEM=(SS:BP+8,I,0x10) FMT="16-bytes of parameter 1: %R%W" will append MEM=(SS:BP+8,I,0x10) FMT="16-bytes of parameter 1: %R%W" to every 16-bit entry tracepoint definition. MAKETSF 1.1 ----------- The purpose of MAKETSF is to extract dynamic trace definitions imbedded in C or ASM source file to which they relate. MAKETSF will also substitute line number information into those trace definions that are specified by line number and source file reference. For example: TRACE TP=@myprog.c,1234 This specifies a tracepoint at location corresponding to line 1234 in module whose source is "myprocg.c". The problem with this type of specification is that line number reference will need to be updated whenever the source is changed. MAKETSF allows the trace definitions to be imbedded in the source as comments but in extraction will generate the correct line number information. It does this be detecting the string "TP=@," or "TP=@ " and then inserting the line number specification. If the TP= keyword explicitly specifies an address expression then the trace definiton is extracted without modification. To use line number references modules must be compiled and linked with debugging information. For CSET2 the compile option is /TI, and the LINK386 option is /DE. Warning: Optimised code may not place tracepoints in the desired location. For example: in C: +-------------------------------------------+ |/***DT here is the header | | * MODNAME=my.exe | | * MAJOR=256 | | */ | | | | | | | |void myproc(char * parm1) { | |int result; | | | |. | |. | |. | | | |/***DT tracepoint definition | | * TRACE TP=@, | | * DESC="a tracepoint", | | * MEM32=(.parm1,I,4), | | * MEM32=(.resut,D,4), | | * FMT="parm1=%p%f result=%f" | | */ | | | | | | | +-------------------------------------------+ in ASM: +-------------------------------------------+ |;***DT here is the header | |; MODNAME=my.exe | |; MAJOR=256 | | | | | |parm1 DD ? | | | |myproc proc | | push ebp | | move ebp,esp | |. | |. | |. | | | |;***DT tracepoint definition | |; TRACE TP=@, | |; DESC="a tracepoint", | |; MEM32=(.parm1,D,4), | |; FMT="parm1=%p%f" | | | | | +-------------------------------------------+ Notes: The comment block must begin in column 1 with either ;***DT or /***DT. If the C form is used then an * must appear in column 2 of each line. A */ in column 2 ends the comment block. If the ASM form is used then a ; is required in every column. If TP=@ is coded then MAPTSF will insert the file name and line number corresponding to the trace definition. MAKETSF will respond to the $include <filename> directive if coded in column 1. This is intended for use where multiple source modules comprise a single load module. A list of component source files can be coded in a single file using include statements then given to MAKETSF for processing. For example: +-------------------------------------------+ |;A sample include file for MAKETSF | | | | | |$include myprog.c | |$include ..\asm\myproc.asm | |$include ..\sub\subr.c This is a comment | | | +-------------------------------------------+ MAKETSF will ignore any line that is not part of a ;***DT or /***DT comment block or a $include statement. TSF output form MAKETSF is written to the output file if specified, otherwise to STDOUT. Messages are written to STDERR. There are five switch options that MAKETSF supports: -v verbose mode - this gives information about number of files read and blocks processed. -n no includes - this forces MAKETSF to ignore $include directives. -p include source file path info - this forces MAKETSF to retain the full file specification from $include statements or the command line input file in the TP= keyword. The default is to strip path information. -a append output to output file. Default - replace output file -o<output> specifies the output file. The default is to direct output to STDOUT. The syntax for MAKTSF is: MAKETSF <options> input The DEBSTRIP utility may be use to remove debugging information after TRCUST has generated the TDF, alternatively re-link the load module without /DE. Removal of debugging information does not affect the validity of the TDF, however if the source is re-compiled then the TDF must be re-built. The syntax for DEBSTRIP is: DEBSTRIP <-o debinfo> module where <module> is the load module file to be stripped of debugging debugging information and <debinfo> is an optional output file that in which the stripped debugging information is placed. This file may be subsequently appended to the load module is TRCUST is to be re-used. SELRPN ------ Syntax: SELRPN <minor code list> Required parameters are the minor codes of interest. Each code is entered in decimal by default. An 'x' anywhere in a parameter means that parameter is hex. You may enter as many codes as you want. You may enter a range of codes by using smaller-larger syntax. The letter 'q' anywhere in the parameters will cause the first 8 minor codes which are not used to be written to STDERR Redirect STDIN and STDOUT to use files. SELTSF ------ Syntax: SELTSF <minor code list> Required parameters are the minor codes of interest. Each code is entered in decimal, or optionally in hex. An x anywhere in a parameter means that parameter is hex. You may enter as many codes as you want. You may enter a range of codes by using smaller-larger syntax. Redirect STDIN and STDOUT to use files. TRACEF ------ Syntax: TRACEF <selection criteria> TraceFilter 0.7 reads formatted trace data saved by TRACEFMT, and creates an output file which either includes or excludes events based on process ids, major event codes, and CASE-SENSITIVE strings. Each parameter is processed as follows: Special processing is done based on the first character. if '?', you get this help. if '=', the rest is a string which must be in the event. if '!', the rest is a string which must NOT be in the event. if '-' or '/', the parameter is NOT a filename. The first parameter not already explained is the input file name. The default input file is "TRACEFMT.SAV" . The second parameter not already explained is the output file name. The default is stdout, and is redirectable. Once the input and output files have been named, you no longer need '-' or '/'. You may (Include or EXclude) (processes and/or event codes), but using both Include and EXclude for either one is invalid. Parameter position 1 is the include/exclude flag. To include, use 'i'; to exclude, use either 'e' or 'x'. Parameter position 2 is the process/major code flag. For processes, use 'p'; for major event codes, use 'm'. Parameter position 3 is where the hex number begins. Examples: TRACEF -IPC /IPD -IPE >MYFILE Input file is 'TRACEFMT.SAV', output file is MYFILE (created); output contains only events from processes 12,13,14 (decimal). TRACEF tracefmt.sav myfile ipd ip0000e ipc same as above. TRACEF what.now -IPC /IPD -IPE MYFILE Input file is 'what.now', output file is MYFILE (created); TRACEF /xp2c -im10 Input is TRACEFMT.SAV, output is stdout, and includes only major event 16 (decimal) for all processes except 44 (decimal). TRACEF =Protection Output has only those events which contain the case-sensitive string "Protection". The program logic is first to find out if the event is excluded by PID, major code, or negative string. If excluded, no output. Next, if "include" is specified, and the reason for inclusion is not in this event, try the next event. Last, if no decision is yet made, output the event. Note: lines longer than 255 characters are not processed properly. Note: you may specify up to 16 PIDs, 16 Major codes, 16 positive and 16 negative strings. Experimentation with known data is recommended. Examples -------- In this example the tracepoint definition WinPostMsg is supplemented by having the caller's (caller to WinPostMsg) return address and stack address recorded. Notes: The recording of the caller's return address is often vital in trying to determine which module was responsible for calling a particular instance of an API. This address may be used with the kernel debugger, dump formatter or Theseus2 to determine which DLL issued an API. Or if the address is a private arena then PSTAT, with the PID recorded in the trace entry will readily reveal which process, hence executable, is calling a particular API. Recording the caller's stack address gives an indication of the level of recursion when an API was called. Step: 1) The first step is to make a temporary directory then split SYSTEM.TDF and SYSTEM.TFF: md temp cd temp syssplit c:\os2\system\trace.system.tdf syssplit c:\os2\system\trace.system.tff 2) WinPostMsg is a PMWIN API so we list PMWIN.TDF tdflst pmwin.tdf > pmwin.rpn 3) From the TDF listing we can see that the major code for PMWIN is 194 or 0xc2. (This information can also be obtained from the System Trace Reference in the OS/2 Debugging Handbook.) This tells us that the corresponding TFF is TRC00C2.TFF. This is listed to produce PMWIN.TSF: tfflst trc00c2.tff > pmwin.tsf 4) From PMWIN.TSF we can locate WinPostMsg pre-invocation. We see that the minor code is 706 or 0x2c2. The formatting definition appears as follows: /* start TP 0x02C2 */ TRACE MINOR=0x02C2, TP=@STATIC, DESC="WINPOSTMSG PRE-INVOCATION", FMT="hwndDest=%P%F, msg=%F, mp1=%F, mp2=%F " /* end TP 0x02C2 */ Searching for minor=0x02c3 in PMWIN.RPN we see that the tracepoint definition appears as: minor=0x02C2 object=0x00000004 offset=0x00007B60 opcode=0x55 push w,0x0010 push esp push d,0x00000004 add log mrf 5) Since WinPostMsg is a 32-bit API, and will therefore have been called as a Near 32-bit call, we will need to record the EIP from the first double word of the stack. The stack address can be recorded directly from the value in ESP. Thus the tracepoint definition in PMWIN.RPN will be modified to look like the following: minor=0x02C2 object=0x00000004 offset=0x00007B60 opcode=0x55 ; inserted instructions push d,4 ; 4 bytes to log push esp ; address of data to log log mrf ; log memory from flat address push esp ; save the stack address log dn,1 ; log 1 double word ; end of inserts push w,0x0010 push esp push d,0x00000004 add log mrf 6) The formatting template for WinPostMsg is modified for the new data: TRACE MINOR=0x02C2, TP=@STATIC, DESC="WINPOSTMSG PRE-INVOCATION", FMT="Return Address=%P%F, Stack Pointer=%F" FMT="hwndDest=%P%F, msg=%F, mp1=%F, mp2=%F " 7) Rebuild the TDF and copy to OS2\SYSTEM\TRACE dtrace buildtdf pmwin.rpn pmwin.tdf copy pmwin.tdf c:\os2\system\trace Note: PMWIN.TDF needs to be specified otherwise DTRACE will build a file called PMMERGE.TDF. This is because the tracepoints, along with PMGRE and PMSHAPI are actually applied to PMMERGE.DLL. 8) Rebuild the TFF and copy to OS2\SYSTEM\TRACE trcust pmwin.tsf copy trc00c2.tff c:\os2\system\trace 9) Activate tracing on WinPostMsg and format the trace buffer: trace on pmwin(706) trace /c tracefmt 10) The WinPostMsg trace points now appear as WINPOSTMSG PRE-INVOCATION EVENT#[0001] PID[00AA] MAJOR[C2] MINOR[02C2] LENGTH[001E] TIME: 11:55:55.44 Return Address=1BF96A41 , Stack Pointer=0007EF00 hwndDest=800001E5 , msg=00000020 , mp1=00001BBE , mp2=00000000 WINPOSTMSG PRE-INVOCATION EVENT#[0002] PID[0004] MAJOR[C2] MINOR[02C2] LENGTH[001E] TIME: 11:55:55.35 Return Address=1BECB470 , Stack Pointer=0003F574 hwndDest=8000000C , msg=00002F43 , mp1=00000001 , mp2=00000300 11) In OS/2 version 2.x WinPostMsg is a 16-bit API, its definition would have been modified as follows: TRACE MINOR=0x02C2, TP=@STATIC, DESC="WINPOSTMSG PRE-INVOCATION", FMT="Entry SP:%W SS:%W, Return IP:%P%W CS:%W" FMT="%PMP2 = %D, MP1 = %D, MSG = %W, HWND = %A " minor=0x02C2 major=0x00C2 object=0x00000001 offset=0x0000DE7E opcode=0x58 ;inserted instructions push ss ; save selector push esp ; and offset of stack log wn,2 ; log these as two words push w,4 ; prepare to log 4 bytes of data push ss ; save selector push esp ; and offset of address of data log mrs ; log the data (return cs:ip) ;end of inserted instructions push w,0x000E push ss push esp push w,0x0004 add log mrs --------------------------------------------------------------------- Observations and warnings: -------------------------- 1) Always save the original versions of SYSTEM.TFF and SYSTEM.TDF 2) Re-work any modifications after applying system maintenance since the location of the tracepoints will probably have changes and new SYSTEM.TFF and SYSTEM.TDF files will have been shipped with the maintenance. 3) TRACEFMT objects badly to a mismatched TFF. Be sure to rename SYSTEM.TFF and SYSTEM.TDF so as not to invoke old definitions. 4) Be selective with tracing. Tracing unnecessary events will wrap the trace buffer. Also some system tracepoints may not be correctly formatted - this tends to upset TRACEFMT as noted in 3). 5) OS/2 Version 4.0 ceases to ship SYSTEM.TDF and SYSTEM.TFF, since these have lead to maintenance problems. Instead their constituent TFF and TDF file will be shipped. 6) The TRACEFMT facility shipped with OS/2 version 4 is a totally revised facility with many new functions. Some of the observations and restrictions noted above have been eliminated. In particular, a TFF path may be explicitly specified, furthermore SYSTEM.TFF will be used as a last resort. Change History ------------- 1.0 2nd Sept 96 Submitted to OS2TOOLS 1.1 3rd Sept 96 Corrected function of SYSSPLIT when multipe TFF of the same major code have been concatenated into SYSTEM.TFF. Also added clarification on how TRACE processes OS2KRNL.TDF. 1.2 19th Sep 96 Fix PUSH ECS in TDFLST, and fix TDF generation in SYSSPLIT caused by new TFF processing introduced in 1.1 1.3 TDFLST: suppress null group/type specification TDFLST: suppress redundant major code overrides 1.4 fix push ecs error 1.5 13th Jan 97 Non-DLL name support + new Merlin rpn commands 1.6 29th Apr 97 SELRPN and SELTSF utilities added. 1.7 7th May 97 MAPTSF and TRACEF added. Latest TRCUST added. Information on latest TRACE and TRACEFMT added. 1.8 17th May 97 MAPTSF 1.3 added to package. /REGS, /INCLUDE, /EXCLUDE, /TEMPLATE switches added. Better parsing of map file added. Error messages directed to STDERR. SELRPN and SETST 0.8 - parameter scanning error fixed. 1.9 10th Oct 97 Added /CASESENSITIVE to MAPTSF and improved code segment recognition. 1.10 16th Jul 98 Shipped the latest tools at the Warp 3 FP 35 level++ 1.11 11th Aug 98 Update TRCUST, TDFLST and TFFLST. Add MAKETSF. Include updated TRACE.DOC for FP35. 1.12 22th Aug 98 Update MAPTSF, MAKETSF, TRCUST and TRACEFMT. Fixes: Return entry points not correctly generated by MAPTSF. MAKETSF supports additional switches. TRCUST supports /L parameter, /P switch and fixes two traps. TRCUST not allowing traceponints on TEST, NOT and NEG instrucitons. TRACEFMT Selection Filter logic incorrect with > or < comparisons. Time specification was not handled correctly. DTRACE: handling of BASEDEVs. Opcode validation added. Whitespace character handling added. TRACE: handling of BASEDEVs. 1.13 25th Sep 98 Release 1.12 to OS2TOOLS + Add: TRSTOP to enable TRSPOOL to be terminated from another command window or CMD file. 1.14 11th Nov 98 Release 1.14 to OS2TOOLS + Update TRCUST and TRACE.