home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 17 Fixes30
/
17-Fixes30.zip
/
xr_w039.dbg
< prev
next >
Wrap
Text File
|
1998-12-05
|
22KB
|
785 lines
< Using OS/2 Warp System Debugging Tools
July 14, 1998
NCSD Fix Distribution
Personal System Products
Austin, Tx
(c) Copyright International Business Machines Corporation, 1997, 1998.
All rights Reserved.
July 14, 1998 - Warp Debug
July 14, 1998 - Warp Debug
CONTENTS
1.0 Preface . . . . . . . . . . . . . . . . . . . . . . . . . 1
2.0 Install Notes . . . . . . . . . . . . . . . . . . . . . . 2
2.0.1 Dump Formatter . . . . . . . . . . . . . . . . . . . . 2
2.0.2 Kernel Debugger . . . . . . . . . . . . . . . . . . . 3
2.0.3 System Trace Utilities . . . . . . . . . . . . . . . . 4
3.0 Trace Facilities . . . . . . . . . . . . . . . . . . . . . 6
3.0.1 System Trace (SYSTRACE) Facility . . . . . . . . . . . 6
3.0.2 Software Trace (STRACE) Facility . . . . . . . . . . . 6
3.0.3 CONFIG.SYS Additions . . . . . . . . . . . . . . . . . 6
3.0.4 Command Line Interfaces . . . . . . . . . . . . . . . 7
4.0 System Dump Facility . . . . . . . . . . . . . . . . . . . 9
4.0.1 RASKDATA CONFIG.SYS statement . . . . . . . . . . . . 9
4.0.2 TRAPDUMP CONFIG.SYS statement . . . . . . . . . . . . 9
4.0.3 Examples of TRAPDUMP . . . . . . . . . . . . . . . . 11
5.0 Process Dump Facility . . . . . . . . . . . . . . . . . . 12
5.0.1 Enhancements Overview . . . . . . . . . . . . . . . . 12
Contents ii
July 14, 1998 - Warp Debug
1.0 PREFACE
This file provides information about the debugging tools that is
more current than the last published documentation. However, this
file only provides information about the facilities and their
components if they have modified.
This file is broken into sections based on the various facilities.
The sections are:
1. Install Notes - This section contains important information
about the install of the FixPak.
2. Trace facilities - This section contains information and both
the System (SysTrace) and Software (STRACE) trace facilities.
3. System Dump facility - This section contains information about
system dumps that are requested through programming or keyboard
interfaces.
4. Process Dump facility - This section contains information about
process dumps that are requested through programming interfaces,
keyboard interfaces, command line interfaces, and when a trap
occurs.
Preface 1
July 14, 1998 - Warp Debug
2.0 INSTALL NOTES
2.0.1 DUMP FORMATTER
With WARP, each FixPak installs the corresponding version of the
Dump Formatter and related symbol files in
\OS2\SYSTEM\PMDF Warp Server SMP
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
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
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 symbol files for various OS/2 versions may be
obtained from:
ftp://service.boulder.ibm.com
in the
/ps/products/os2/fixes/debug directory.
Files beginning with the last 4 characters of the Fixpak name are
the ones you need to download. For example, once connected you
would do a:
dir w035*.*
Install Notes 2
July 14, 1998 - Warp Debug
to see what debug images are available for Fixpak XR_W035.
W035S*.* are for SMP systems, W035U*.* are for UNI systems.
■ SMP means you are running Warp Server SMP
■ UNI means you are running any of the other Warp 3.x family
2.0.2 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 symbol files may be obtained from:
ftp://service.boulder.ibm.com
in the
/ps/products/os2/fixes/debug directory.
Files beginning with the last 4 characters of the Fixpak name are
the ones you need to download. For example, once connected you
would do a:
dir w035*.*
to see what debug images are available for Fixpak XR_W035.
W035S*.* are for SMP systems, W035U*.* are for UNI systems.
■ SMP means you are running Warp Server SMP
■ UNI means you are running any of the other Warp 3.x family
Install Notes 3
July 14, 1998 - Warp Debug
2.0.3 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.
See TRACE.DOC in the OS2\SYSTEM\RAS directory for more information
on TRACEFMT parameters.
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
in the
/ps/products/os2/fixes/debug directory.
Files beginning with the last 4 characters of the Fixpak name are
the ones you need to download. For example, once connected you
would do a:
dir w035*.*
to see what debug images are available for Fixpak XR_W035.
W035S*.* are for SMP systems, W035U*.* are for UNI systems.
■ SMP means you are running Warp Server SMP
■ UNI means you are running any of the other Warp 3.x family
Note: With OS/2 3.0 Fix Pack 29 the combined SYSTEM.TDF and
SYSTEM.TFFs were eliminated. Individual TFFs and TDFs are
installed. However SYSTEM.TFF is still supported by the TRACEFMT
command and may be used for earlier versions of OS/2.
Warp 3.0 FixPak 29 introduced three new trace utilities: TRACEGET,
TRSPOOL and DTRACE.
Install Notes 4
July 14, 1998 - Warp Debug
These are described in the TRACE.DOC, TRSPOOL.DOC and DTRACE.DOC
files, which can be found in the OS2\SYSTEM\RAS directory.
Install Notes 5
July 14, 1998 - Warp Debug
3.0 TRACE FACILITIES
There are 2 trace facilities in OS/2. They are System trace
(SysTrace), used for execution tracing, and software trace
(STRACE), used for performance tracing.
3.0.1 SYSTEM TRACE (SYSTRACE) FACILITY
The System Trace facility has been enhanced to:
■ Select process to be traced by process short name
■ Enablement of Dynamic Tracing at interrupt time
■ Allow Dynamic Trace to handle forwarded DLLs.
■ The 256 major code limit has been removed for Dynamic
tracepoints. Static tracepoints will retain the restriction to
maintain compatibility with the rest of the system.
■ The buffer can be grown dynamically (and without requiring a
reboot) up to 512 KB (formerly 64KB). This is controlled by the
user from both config.sys and the command line.
The buffer will continue to be a wrapping buffer but the user now
has the option to have logging to the buffer stopped when the
buffer is full.
Information about the enhancements can be found in the TRACE.DOC
file in the OS2\SYSTEM\RAS directory.
3.0.2 SOFTWARE TRACE (STRACE) FACILITY
The Software Trace (STRACE) facility has been enhanced to remove
the dependency on the System Trace facility. This is done by
providing a config.sys statement that allows the buffer to be
defined and tracepoints to be enabled.
Note: The STRACE facility no longer uses the TRACE ON/OFF command
to enable tracepoints as documented in the STRACE documentation.
3.0.3 CONFIG.SYS ADDITIONS
A new config.sys statement (STRACE) has been created to allow the
user to control the Software Trace facility. This statement allows
the buffer to be allocated and tracepoints to be enabled. The
following commands are supported:
Trace Facilities 6
July 14, 1998 - Warp Debug
■ STRACE=INIT x
■ STRACE=ON
■ STRACE=ENABLE n1 n2 n3 ...
■ STRACE=DISABLE n1 n2 n3 ...
■ STRACE=INSERT
■ STRACE=REMOVE
The syntax for these commands is similar to the corresponding
command line version which was documented in previous STRACE
documentation. Some examples of these commands are:
■ Initialize an 8 MB buffer:
STRACE=INIT 8
■ Enable static tracepoints 5, 7, and 9
STRACE=ENABLE 5 7 9
■ Start tracing
STRACE=ON
■ Disable static tracepoints 5 and 9
STRACE=DISABLE 5 9
■ Insert and Enable dynamic tracepoint 19
STRACE=INSERT 19
■ Disable and Remove dynamic tracepoint 19
STRACE=REMOVE
3.0.4 COMMAND LINE INTERFACES
The STRACE command has been extended to allow tracepoints to be
enabled/disabled. The following commands are supported in addition
to all of the existing commands.
■ STRACE ENABLE n1 n2 n3...
Trace Facilities 7
July 14, 1998 - Warp Debug
■ STRACE DISABLE n1 n2 n3 ...
Some examples are:
■ Enable tracepoints 1, 4, and 100 STRACE ENABLE 1 4 100
■ Disable tracepoints 1 and 100 STRACE DISABLE 1 100
Trace Facilities 8
July 14, 1998 - Warp Debug
4.0 SYSTEM DUMP FACILITY
The System (Standalone) dump facility has been enhanced to provide
more flexibility to the user. Enhancements include:
■ Allow the user to specify that information about "swapped out"
processes should remain resident so that they are collected when
a dump is taken. This is done by placing a new statement
(RASKDATA) in the config.sys file and rebooting the system.
■ Allow the user to specify that a Process Dump should be used
instead of a system dump when the system dump keyboard interface
is used. This is specified in the TRAPDUMP config.sys
statement.
4.0.1 RASKDATA CONFIG.SYS STATEMENT
The "RASKDATA" statement will contain parameters that identify
internal structures that should remain resident (not swappable).
The only parameter currently defined for this statement is "OTE".
An equal sign (=) will be accepted as a separator between the
statement RASKDATA) and its parameters. Currently there is only
one parameter:
■ OTE
The System Loader should use the Resident Heap for Object
Table Entries (OTEs) associated with Swappable Module Table
Entries (SMTEs) and information required to provide the
pathname information for the process.
Note: This option should only be used when anticipating that a
system dump is inevitable because of the larger footprint caused by
keeping these records resident.
4.0.2 TRAPDUMP CONFIG.SYS STATEMENT
The "TRAPDUMP" statement will allow the user to specify that a
Process Dump should be attempted if the System Dump hotkey sequence
is used. The format of the command is:
TRAPDUMP=[OFF,Drive: | ON,Drive: | R0,Drive:] [,PD]
System Dump Facility 9
July 14, 1998 - Warp Debug
■ OFF,Drive
This allows the user to define the location where the system
dump will be placed while not enabling the automatic dumping
of the trapping process. A dump can be initiated through the
keyboard interface.
■ ON,Drive
This allows the user to define the location where the system
dump will be placed and state that any process that has an
unhandled trap should initiate a dump. A dump can also be
initiated through the keyboard interface.
■ R0,Drive
This allows the user to define the location where the system
dump will be placed and state that any system process (Ring
0) that has an unhandled trap should initiate a dump. A dump
can also be initiated through the keyboard interface.
■ PD
This specifies that a Process Dump should be attempted if
the user initiates a system dump through the keyboard
interface. The system will be rebooted when the dump is
completed.
This will cause the Process Dump facility to attempt to take a
process dump using the system context (defined by PDUMPSYS
command). If that can not be done then a system dump will be
taken.
The user can override this behavior by using the keyboard interface
twice instead of once.
Note: The process dump will be placed at the location being used by
the Process Dump facility (specified by the DUMPPROCESS statement
in config.sys or from the PROCDUMP /L option on the command line).
System Dump Facility 10
July 14, 1998 - Warp Debug
4.0.3 EXAMPLES OF TRAPDUMP
The following statement would set the system dumps to be placed on
the F: drive. However, no dump will be taken unless initiated
through the keyboard interface.
TRAPDUMP=OFF,F:
The following statement would set the system dumps to be placed on
the F: drive and state that a Process Dump should be attempted
instead of a system dump. However, no dump will be taken unless
initiated through the keyboard interface.
TRAPDUMP=OFF,F:,PD
The following statement does not enable the System dump facility
but it does say to attempt a Process Dump if the keyboard interface
is used. If the process dump can not be taken a system dump will be
initiated which will go to diskettes (default).
TRAPDUMP=PD
The following statement would set the system dumps to be placed on
the F: drive and state that a Process Dump should be attempted
instead of a system dump when the keyboard interface is used. Any
other unhandled trap would cause a system dump to be initiated.
TRAPDUMP=ON,F:,PD
The following statement would set the system dumps to be placed on
the F: drive and state that a Process Dump should be attempted
instead of a system dump when the keyboard interface is used. Any
system process (Ring 0) that has an unhandled trap would cause a
system dump to be initiated.
TRAPDUMP=R0,F:,PD
System Dump Facility 11
July 14, 1998 - Warp Debug
5.0 PROCESS DUMP FACILITY
The process dump facility allows the user to specify what data will
be captured for a process that traps or at any time (user request).
In most instances, the rest of the processes running in the system
will be unaffected which make this facility more appealing than the
alternative (system dump that requires a reboot of the system).
While a process dump has been an alternative for the last few
releases it has been ineffective due to the fixed data that was
captured. By allowing the user to specify what will be captured we
are providing a much more robust facility.
5.0.1 ENHANCEMENTS OVERVIEW
The enhancements include:
■ Ability to Dump a process, multiple processes, all processes, or
memory ranges with the user selecting what will be dumped by
type of records. See the PDUMPSYS statement in the command line
section of the document for the types of data that can be
dumped.
A Device Driver can be used to do special processing that is not
possible using the defined commands. This device driver is
written by the user using the rules that are defined later in
this file.
■ A command to specify the defaults used for System Level/Ring 0
(PDUMPSYS) and User Level/Ring 3 (PDUMPUSR) dumps. These
defaults will be assigned to the processes as they are started
unless specific data had been identified (PROCDUMP statement)
for that process.
■ A command to allow the user to identify what data should be
dumped by specific process(es).
■ Provide the ability to initiate a process dump through a
keyboard hot-key interface. This will be controlled with a
config.sys statement (TRAPDUMP statement described with the
System Dump enhancements section of README.DBG).
Information about the Process Dump enhancements can be found in
the PROCDUMP.DOC file on the OS2\SYSTEM\RAS directory.
Process Dump Facility 12