<        Using OS/2 Warp System Debugging Tools















        

        
        



        March 2, 1999

        
        
        
        
        NCSD Fix Distribution
        Personal System Products
        Austin, Tx
        
        
        
        
        
        (c) Copyright International Business Machines Corporation, 1997, 1998.
        All rights Reserved.

        March 2, 1999 - Warp Debug



                            March 2, 1999 - 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  . . . . . . . . . . . . . . . . . 7
            3.0.4 Command Line Interfaces   . . . . . . . . . . . . . . . 8

          4.0 System Dump Facility  . . . . . . . . . . . . . . . . . . . 9
            4.0.1 RASKDATA CONFIG.SYS statement   . . . . . . . . . . . . 9
            4.0.2 TRAPDUMP CONFIG.SYS statement  . . . . . . . . . . . . 10
            4.0.3 Examples of TRAPDUMP   . . . . . . . . . . . . . . . . 11

          5.0 Process Dump Facility  . . . . . . . . . . . . . . . . . . 13
            5.0.1 Enhancements Overview  . . . . . . . . . . . . . . . . 13





























        
                                                               Contents  ii


                            March 2, 1999 - 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 been 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 for 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


                            March 2, 1999 - Warp Debug

        2.0 INSTALL NOTES



        2.0.1 DUMP FORMATTER

        With WARP 3, each FixPak installs the corresponding version of the
        Dump Formatter and related symbol files in

           \OS2\SYSTEM\PMDF                        Warp Server SMP


        With WARP 4, each FixPak installs the corresponding version of the
        Dump Formatter and related symbol files in

           \OS2\PDPSI\PMDF                         Warp 4


        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 Warp 3 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.



        
                                                           Install Notes  2


                            March 2, 1999 - Warp Debug

        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

        Similarly, for Warp 4 fix pack 10:

           dir M010*.*


        will list the corresponding debugging files.



        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 Warp 3 Fixpak XR_W035.



        
                                                           Install Notes  3


                            March 2, 1999 - Warp Debug

           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

        Similarly, for Warp 4 fix pack 10:

           dir M010*.*


        will list the corresponding debugging files.



        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*.*




        
                                                           Install Notes  4


                            March 2, 1999 - Warp Debug

        to see what debug images are available for Warp 3, 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 and Warp 4.0 GA, 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, and Warp 4 GA, introduced three new trace
        utilities:  TRACEGET, TRSPOOL and DTRACE.  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


                            March 2, 1999 - 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 defined dynamically (and without requiring a
           reboot) to at least 5Mb (formerly 64KB), (the upper limit
           depends on availability of resident memory below 16Mb).  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.










        
                                                        Trace Facilities  6


                            March 2, 1999 - Warp Debug

        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:

        þ  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






        
                                                        Trace Facilities  7


                            March 2, 1999 - Warp Debug

        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...
        þ  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


                            March 2, 1999 - 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) for
        debugging purposes.  The syntax of the RASKDATA statement is as
        follows:


           RASKDATA=<option><,option><,.....>




        The valdi options available are:

        þ  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.


        þ  LOCKS

               The System Memory Manager should record long- and short-term
               memory locks for use by the Kernel Debugger and Dump Formatter
               .MK command. This is the default behaviour for debug (ALLSTRICT and
               HSTRICT) kernels. The option is available with Warp 3 Fix Pack 41 and
               Warp 4 Fix Pack 10.


        þ  NOLOCKS

        
                                                    System Dump Facility  9


                            March 2, 1999 - Warp Debug

               The System Memory Manager should not record long- and short-term
               memory locks. This is the default behaviour for the RETAIL kernel.
               The option is available with Warp 3 Fix Pack 41 and Warp 4 Fix Pack 10.


        Note: These options will have an effect on the demand for resident
        memory and should only be used when anticipating the need for a
        system dump.




        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]


        þ  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





        
                                                   System Dump Facility  10


                            March 2, 1999 - Warp Debug

               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).




        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.


        
                                                   System Dump Facility  11


                            March 2, 1999 - Warp Debug

            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  12


                            March 2, 1999 - 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  13

