home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 17 Fixes30 / 17-Fixes30.zip / xr_w039.dbg < prev    next >
Text File  |  1998-12-05  |  22KB  |  785 lines
  1. <        Using OS/2 Warp System Debugging Tools
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.         
  18.  
  19.         
  20.         
  21.  
  22.  
  23.  
  24.         July 14, 1998
  25.  
  26.         
  27.         
  28.         
  29.         
  30.         NCSD Fix Distribution
  31.         Personal System Products
  32.         Austin, Tx
  33.         
  34.         
  35.         
  36.         
  37.         
  38.         (c) Copyright International Business Machines Corporation, 1997, 1998.
  39.         All rights Reserved.
  40.  
  41.         July 14, 1998 - Warp Debug
  42.  
  43.  
  44.  
  45.                             July 14, 1998 - Warp Debug
  46.  
  47.         CONTENTS
  48.  
  49.  
  50.           1.0 Preface   . . . . . . . . . . . . . . . . . . . . . . . . . 1
  51.  
  52.           2.0 Install Notes   . . . . . . . . . . . . . . . . . . . . . . 2
  53.             2.0.1 Dump Formatter  . . . . . . . . . . . . . . . . . . . . 2
  54.             2.0.2 Kernel Debugger   . . . . . . . . . . . . . . . . . . . 3
  55.             2.0.3 System Trace Utilities  . . . . . . . . . . . . . . . . 4
  56.  
  57.           3.0 Trace Facilities  . . . . . . . . . . . . . . . . . . . . . 6
  58.             3.0.1 System Trace (SYSTRACE) Facility  . . . . . . . . . . . 6
  59.             3.0.2 Software Trace (STRACE) Facility  . . . . . . . . . . . 6
  60.             3.0.3 CONFIG.SYS Additions  . . . . . . . . . . . . . . . . . 6
  61.             3.0.4 Command Line Interfaces   . . . . . . . . . . . . . . . 7
  62.  
  63.           4.0 System Dump Facility  . . . . . . . . . . . . . . . . . . . 9
  64.             4.0.1 RASKDATA CONFIG.SYS statement   . . . . . . . . . . . . 9
  65.             4.0.2 TRAPDUMP CONFIG.SYS statement   . . . . . . . . . . . . 9
  66.             4.0.3 Examples of TRAPDUMP   . . . . . . . . . . . . . . . . 11
  67.  
  68.           5.0 Process Dump Facility  . . . . . . . . . . . . . . . . . . 12
  69.             5.0.1 Enhancements Overview  . . . . . . . . . . . . . . . . 12
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.         
  100.                                                                Contents  ii
  101.  
  102.                             July 14, 1998 - Warp Debug
  103.  
  104.         1.0 PREFACE
  105.  
  106.         This file provides information about the debugging tools that is
  107.         more current than the last published documentation.  However, this
  108.         file only provides information about the facilities and their
  109.         components if they have modified.
  110.  
  111.         This file is broken into sections based on the various facilities.
  112.         The sections are:
  113.  
  114.         1. Install Notes - This section contains important information
  115.            about the install of the FixPak.
  116.  
  117.         2. Trace facilities - This section contains information and both
  118.            the System (SysTrace) and Software (STRACE) trace facilities.
  119.  
  120.         3. System Dump facility - This section contains information about
  121.            system dumps that are requested through programming or keyboard
  122.            interfaces.
  123.  
  124.         4. Process Dump facility - This section contains information about
  125.            process dumps that are requested through programming interfaces,
  126.            keyboard interfaces, command line interfaces, and when a trap
  127.            occurs.
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.         
  157.                                                                  Preface  1
  158.  
  159.                             July 14, 1998 - Warp Debug
  160.  
  161.         2.0 INSTALL NOTES
  162.  
  163.  
  164.  
  165.         2.0.1 DUMP FORMATTER
  166.  
  167.         With WARP, each FixPak installs the corresponding version of the
  168.         Dump Formatter and related symbol files in
  169.  
  170.            \OS2\SYSTEM\PMDF                        Warp Server SMP
  171.  
  172.  
  173.         If multiple versions of the Dump Formatter are required then they
  174.         must be installed in directories outside the \OS2 directory tree
  175.         since the fix installation tool will replace all versions of
  176.         DF_RET.EXE and DF_DEB.EXE if finds in the \OS2 directory tree.
  177.  
  178.         Thus, prior to installation of a FixPak the
  179.  
  180.            \OS2\SYSTEM\PMDF                        Warp Server SMP
  181.  
  182.  
  183.         directory should be copied if it is required for use after the
  184.         FixPak has been installed.
  185.  
  186.         When multiple versions of the Dump Formatter are used the
  187.  
  188.            \OS2\SYSTEM\PMDF\PMDFVERS.LST           Warp Server SMP
  189.  
  190.  
  191.         file should be updated to cross reference each system version with
  192.         its corresponding Dump Formatter directory location. The format of
  193.         PMDFVERS.LST entries are:
  194.  
  195.            df-path;build-level;description
  196.  
  197.  
  198.         Dump Formatters and symbol files for various OS/2 versions may be
  199.         obtained from:
  200.  
  201.            ftp://service.boulder.ibm.com
  202.                  in the
  203.            /ps/products/os2/fixes/debug directory.
  204.  
  205.  
  206.         Files beginning with the last 4 characters of the Fixpak name are
  207.         the ones you need to download. For example, once connected you
  208.         would do a:
  209.  
  210.            dir w035*.*
  211.  
  212.  
  213.         
  214.                                                            Install Notes  2
  215.  
  216.                             July 14, 1998 - Warp Debug
  217.  
  218.          to see what debug images are available for Fixpak XR_W035.
  219.  
  220.            W035S*.* are for SMP systems, W035U*.* are for UNI systems.
  221.  
  222.  
  223.         ■  SMP means you are running Warp Server SMP
  224.         ■  UNI means you are running any of the other Warp 3.x family
  225.  
  226.  
  227.  
  228.  
  229.         2.0.2 KERNEL DEBUGGER
  230.  
  231.         If the debug kernel is installed when a FixPak is installed then it
  232.         will be replaced by the retail version of new version of the
  233.         kernel, together with any symbol files are that are installed by
  234.         the FixPak.  If these files are required after installation of a
  235.         FixPak then they should be copied to a private directory not on the
  236.         boot drive.
  237.  
  238.         After installation of a FixPak the associated debug (ALLSTRICT and
  239.         HSTRICT) kernel and symbol files may be obtained from:
  240.  
  241.            ftp://service.boulder.ibm.com
  242.                  in the
  243.            /ps/products/os2/fixes/debug directory.
  244.  
  245.  
  246.         Files beginning with the last 4 characters of the Fixpak name are
  247.         the ones you need to download.  For example, once connected you
  248.         would do a:
  249.  
  250.            dir w035*.*
  251.  
  252.  
  253.         to see what debug images are available for Fixpak XR_W035.
  254.  
  255.            W035S*.* are for SMP systems, W035U*.* are for UNI systems.
  256.  
  257.  
  258.         ■  SMP means you are running Warp Server SMP
  259.         ■  UNI means you are running any of the other Warp 3.x family
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.         
  271.                                                            Install Notes  3
  272.  
  273.                             July 14, 1998 - Warp Debug
  274.  
  275.         2.0.3 SYSTEM TRACE UTILITIES
  276.  
  277.         Each FixPak installs version specific trace formatting (*.TFF) and
  278.         definition files (*.TDF) in the \OS2\SYSTEM\TRACE directory.  If
  279.         users service multiple versions of OS2 they may need to copy the
  280.         *.TFF files to a private directory in order to allow a trace taken
  281.         from another system version to format correctly.  The /T= parameter
  282.         of TRACEFMT will allow the user to specify the TFF path from the
  283.         command line.  The TFF path may also be specified by selecting the
  284.         File pull-down and Set TFF path option of TRACEFMT.
  285.  
  286.         See TRACE.DOC in the OS2\SYSTEM\RAS directory for more information
  287.         on TRACEFMT parameters.
  288.  
  289.         In general TFFs are changed for a given release of OS2 except for
  290.         corrective purposes.  The TDFs however are dependent on being
  291.         precisely matched to the module version to which they apply.  TDFs
  292.         are used by the TRACE command to apply dynamic trace points.  If
  293.         the debug kernel is installed then the associated OS2KRNL.TDF must
  294.         be installed if kernel tracing is required.  The TDFs for the
  295.         HSTRICT and ALLSTRICT kernels are packaged with the dump formatter
  296.         symbols as OS2KRNLB.TDF and OS2KRNLD.TDF.  These may be obtained
  297.         from:
  298.  
  299.            ftp://service.boulder.ibm.com
  300.                  in the
  301.            /ps/products/os2/fixes/debug directory.
  302.  
  303.  
  304.         Files beginning with the last 4 characters of the Fixpak name are
  305.         the ones you need to download. For example, once connected you
  306.         would do a:
  307.  
  308.            dir w035*.*
  309.  
  310.  
  311.         to see what debug images are available for Fixpak XR_W035.
  312.  
  313.            W035S*.* are for SMP systems, W035U*.* are for UNI systems.
  314.  
  315.  
  316.         ■  SMP means you are running Warp Server SMP
  317.         ■  UNI means you are running any of the other Warp 3.x family
  318.  
  319.         Note: With OS/2 3.0 Fix Pack 29 the combined SYSTEM.TDF and
  320.         SYSTEM.TFFs were eliminated.  Individual TFFs and TDFs are
  321.         installed.  However SYSTEM.TFF is still supported by the TRACEFMT
  322.         command and may be used for earlier versions of OS/2.
  323.  
  324.         Warp 3.0 FixPak 29 introduced three new trace utilities:  TRACEGET,
  325.         TRSPOOL and DTRACE.
  326.  
  327.         
  328.                                                            Install Notes  4
  329.  
  330.                             July 14, 1998 - Warp Debug
  331.  
  332.         These are described in the TRACE.DOC, TRSPOOL.DOC and DTRACE.DOC
  333.         files, which can be found in the OS2\SYSTEM\RAS directory.
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.         
  385.                                                            Install Notes  5
  386.  
  387.                             July 14, 1998 - Warp Debug
  388.  
  389.         3.0 TRACE FACILITIES
  390.  
  391.         There are 2 trace facilities in OS/2.  They are System trace
  392.         (SysTrace), used for execution tracing, and software trace
  393.         (STRACE), used for performance tracing.
  394.  
  395.  
  396.  
  397.         3.0.1 SYSTEM TRACE (SYSTRACE) FACILITY
  398.  
  399.         The System Trace facility has been enhanced to:
  400.  
  401.         ■  Select process to be traced by process short name
  402.         ■  Enablement of Dynamic Tracing at interrupt time
  403.         ■  Allow Dynamic Trace to handle forwarded DLLs.
  404.         ■  The 256 major code limit has been removed for Dynamic
  405.            tracepoints.  Static tracepoints will retain the restriction to
  406.            maintain compatibility with the rest of the system.
  407.         ■  The buffer can be grown dynamically (and without requiring a
  408.            reboot) up to 512 KB (formerly 64KB).  This is controlled by the
  409.            user from both config.sys and the command line.
  410.  
  411.         The buffer will continue to be a wrapping buffer but the user now
  412.         has the option to have logging to the buffer stopped when the
  413.         buffer is full.
  414.  
  415.         Information about the enhancements can be found in the TRACE.DOC
  416.         file in the OS2\SYSTEM\RAS directory.
  417.  
  418.  
  419.  
  420.         3.0.2 SOFTWARE TRACE (STRACE) FACILITY
  421.  
  422.         The Software Trace (STRACE) facility has been enhanced to remove
  423.         the dependency on the System Trace facility.  This is done by
  424.         providing a config.sys statement that allows the buffer to be
  425.         defined and tracepoints to be enabled.
  426.  
  427.         Note: The STRACE facility no longer uses the TRACE ON/OFF command
  428.         to enable tracepoints as documented in the STRACE documentation.
  429.  
  430.  
  431.  
  432.  
  433.         3.0.3 CONFIG.SYS ADDITIONS
  434.  
  435.         A new config.sys statement (STRACE) has been created to allow the
  436.         user to control the Software Trace facility.  This statement allows
  437.         the buffer to be allocated and tracepoints to be enabled.  The
  438.         following commands are supported:
  439.  
  440.  
  441.         
  442.                                                         Trace Facilities  6
  443.  
  444.                             July 14, 1998 - Warp Debug
  445.  
  446.         ■  STRACE=INIT x
  447.         ■  STRACE=ON
  448.         ■  STRACE=ENABLE n1 n2 n3 ...
  449.         ■  STRACE=DISABLE n1 n2 n3 ...
  450.         ■  STRACE=INSERT
  451.         ■  STRACE=REMOVE
  452.  
  453.         The syntax for these commands is similar to the corresponding
  454.         command line version which was documented in previous STRACE
  455.         documentation. Some examples of these commands are:
  456.  
  457.         ■  Initialize an 8 MB buffer:
  458.  
  459.                STRACE=INIT 8
  460.  
  461.  
  462.         ■  Enable static tracepoints 5, 7, and 9
  463.  
  464.                STRACE=ENABLE 5 7 9
  465.  
  466.  
  467.         ■  Start tracing
  468.  
  469.                STRACE=ON
  470.  
  471.  
  472.         ■  Disable static tracepoints 5 and 9
  473.  
  474.                STRACE=DISABLE 5 9
  475.  
  476.  
  477.         ■  Insert and Enable dynamic tracepoint 19
  478.  
  479.                STRACE=INSERT 19
  480.  
  481.  
  482.         ■  Disable and Remove dynamic tracepoint 19
  483.  
  484.                STRACE=REMOVE
  485.  
  486.  
  487.  
  488.  
  489.  
  490.         3.0.4 COMMAND LINE INTERFACES
  491.  
  492.         The STRACE command has been extended to allow tracepoints to be
  493.         enabled/disabled.  The following commands are supported in addition
  494.         to all of the existing commands.
  495.  
  496.         ■  STRACE ENABLE n1 n2 n3...
  497.  
  498.         
  499.                                                         Trace Facilities  7
  500.  
  501.                             July 14, 1998 - Warp Debug
  502.  
  503.         ■  STRACE DISABLE n1 n2 n3 ...
  504.  
  505.         Some examples are:
  506.  
  507.         ■  Enable tracepoints 1, 4, and 100 STRACE ENABLE 1 4 100
  508.         ■  Disable tracepoints 1 and 100 STRACE DISABLE 1 100
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.         
  556.                                                         Trace Facilities  8
  557.  
  558.                             July 14, 1998 - Warp Debug
  559.  
  560.         4.0 SYSTEM DUMP FACILITY
  561.  
  562.         The System (Standalone) dump facility has been enhanced to provide
  563.         more flexibility to the user. Enhancements include:
  564.  
  565.         ■  Allow the user to specify that information about "swapped out"
  566.            processes should remain resident so that they are collected when
  567.            a dump is taken.  This is done by placing a new statement
  568.            (RASKDATA) in the config.sys file and rebooting the system.
  569.  
  570.         ■  Allow the user to specify that a Process Dump should be used
  571.            instead of a system dump when the system dump keyboard interface
  572.            is used.  This is specified in the TRAPDUMP config.sys
  573.            statement.
  574.  
  575.  
  576.  
  577.  
  578.         4.0.1 RASKDATA CONFIG.SYS STATEMENT
  579.  
  580.         The "RASKDATA" statement will contain parameters that identify
  581.         internal structures that should remain resident (not swappable).
  582.         The only parameter currently defined for this statement is "OTE".
  583.         An equal sign (=) will be accepted as a separator between the
  584.         statement RASKDATA) and its parameters.  Currently there is only
  585.         one parameter:
  586.  
  587.         ■  OTE
  588.  
  589.                The System Loader should use the Resident Heap for Object
  590.                Table Entries (OTEs) associated with Swappable Module Table
  591.                Entries (SMTEs) and information required to provide the
  592.                pathname information for the process.
  593.  
  594.  
  595.         Note: This option should only be used when anticipating that a
  596.         system dump is inevitable because of the larger footprint caused by
  597.         keeping these records resident.
  598.  
  599.  
  600.  
  601.  
  602.         4.0.2 TRAPDUMP CONFIG.SYS STATEMENT
  603.  
  604.         The "TRAPDUMP" statement will allow the user to specify that a
  605.         Process Dump should be attempted if the System Dump hotkey sequence
  606.         is used.  The format of the command is:
  607.  
  608.             TRAPDUMP=[OFF,Drive: | ON,Drive: | R0,Drive:] [,PD]
  609.  
  610.  
  611.  
  612.         
  613.                                                     System Dump Facility  9
  614.  
  615.                             July 14, 1998 - Warp Debug
  616.  
  617.         ■  OFF,Drive
  618.  
  619.  
  620.                This allows the user to define the location where the system
  621.                dump will be placed while not enabling the automatic dumping
  622.                of the trapping process. A dump can be initiated through the
  623.                keyboard interface.
  624.  
  625.  
  626.         ■  ON,Drive
  627.  
  628.                This allows the user to define the location where the system
  629.                dump will be placed and state that any process that has an
  630.                unhandled trap should initiate a dump. A dump can also be
  631.                initiated through the keyboard interface.
  632.  
  633.  
  634.         ■  R0,Drive
  635.  
  636.                This allows the user to define the location where the system
  637.                dump will be placed and state that any system process (Ring
  638.                0) that has an unhandled trap should initiate a dump. A dump
  639.                can also be initiated through the keyboard interface.
  640.  
  641.  
  642.         ■  PD
  643.  
  644.                This specifies that a Process Dump should be attempted if
  645.                the user initiates a system dump through the keyboard
  646.                interface. The system will be rebooted when the dump is
  647.                completed.
  648.  
  649.  
  650.         This will cause the Process Dump facility to attempt to take a
  651.         process dump using the system context (defined by PDUMPSYS
  652.         command).  If that can not be done then a system dump will be
  653.         taken.
  654.  
  655.         The user can override this behavior by using the keyboard interface
  656.         twice instead of once.
  657.  
  658.         Note: The process dump will be placed at the location being used by
  659.         the Process Dump facility (specified by the DUMPPROCESS statement
  660.         in config.sys or from the PROCDUMP /L option on the command line).
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.         
  670.                                                    System Dump Facility  10
  671.  
  672.                             July 14, 1998 - Warp Debug
  673.  
  674.         4.0.3 EXAMPLES OF TRAPDUMP
  675.  
  676.         The following statement would set the system dumps to be placed on
  677.         the F:  drive.  However, no dump will be taken unless initiated
  678.         through the keyboard interface.
  679.  
  680.             TRAPDUMP=OFF,F:
  681.  
  682.  
  683.         The following statement would set the system dumps to be placed on
  684.         the F:  drive and state that a Process Dump should be attempted
  685.         instead of a system dump.  However, no dump will be taken unless
  686.         initiated through the keyboard interface.
  687.  
  688.             TRAPDUMP=OFF,F:,PD
  689.  
  690.  
  691.         The following statement does not enable the System dump facility
  692.         but it does say to attempt a Process Dump if the keyboard interface
  693.         is used. If the process dump can not be taken a system dump will be
  694.         initiated which will go to diskettes (default).
  695.  
  696.             TRAPDUMP=PD
  697.  
  698.  
  699.         The following statement would set the system dumps to be placed on
  700.         the F: drive and state that a Process Dump should be attempted
  701.         instead of a system dump when the keyboard interface is used. Any
  702.         other unhandled trap would cause a system dump to be initiated.
  703.  
  704.             TRAPDUMP=ON,F:,PD
  705.  
  706.  
  707.         The following statement would set the system dumps to be placed on
  708.         the F: drive and state that a Process Dump should be attempted
  709.         instead of a system dump when the keyboard interface is used. Any
  710.         system process (Ring 0) that has an unhandled trap would cause a
  711.         system dump to be initiated.
  712.  
  713.             TRAPDUMP=R0,F:,PD
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.         
  727.                                                    System Dump Facility  11
  728.  
  729.                             July 14, 1998 - Warp Debug
  730.  
  731.         5.0 PROCESS DUMP FACILITY
  732.  
  733.         The process dump facility allows the user to specify what data will
  734.         be captured for a process that traps or at any time (user request).
  735.         In most instances, the rest of the processes running in the system
  736.         will be unaffected which make this facility more appealing than the
  737.         alternative (system dump that requires a reboot of the system).
  738.  
  739.         While a process dump has been an alternative for the last few
  740.         releases it has been ineffective due to the fixed data that was
  741.         captured. By allowing the user to specify what will be captured we
  742.         are providing a much more robust facility.
  743.  
  744.  
  745.  
  746.         5.0.1 ENHANCEMENTS OVERVIEW
  747.  
  748.         The enhancements include:
  749.  
  750.         ■  Ability to Dump a process, multiple processes, all processes, or
  751.            memory ranges with the user selecting what will be dumped by
  752.            type of records.  See the PDUMPSYS statement in the command line
  753.            section of the document for the types of data that can be
  754.            dumped.
  755.  
  756.            A Device Driver can be used to do special processing that is not
  757.            possible using the defined commands.  This device driver is
  758.            written by the user using the rules that are defined later in
  759.            this file.
  760.  
  761.         ■  A command to specify the defaults used for System Level/Ring 0
  762.            (PDUMPSYS) and User Level/Ring 3 (PDUMPUSR) dumps.  These
  763.            defaults will be assigned to the processes as they are started
  764.            unless specific data had been identified (PROCDUMP statement)
  765.            for that process.
  766.  
  767.         ■  A command to allow the user to identify what data should be
  768.            dumped by specific process(es).
  769.  
  770.         ■  Provide the ability to initiate a process dump through a
  771.            keyboard hot-key interface.  This will be controlled with a
  772.            config.sys statement (TRAPDUMP statement described with the
  773.            System Dump enhancements section of README.DBG).
  774.  
  775.            Information about the Process Dump enhancements can be found in
  776.            the PROCDUMP.DOC file on the OS2\SYSTEM\RAS directory.
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.         
  784.                                                   Process Dump Facility  12
  785.