home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Spezial
/
SPEZIAL2_97.zip
/
SPEZIAL2_97.iso
/
UPDATE
/
WARP4FXD
/
readme.dbg
< prev
next >
Wrap
Text File
|
1997-09-04
|
50KB
|
1,696 lines
< Using OS/2 Warp System Debugging Tools
July 18, 1997
OS/2 Fix Distribution
Personal System Products
Austin, Tx
(c) Copyright International Business Machines Corporation, 1997.
All rights Reserved.
July 18, 1997 - Warp Debug
July 18, 1997 - Warp Debug
CONTENTS
Overview ......................................................... 1
Dump Formatter ................................................... 1
Kernel Debugger .................................................. 2
System Trace Utilities ........................................... 2
TRACEGET ....................................................... 3
TRSPOOL ........................................................ 3
DTRACE ......................................................... 5
User Guide ..................................................... 5
DTRACE functions ............................................... 8
Format of the Trace Program File .............................. 11
RPN command syntax ............................................ 12
File header ..................................................... 13
Tracepoint header ............................................... 15
The Trace Program ............................................... 17
Trace Program Examples .......................................... 27
Contents ii
July 18, 1997 - Warp Debug
OVERVIEW
This README file contains information for the users of the system
debugging tools:
Ä Dump Formatter
Ä Kernel Debugger
Ä System Trace Utilities
DUMP FORMATTER
With WARP Server SMP and Warp 4.0, each FixPak installs the
corresponding version of the Dump Formatter and related symbol files
in
\OS2\SYSTEM\PMDF Warp Server SMP
\OS2\PDPSI\PMDF\WARP4 Warp 4.0
If multiple versions of the Dump Formatter are required then they must
be installed in directories outside the \OS2 directory tree since the
fix installation tool will replace all versions of DF_RET.EXE and
DF_DEB.EXE if finds in the \OS2 directory tree.
Thus, prior to installation of a FixPak the
\OS2\SYSTEM\PMDF Warp Server SMP
\OS2\PDPSI\PMDF\WARP4 Warp 4.0
directory should be copied if it is required for use after the FixPak
has been installed.
When multiple versions of the Dump Formatter are used the
\OS2\SYSTEM\PMDF\PMDFVERS.LST Warp Server SMP
\OS2\PDPSI\PMDF\WARP4\PMDFVERS.LST Warp 4.0
file should be updated to cross reference each system version with its
corresponding Dump Formatter directory location. The format of
PMDFVERS.LST entries are:
df-path;build-level;description
Dump Formatters and fuller sets of symbols file for various OS/2
versions may be obtained from:
Overview 1
July 18, 1997 - Warp Debug
ftp:\\service.boulder.ibm.com\ps\products\os2\fixes\debug
KERNEL DEBUGGER
If the debug kernel is installed when a FixPak is installed then it
will be replaced by the retail version of new version of the kernel,
together with any symbol files are that are installed by the FixPak.
If these files are required after installation of a FixPak then they
should be copied to a private directory not on the boot drive.
After installation of a FixPak the associated debug (ALLSTRICT and
HSTRICT) kernel and system symbol files may be obtained from:
ftp:\\service.boulder.ibm.com\ps\products\os2\fixes\debug
SYSTEM TRACE UTILITIES
Each FixPak installs version specific trace formatting (*.TFF) and
definition files (*.TDF) in the \OS2\SYSTEM\TRACE directory. If users
service multiple versions of OS2 they may need to copy the *.TFF files
to a private directory in order to allow a trace taken from another
system version to format correctly. The /T= parameter of TRACEFMT
will allow the user to specify the TFF path from the command line. The
TFF path may also be specified by selecting the File pull-down and Set
TFF path option of TRACEFMT.
In general TFFs are changed for a given release of OS2 except for
corrective purposes. The TDFs however are dependent on being precisely
matched to the module version to which they apply. TDFs are used by
the TRACE command to apply dynamic trace points. If the debug kernel
is installed then the associated OS2KRNL.TDF must be installed if
kernel tracing is required. The TDFs for the HSTRICT and ALLSTRICT
kernels are packaged with the dump formatter symbols as OS2KRNLB.TDF
and OS2KRNLD.TDF. These may be obtained from:
ftp:\\service.boulder.ibm.com\ps\products\os2\fixes\debug
Note: With OS/2 3.0 Fix Pack 29 and OS/2 4.0 GA the combined
SYSTEM.TDF and SYSTEM.TFFs were obsoleted. Individual TFFs and TDFs
are installed. However SYSTEM.TFF is sill supported by the TRACEFMT
command and may be used for earlier versions of OS/2.
Warp 3.0 FixPak 29 and Warp 4.0 GA introduce three new trace
utilities: TRACEGET, TRSPOOL and DTRACE. These are described below:
Overview 2
July 18, 1997 - Warp Debug
TRACEGET
The TACEGET command will extract the System Trace buffer and save it
in a file. The command syntax:
TRACEGET file
TRSPOOL
TRSPOOL extends the usefulness of the OS/2 system trace facility by
capturing the single system trace buffer and spooling it a cyclically
used sequence of disk files. The captured trace disk files may be
later formatted using TRACEFMT, by selecting the Open option of the
File menu.
TRSPOOL operates by polling the system trace buffer until halted by
pressing Ctrl-C.
The system trace buffer may be captured at regular intervals or by
"Adaptive polling".
Adaptive polling mode attempts to capture the system trace buffer when
the system trace buffer is a certain per-centage used. The polling
time is adjusted according to the actual usage of the last captured
buffer. The adaptive algorithm has a built in hysteresis to avoid the
affects of short bursts of intensive tracing or moments of inactivity.
Because there is no system notification of when the trace buffer
wraps, TRSPOOL may loose trace events under very erratic system
performance.
TRSPOOL will operate without parameter specification in adaptive
polling mode. However the following parameters may be specified:
Overview 3
July 18, 1997 - Warp Debug
/An Specifies the target per-centage trace buffer usage for adaptive
spooling.
Default: 30(%%). This is the default spooling method.
/Fn Specifies the number of spooled trace buffer files.
Default: 10.
/Tn Specifies fixed time trace buffer spooling, in mili-seconds,
or if specified with /A the initial sleep time.
Default: Adaptive spooling - /A option + initial sleep time
2000ms.
Note: when adaptive spooling is active, the sleep time interval
is limitated to a range between 50ms and 60000ms. Any time interval
may be specified with fixed time spooling.
/Q Specifies quiet operation - messages are suppressed.
Default: non-quiet mode.
/W Specifies write-through mode. Trace files are pre-allocated
and opened in write-through mode.
Default: normal file open mode.
/P Specifies trace files should be pre-allocated.
Default: files are not pre-allocated unless /W is specified.
/? Display help.
The generated trace buffer files have names: TRACEBUF.nnn, where nnn
ranges from 000 to the value specified by /Fn.
The /W option is provided for use where tracing precedes a system
outage and there is no orderly shutdown. This disadvantage of using
this option is that writing to the TRACEBUG.nnn files is made
synchronous, consequently the time take to spool the trace buffer will
be longer.
The /P option pre-allocates and initialises all TRACEBUF.nnn files to
nulls. This ensures that space is available on hard disk for the
requisite TRACEBUF.nnn files. In addition there is an improved chance
that data written to these files will be committed should a system
outage occur. The /P option is implied by /W.
Note: Neither of the /P or /W options is fail-safe. If a system outage
occurs after the trace buffer has been read, but before data has been
committed to disk then it will not be recorded. However, the segment
allocated by TRSPOOL for the local copy of the trace buffer is
reported at initialisation. This may also be located from a system
dump by searching for the eye-catcher "TRSPOOL RAS DATA" in the
TRSPOOL stack segment. The trace buffer selector follows the
eye-catcher. The file number of the last file written is also recorded
as a word following the trace buffer selector.
To use TRSPOOL, the system trace must first be enabled by specifying
TRACEBUF=63
Overview 4
July 18, 1997 - Warp Debug
in the CONFIG.SYS.
The system trace is activated by using the TRACE command or TRACE=
statement of CONFIG.SYS.
DTRACE
DTRACE exploits the DosDynamicTrace facility at a low-level. This may
be used to implement ad-hoc tracing in DLLs, Device Drivers, File
System Drivers and the OS2 Kernel. EXE files are also included.
Dynamic Trace may be used for diagnostic purposes and performance
monitoring.
Dynamic trace is a facility available within the OS/2 kernel.
Tracepoints are implemented by modifying dynamically code of modules
loaded in memory. This is in contrast to Static tracepoints which are
implemented when applications call the DosSysTrace API.
Dynamic tracepoints are implemented by replacing machine instructions
at specified points within a module by INT3 instructions. This is
done by the DosDynamicTrace API. When the INT3 instruction executes,
control is passed to the system TRAP3 exception handler, which in turn
passes control to Dynamic Trace if the TRAP3 was due to a known
tracepoint. Dynamic Trace interprets instructions, which are in
Reverse Polish Notation, that were passed to it when the trace point
was defined. These instructions allow data to be logged in the system
trace buffer and local variables associated with the tracepoint to be
manipulated. After the RPN instruction stream is complete, the
original instruction is single-stepped then normal execution resumed.
The overhead of dynamic trace is a few milliseconds per tracepoint.
Normally this is small enough not to make a noticeable difference to
system performance.
USER GUIDE
Command Syntax:
DTRACE APPLY trpgm_file [/h=hmte É /n=name] [/m=major] [/i=id] [/q] [/d]
DTRACE BUILDTDF trpgm_file [tdf_file] [/m=major] [/n=name] [/i=id] [/q]
[/d]
DTRACE REMOVE [trpgm_file É /h=hmte É /n=name] [/q] [/d]
DTRACE CLEARALL [/q] [/d]
DTRACE QUERY [/h=hmte É /n=name] [/i=id] [/q] [/d]
DTRACE GETVARS [/h=hmte É /n=name] [/i=id] [/v=n:m] [/z] [/r] [/q] [/d]
Numeric values may be specified in hexadecimal or decimal. Hexadecimal
values are signified with either the (C -style) 0x prefix, e.g. 0x2f8;
Overview 5
July 18, 1997 - Warp Debug
or the (assembler-style) h suffix, e.g. 2f8h
Optional command line parameters (/i, /m, /h and /n) set defaults
which override the default settings in the header of the trace program
file. Overrides for specific tracepoints take precedence over the
command line and the header in the trace program file.
Overview 6
July 18, 1997 - Warp Debug
hmte: module handle (any module with an MTE). May be specified also in
the trace program file.
name: module name.
name may specify a simple name, a name and extension or a
fully qualified name with path information.
If a fully qualified name is specified then it is used without
modification to determine the module handle. If this is unccessful
the no attempt is made to search for the module.
For partially specified names DTRACE attempts to work out the
module handle according to the following assumptions:
if a simple name without extension is specified then .DLL is
assumed. If the DLL is not loaded then LIBPATH is used to search
and load the DLL.
All other module types must specify at the very least
name and extension. If the module is not already loaded then
PATH is seached for determine the fully qualified module name
and hence the module handle.
The following types of module may be traced:
Physical Device Drivers
Virtual Device Drivers
File System Drivers
Printer Drivers
Queue Drivers
Custom DLLs (DLLs with non-DLL extension names)
EXE modules
Custom EXE modules (EXEs with a non_EXE extension or no extension)
Base device drivers.
Any of the above in non-PATH or LIBPATH directories.
For BASEDEVs the system records the path name as
being the root directory of the boot drive regardless of which
directory the driver was loaded from. DTRACE will attempt to
derive the module handle of a BASEDEV automatically if only
name and extension are supplied.
Build BUILDTDF may be used for non-DLL modules however under
OS/2 3.0+ JR09872 is required for the TRACE command to process
TDFs for non-DLL modules.
major: The default major code. May also be specified in the trace program
file. Major codes specified with specific tracepoints in the trace
program file override any other specification.
Overview 7
July 18, 1997 - Warp Debug
id: Superset grouping of tracepoints. May include more than one major
code. Defaults to 0 when defining tracepoints. NB dynamic trace
generated by TRCUST uses id=0, unless overridden by TDFID=. Id may
be specified also in the trace program file.
Id is intended for use with the QUERY and GETVARS functions.
These functions will assume all non-zero ids are to be processed if
id is not specified.
n:m Variables n to m. Dynamic Trace variables are referred to by index number
starting with 0. Number of variables defined is determined by the
vars= statement of the trace program file.
z: Zero variables.
r: Read variables.
q: Suppress copyright and incidental informational messages.
d: Debugging switch. This is provided for diagnosing problems with DTRACE.
It should only be used at the request of Service personnel.
Note: DTRACE also has associated DTRACE.TDF and TRC0063.TFF files which
permit inernal tracing of DTRACE itself by means of TRACE ON DTRACE.EXE
trpgm_file: Trace program file. If a simple name is specified then
an extension of .RPN is assumed.
See below. for the file description.
tdf_fiie: The generated Trace Definition File name. See below.
Options that may also be specified in the trace program file are
overridden when specified on the command line.
DTRACE FUNCTIONS
Overview 8
July 18, 1997 - Warp Debug
APPLY: Insert dynamic tracepoints, specified by the trace program
file for a module specified by name or hmte. A full
description of the trace program file is given below.
BUILDTDF: Build a Trace Definition File (TDF) from the definitions
supplied in the trace program file. The OS/2 TRACE command
may be used subsequently to apply or removed all or selected
tracepoints defined in the TDF.
TFD files must be stored in the current directory, DPATH or
in \OS2\SYSTEM\TRACE.
BUILDTDF permits group and type classifications to be
specified with each tracepoint. These may be used by the
OS/2 TRACE command to select subsets of tracepoints to be
activated. The TRACE command also permits specific minor
codes, or ranges of minor codes to be specified.
The syntax for the TRACE command using a TDF file is as
follows:
TRACE ONÉOFF tdf_file
or TRACE ON tdf_file(minor spec)
or TRACE ON tdf_file(group spec)
or TRACE ON tdf_file(type spec)
where:
tdf_file is the file name, excluding path and
extension of the tdf_file.
minor spec is a combination of minor code or
ranges of minor codes separated by commas.
In the following example KERNEL minor codes
(decimal) 1, 2 through 10 and 401 are traced.
TRACE ON KERNEL(1,2-10,401)
group spec is a combination of groups separated by
commas. Each group may further specify one or more
types.
In the following example KERNEL group FS (with
all types) and TK with types PRE and POST is traced.
TRACE ON KERNEL(FS,TK:PRE+POST)
type spec is a combination of types separated by
commas. In the following example all KERNEL PRE and
Overview 9
July 18, 1997 - Warp Debug
POST type tracepoints are traced.
TRACE ON KERNEL(PRE,POST)
Notes:
Due to a limitation with the TRACE command, BUILDTDF
can only be used to create TDFs for DLLs and OS2KRNL unless
JR09872 is installed.
If the TRACE command fails to find the TDF in the DPATH it
will look in \OS2\SYSTEM\TRACE\SYSTEM.TDF before looking
finally for \OS2\SYSTEM\TRACE\tdf_file. The becomes an
important consideration when one of the pre-existing system
trace definitions is modified or replaced.
The TRACE command fails to find OS2KRNL.TDF in
in OS2\SYSTEM\TRACE if executed from a command line where
the current directory is other than on the boot drive.
APAR PJ23293 addresses this problem.
See the accompanying TRCTOOLS documentation for further
information of modifying and replacing system trace
definitions.
REMOVE: Remove dynamic tracepoints for a module specified by name or
handle.
CLEARALL: Remove all dynamic tracepoints for all modules.
QUERY: Query by id or hmte all traced modules, their ids and number
of Dynamic Trace variables.
By default all non-zero ids are queried.
Note: Standard system dynamic trace definitions and user
definitions that are defined using TRCUST are always defined
with id=0.
GETVARS: Retrieve and/or set to zero the Dynamic Trace variables for
a given id or module.
By default all variables of all non-zero ids are retrieved.
Variables are displayed as a list in hexadecimal and decimal
formats.
Overview 10
July 18, 1997 - Warp Debug
FORMAT OF THE TRACE PROGRAM FILE
This file specifies one or more tracepoints for a module. Each
tracepoint may have an associated program that species to DynamicTrace
what variables to manipulate and what data to log in the system trace
buffer when the tracepoint fires.
Comments may appear after the instructions or on whole lines. They are
prefixed with a semi-colon.
Blanks are ignored by DTRACE.
The trace program consists of a header followed by one or more
tracepoint definitions. Each tracepoint definition has a header
followed by an optional program specified as a sequence of Reverse
Polish Notation instructions. The RPN commands use a circular stack
of 16 double-word elements as a work space. The top element of the
stack is the only immediately accessible element. As each element is
accessed the top of stack (TOS) pointer is moved to point to the
preceding stack element - this is referred to as a POP operation even
though the popped stack element is not actually removed from the
stack. Thus an RPN command that takes two stack parameters pops the
two topmost elements from the stack. Whenever data on the stack is
referenced it is done so in integral numbers of elements. Thus
pushing or popping a word will move the stack pointer as if a
double-word had been pushed or popped. Word and byte length data is
always padded to a double-word when pushed on to the stack.
The trace program may be used for three purposes (which may be
combined):
Overview 11
July 18, 1997 - Warp Debug
1) To cause one or more items of data to be logged in the system
trace buffer.
2) To update local variables which are associated with a particular
module being traced.
3) To detect a specific condition (value of a register, value in
memory or code path) and force a System Dump when that condition
occurs.
NB: this function is not available in all releases of OS/2.
The entire set of trace definitions and local variables for a
particular module is referred to as a Dynamic Trace Object (DTO).
One DTO may exist per module. DosDynamicTrace will not merge an
existing DTO with additional definitions for the same module.
DTOs for several modules may be grouped under the same id - see
the /i parameter above and the id= parameter below.
RPN COMMAND SYNTAX
RPN command syntax rules are as follows:
[label:] operator [operand1 [,operand2 [, ..... ]]] [; comment]
[;comment]
Where:
label
is an optional string of 1 - 255 characters, excluding ':',
initiated with a non-numeric character and delimited by a ':'.
A label must always precede a command, but the command my be
coded on the following line. Labels are for use by the jump
instructions as an alternative to coding an explicit numeric
value. Backward jumping is not permitted.
operator
is one of the valid RPN commands listed below.
operand1,...
are operands as defined by each RPN command.
A comment is initiated by a ';' and may follow on the same line as a
command or on a new line.
Overview 12
July 18, 1997 - Warp Debug
RPN commands,labels and operators are case insensitive.
Imbedded blanks are ignored.
Data logged by DTRACE may be formatted using TRACEFMT. The format will
be in hexadecimal bytes unless a custom trace format file has been
generated using the TRCUST utility. When using TRCUST, specify the TP
parameter as @STATIC. The prefixes %P and %R may be used. See the OS/2
Debugging Handbook (SBOF-8617).
Refer to the OS/2 Debugging Handbook, Volume 1 and 3 for further
information on the system trace utility.
FILE HEADER
Zero or more of the following may be specified, in any order:
Overview 13
July 18, 1997 - Warp Debug
vars= Number of Dynamic Trace variables to be defined
(initialised to zero).
major= Major code
hmte= Module handle
id= DTO grouping id - not to be confused with typedef or
groupdef ids. This is a gouping of Dynamic Trace Objects.
The default DTO id is 0. Id is used with GETVARS and QUERY
functions.
logmax= Maximum data to be logged in the trace buffer (default 512
bytes).
name= Module name. See name specification above.
typedef= Defines a type keyword. This is used only by the BUILDTDF
function. The definition is specified as:
typedef=keyword,id.
Keyword is a string, which is used by type statements, see
below.
id is a value equal to a power of two in the range 2**1 to
2**31.
Multple typedef statements my be specified.
groupdef= Defines a group keyword. This is used only by the BUILDTDF
function. The definition is specified as:
groupdef=keyword,id.
Keyword is a string, which is used by group statements, see
below.
id is a value in the rande 0x to 0xffffffff.
Multple groupdef statements my be specified.
Major code and hmte are required but may be specified or overridden by
the command line parameters.
If name and hmte are specified then the first parameter encountered
takes precedence.
id defaults to zero.
vars defaults to zero.
logmax defaults to 512.
The BUILDTDF function requires all definitions to be completely
specified within the trace program file. Furthermore name must be
Overview 14
July 18, 1997 - Warp Debug
specified rather than a module's hmte.
TRACEPOINT HEADER
The following must be specified, in any order, with the exception that
minor= must appear first.
Overview 15
July 18, 1997 - Warp Debug
minor= Tracepoint minor code
major= Tracepoint major code - this may be respecified for
each tracepoint and overrides the major code specified
in the file header. This applies to which the current
tracepoint.
opcode= Byte of opcode in module where the tracepoint will be
inserted.
object= Relative object of module where trace point will be
applied. Objects are numbered from 1.
offset= Offset within object where tracepoint will be applied.
major= The major code override for a specific tracepoint. The
default major code must be specified in the header to the
trace program file.
type= Type is an optional parameter that is used only by the
BUILDTDF function. Its purpose is to associate with each
tracepoint one or more types. These are used by the
OS/2 TRACE command as a means of selecting a subset of the
tracepoints defined in the generated TDF. The operand to the
type= statement is be specified as a sequence of one or more
keyword names defined by typedef statements, separated
'+' signs as follows:
type=[keyword1[+keyword2 ...]]
A typical use of the trace type is to associate a particular
tracepoint with a particular characteristic. For example,
tracepoints in DOSCALL1 and KERNEL use type=PRE for API
pre-invocation tracepoints and type=POST for
API post-invocation tracepoints.
Only one type statement is permissible per tracepoint.
group= Group is an optional parameter that is used only by the
BUILDTDF function. Its purpose is to associate related
subsets of the set of tracepoints defined in the generated
TDF. These are used by the OS/2 TRACE command as a means of
selecting a subset of the tracepoints defined in the
generated TDF. The operand to the group= statement is
specified as a single keyword name that has been defined by
the groupdef statements.
A typical use of the trace group is to associate all
tracepoints that relate to a particular component of the
system. For example, the group FS is used to associate all
tracepionts in DOSCALL1 and KERNEL that relate to the
Overview 16
July 18, 1997 - Warp Debug
file-system.
Group is intended to be an exclusive classification of
tracepoints compared with Type. Only one group may be
associated with a particular tracepoint, whereas a
tracepoint may have several type.
Only one group statement is permissible per tracepoint.
THE TRACE PROGRAM
Trace program may specify any meaningful combination of the following
RPN instructions. (TOS = Top of Stack).
Overview 17
July 18, 1997 - Warp Debug
Leng Mnem Operand(s) Description
-th -onic
Bytes
---------------------------------------------------------------------
1 Abort Abort - Log No Information
1 Add Add top 2 DWORD stack elements
1 Cnvrt DXS Convert Dword to Segmented
1 Cnvrt FXS Convert Flat to Segmented
1 Cnvrt SXD Convert Segmented to Dword
1 Cnvrt SXF Convert Segmented to Flat
3 Inc V,word Increment Immediate Variable
1 Inc VIi Increment indexed Variable
3 Jmp N,word Jump forward N bytes or to a label
3 Jmp NN,word Jump forward N bytes or to a label if TOS < 0
3 Jmp PN,word Jump forward N bytes or to a label if TOS > 0
3 Jmp ZN,word Jump forward N bytes or to a label if TOS = 0
1 Log ARF Log ASCIIZ at Flat Range
1 Log ARS Log ASCIIZ at Segmented Range
2 Log DN,byte Log N DWORDs
1 Log MRF Log Memory at Flat Range
1 Log MRS Log Memory at Segmented Range
2 Log WN,byte Log N WORDs
3 Move V,word Move top of stack to Immediate Var.
1 Move VIi Move top of stack to indexed Var.
1 Mul Multiply top 2 stack elements
3 Or V,word OR immed. indexed variable with TOS
2 Pop N,byte Rotate stack down (pop) N times
1 Push CS Push contents of (CS)
5 Push D,dword Push DWORD Immediate
1 Push DS Push contents of (DS)
1 Push EAX Push contents of (EAX)
1 Push EBP Push contents of (EBP)
1 Push EBX Push contents of (EBX)
1 Push ECX Push contents of (ECX)
1 Push EDI Push contents of (EDI)
1 Push EDX Push contents of (EDX)
1 Push EFlags Push contents of (EFlags)
1 Push EIP Push contents of (EIP)
1 Push ES Push contents of (ES)
1 Push ESI Push contents of (ESI)
1 Push ESP Push contents of (ESP)
1 Push FIF Push Flat Indirect Flat
1 Push FS Push contents of (FS)
1 Push GS Push contents of (GS)
5 Push OXF,dword Push (DWORD Object to Flat Address)
2 Push OXS,byte Push (Object to Selector)
1 Push SIS Push Segmented Indirect Segmented
1 Push SS Push contents of (SS)
3 Push V,word Push Immediate Variable
1 Push VIi Push indexed Variable
3 Push W,word Push WORD Immediate
Overview 18
July 18, 1997 - Warp Debug
1 Push WIS Push WORD Indirect Segmented
1 Remove Remove the current tracepoint
1 Sub Subtract top 2 stack elements
1 SysDump Force a system Dump (*)
1 And AND top 2 stack elements (*)
1 Or OR top 2 stack elements (*)
1 Xor XOR top 2 stack elements (*)
1 Neg 1's complement TOS (*)
1 Exit Log data and exit tracepoint (*)
3 SetMin W,word Override the tracepoint minor code with 'word' (**)
1 SetMin Override the tracepoint minor code from TOS (**)
3 SetMaj W,word Override the tracepoint major code with 'word' (**)
1 SetMaj Override the tracepoint major code from TOS (**)
1 Xchg Swap top two elements on the stack. (**)
* Each of the commands flagged with (*) require APAR PJ22196 applying
to the OS2KRNL (available with Warp 3.0 FixPak 29 and Warp 4.0 GA).
** Each of the commands flagged with (**) will be supported the GA
version of OS/2 Warp 4.0 and Warp 3.0 FixPak 29.
Each of these commands acts as follows:
Overview 19
July 18, 1997 - Warp Debug
PUSH: Push a value on to the RPN stack
In Push SS and Push ESP the value of SS and ESP is dependent on whether the
tracepoint occurred at ring 0 or not.
In Push EIP, the EIP on the stack is one too large, due to the
INT3.
Push W takes a word operand, zero extends it, and pushes
it on to the RPN stack.
Push OXS converts its byte operand into a selector,
zero extends that value, and pushes it on to the stack.
The byte operand is on object number of the module which
is currenlty being traced.
Because MTEs may eventually become nonresident, the selectors
(up to 256) are stored in an array by DynamicTrace when the tracepoints
were inserted. The word operand indexes this array to get the sel.
Push WIS pops an offset, then a selector, from the RPN stack,
fetches the user word at that 16:16 address, zero extends it,
and pushes that on to the RPN stack.
If the address is invalid or not present, a GP fault or Page
fault record will be logged in the buffer, and the interpreter
will exit.
Push SIS pops an offset, then a selector, from the RPN stack,
fetches the user dword at that 16:16 address and pushes that on to
the RPN stack in the segmented address format.* That is,
the high word (selector) is zero extended and pushed, and then
the low word (offset) is zero extended and pushed.
If the address is invalid or not present, a GP fault or Page
fault record will be logged in the buffer, and the interpreter
will exit.
Push OXF converts its dword operand into a flat address,
and pushes that on to the stack. See description of PUSH OXS for
more details.
Push FIF pops a Dword from the RPN stack, and then
pushes the dword at that flat address on to the stack.
Push V takes a word operand. Push V uses that to index
to the Dynamic Trace variable in the current DTO, and pushes the value
it finds there.
Push VIi fetches an index of a Dynamic Trace variable from
the top of the stack, (without doing a pop), and then
pushes the value of that variable on to the stack.
LOG: Log data in the system trace buffer.
Overview 20
July 18, 1997 - Warp Debug
Log WN takes a byte operand, and repeats the following operation
that many times:
Pop the value from the top of the RPN stack
Log the low word of that value, ignoring the high word.
If the log overflows, the interpreter will exit without continuing,
but will record as much as it can.
Log MRS pops the following from the RPN stack:
Offset
Selector
Length
Log MRS then zero extends all these values, and attempts to
move Length number of bytes from the given 16:16 address into
the log buffer.
The logged memory is prefixed by 3 bytes :
Token byte of 0,
Length word (length of logged information, in bytes)
If an address is invalid or not present, a GP fault or Page
fault record will be logged in the buffer, and the interpreter
will exit.
If the log overflows, the interpreter will exit without continuing,
and without logging the memory.
Log ARS pops the following from the RPN stack:
Offset
Selector
Length
Log ARS then zero extends all these values, and attempts to
move Length number of bytes from the given 16:16 address into
the log buffer. The data transfer will be discontinued if a
null byte is fetched. The null byte will not be logged.
The logged string is prefixed by 3 bytes :
Token byte of 1,
Length word (length of logged information, in bytes)
If an address is invalid or not present, a GP fault or Page
fault record will be logged in the buffer, and the interpreter
will exit.
If the log overflows, the interpreter will exit without continuing,
and without logging the string.
Log DN takes a byte operand, and repeats the following operation
that many times:
Overview 21
July 18, 1997 - Warp Debug
Pop the value from the top of the RPN stack
Log the value (as a DWORD)
If the log overflows, the interpreter will exit without continuing,
but will record as much as it can.
Log MRF pops the following from the RPN stack:
Flat Address
Length
Log MRF then zero extends the length, and attempts to move
Length number of bytes from the given flat address into
the log buffer.
The logged memory is prefixed by 3 bytes :
Token byte of 0,
Length word (length of logged information, in bytes)
If an address is not present, a Page fault record will be
logged in the buffer, and the interpreter will exit.
If the log overflows, the interpreter will exit without continuing,
and without logging the memory.
Log ARF pops the following from the RPN stack:
Flat Address
Length
Log ARF then zero extends the length, and attempts to move
Length number of bytes from the given flat address into
the log buffer. The data transfer will be discontinued if a
null byte is fetched. The null byte will not be logged.
The logged string is prefixed by 3 bytes :
Token byte of 1,
Length word (length of logged information, in bytes)
If an address is not present, a Page fault record will be
logged in the buffer, and the interpreter will exit.
If the log overflows, the interpreter will exit without continuing,
and without logging the string.
When memory references are invalid the token byte is set to one of
the following to indicate the type of error encountered:
-1 Invalid Selector
-2 Selector not Present
-3 Page not Present
Overview 22
July 18, 1997 - Warp Debug
The byte count is set to 4 and the data logged is the fault
address.
ADD/SUB/MUL/AND/OR/XOR: Add/Subtact/Multiply the top two stack
elements
Add pops two DWORDs from the RPN stack, and pushes their sum.
Sub pops two DWORDs from the RPN stack, and pushes their
difference. The first value popped is subtracted from the second.
Mul pops two DWORDs from the RPN stack, and pushes their
product.
And pops two DWORDs from the RPN stack, and pushes their
bit-wise AND.
Or pops two DWORDs from the RPN stack, and pushes their
bit-wise Or.
Xor pops two DWORDs from the RPN stack, and pushes their
bit-wise Xor.
NEG: 1's complement top of stack.
Neg 1's complements the TOS. No data is pushed or popped.
CNVRT: Convert an address
Cnvrt FXS pops a dword from the RPN stack, uses CRMA
to translate that flat pointer to a 16:16 segmented pointer.
It then pushes the selector (zero extended) and then the
offset (zero extended) on to the stack.
If the flat address does not lie within the compatibility
region, the interpreter will exit immediately.
Cnvrt SXF pops a selector, then an offset from the RPN stack,
uses CRMA to translate that 16:16 pointer to a flat address,
and pushes that flat address on to the stack.
If the segmented address does not lie within the comparability
region (GDT selector), the interpreter will exit immediately.
Cnvrt DXS pops a DWORD, then pushes the high word (zero
extended) and then the low word (zero extended). No CRMA is
applied.
Overview 23
July 18, 1997 - Warp Debug
Cnvrt SXD pops a low word, then a high word, then
concatenates them into a DWORD, and pushes the result.
POP: Pop a value from the RPN stack.
Pop N takes a byte operand, and pops that many operands
from the stack. As the values are not actually removed from
the 16-element circular stack, Pop N effectively rotates
the stack down.
MOVE: Move a value to a variable.
Move V takes a word operand. Move V then moves
the value on the top of the stack to the Dynamic Trace variable
in the current DTO at that index. The top of stack pointer
is not changed.
Move VIi pops a variable index off the top of the stack,
and then pops a value off the top of the stack. The value is moved
into the Dynamic Trace variable in the current DTO at that index.
The variable and the index are then pushed back on to the stack,
so that there is no net change on the stack at all.
If the index is too large, the interpreter will exit with an error.
INC: Increment a variable.
Inc V takes a word operand, and increments the value in the
Dynamic Trace variable in the current DTO at that index.
Inc VIi fetches an index of a Dynamic Trace variable from
the top of the stack, (without doing a pop), and then
increments the value of that variable.
If the index is too large, the interpreter will exit with an error.
JMP: Jump forward in the RPN program.
Jmp takes a word or label as operand. Jmp causes an
unconditional jump forward in the instruction stream by
that number of bytes, relative to the first byte of the next
instruction.
Therefore, Jmp by 0 bytes is a NOP (i.e jmp n,0)
Jmp ZN takes a word or label as operand. Jmp ZN causes an
unconditional jump forward in the instruction stream by
Overview 24
July 18, 1997 - Warp Debug
that number of bytes, relative to the end of the instruction,
but only if the value on the top of the stack is zero.
Jmp NN takes a word or label operand. JmpNN causes an
unconditional jump forward in the instruction stream by
that number of bytes, relative to the end of the instruction,
but only if the value on the top of the stack is negative.
Jmp PN takes a word or label operand. Jmp PN causes an
unconditional jump forward in the instruction stream by
that number of bytes, relative to the end of the instruction,
but only if the value on the top of the stack is positive.
To prevent loops, no backward jumps are permitted. Also, it is
illegal to jump into the code stream for another tracepoint.
If labels are specified, DTRACE calculates the relative forward
offset.
REMOVE: Remove and Abort the current tracepoint.
ABORT: Abort the tracepoint.
Abort aborts the tracepoint entirely. The interpreter
exits, but does not log any information. The data logged
by this tracepoint is lost.
However, alterations to the variables remain.
By using Abort in combination with the Jmp
instructions, unnecessary tracepoints can be filtered
at run time, without crowding or overflowing the log buffer.
EXIT: Exit the tracepoint.
Exit terminates the tracepoint. The interpreter
exits, and logs any information requested so far. The tracepoint
remains in tact.
By using Exit in combination with the Jmp
instructions, specific conditions can be detected before logging
additional data.
If Exit is not available (systems without PJ22196) then the
equivalent may be achieved by coding:
jmp n,exit
.
.
.
.
Overview 25
July 18, 1997 - Warp Debug
exit: jmp n,0 ;nop
ORV: OR a Dynamic Trace variable with TOS.
SYSDUMP: Force a System Dump.
SysDump transfers control to the stand alone dump process. No
data is logged. No system shutdown is performed and normal
system execution is terminated immediately.
Use this command with the Jmp instructions to detect illusive error
conditions that require dump analysis at the point of error.
SETMAJ: Override the tracepoint major code
SetMaj takes the word value from the TSO to override the tracepoint
major code. The override remains in effect until the current RPN
program exits. Since data is not logged to the system trace buffer
until the RPN program exits, the major code may be overridden at any
point and remain effective for the whole trace entry.
SetMaj may be specified with the W,word operand form. In this case
'word' forms the major code override.
Note: The system trace facility currently admits only major codes
from 0 - 255. Any specification of a major code greater than 255
will be treated as if the high-order byte value is zero.
This is provided to allow trace formatting templates to be
selected dynamically according to the data logged.
SETMIN: Override the tracepoint minor code
SetMin takes the word value from the TSO to override the tracepoint
minor code. The override remains in effect until the current RPN
program exits. Since data is not logged to the system trace buffer
until the RPN program exits, the minor code may be overridden at
any point and remain effective for the whole trace entry.
SetMin may be specified with the W,word operand form. In this case
'word' forms the minor code override.
The system trace facility admit minor codes in the range from
0x0000 to 0xffff.
This is provided to allow trace formatting templates to be
selected dynamically according to the data logged.
XCHG: Exchange the top two entries on the RPN Stack.
Overview 26
July 18, 1997 - Warp Debug
Xchg pops the top two stack elements then pushes them back on to
the stack in the reverse order.
TRACE PROGRAM EXAMPLES
The following examples illustrate common usages of the RPN commands.
Overview 27
July 18, 1997 - Warp Debug
1) Log AX and BX registers:
Push EBX
Push EAX
Log WN,2 ;lower 16 bits of each DWORD
2) Log EIP, EBP and EAX:
Push EAX
Push EBP
Push EIP
Log DN,3 ;3 DWORDs from the stack
3) Log value at EBP+ESI:
Push W,4 ; push immediate value 4 - length to log
Push EBP
Push ESI
Add ; add top two DWORDs - puts EBP+ESI on stack
Log MRF ; log memory at flat address range
4) Log value at SS:SP using 16-bit segmented addressing:
Push W,9 ; push immediate value 9 - length to log
Push SS
Push ESP
Log MRS ; log memory at segmented address range
5) Log 16 bytes of data pointed to by the flat address at SS:SP+8
Push W,16 ; push immediate value 16 - length to log
Push SS
Push ESP
Push 8 ; offset 8
Add ; 8 added to ESP value on stack
Push SIS ; pop ESP then SS and pop Dword at that address
; as two Words extended to Dwords (as if it was a sel:offset).
; stack now contains the length and split address of data to log
Cnvrt SXD ; Concatenate the two words to form a flat address
Log MRF ; log the data.
Overview 28