home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 28 Fixes4x / 28-Fixes4x.zip / xr_m008.dbg < prev    next >
Text File  |  1998-09-04  |  59KB  |  1,754 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 15, 1998
  25.  
  26.         
  27.         
  28.         
  29.         
  30.         OS/2 Fix Distribution
  31.         Personal System Products
  32.         Austin, Tx
  33.         
  34.         
  35.         
  36.         
  37.         
  38.         (c) Copyright International Business Machines Corporation, 1997.
  39.         All rights Reserved.
  40.  
  41.         July 15, 1998 - Warp Debug
  42.  
  43.  
  44.  
  45.                             July 15, 1998 - Warp Debug
  46.  
  47.         CONTENTS
  48.  
  49.  
  50.           1.0 Overview  . . . . . . . . . . . . . . . . . . . . . . . . . 1
  51.           1.1 Dump Formatter  . . . . . . . . . . . . . . . . . . . . . . 1
  52.           1.2 Kernel Debugger   . . . . . . . . . . . . . . . . . . . . . 2
  53.           1.3 System Trace Utilities  . . . . . . . . . . . . . . . . . . 3
  54.             1.3.1 TRACEGET  . . . . . . . . . . . . . . . . . . . . . . . 4
  55.             1.3.2 TRSPOOL   . . . . . . . . . . . . . . . . . . . . . . . 4
  56.             1.3.3 DTRACE  . . . . . . . . . . . . . . . . . . . . . . . . 6
  57.             1.3.4 User Guide  . . . . . . . . . . . . . . . . . . . . . . 6
  58.             1.3.5 DTRACE functions  . . . . . . . . . . . . . . . . . . . 9
  59.             1.3.6 Format of the Trace Program File   . . . . . . . . . . 12
  60.             1.3.7 RPN command syntax   . . . . . . . . . . . . . . . . . 13
  61.           1.4 File header  . . . . . . . . . . . . . . . . . . . . . . . 14
  62.           1.5 Tracepoint header  . . . . . . . . . . . . . . . . . . . . 16
  63.           1.6 The Trace Program  . . . . . . . . . . . . . . . . . . . . 18
  64.           1.7 Trace Program Examples   . . . . . . . . . . . . . . . . . 28
  65.  
  66.  
  67.  
  68.  
  69.  
  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 15, 1998 - Warp Debug
  103.  
  104.         1.0 OVERVIEW
  105.  
  106.         This README file contains information for the users of the system
  107.         debugging tools:
  108.  
  109.         ■  Dump Formatter
  110.         ■  Kernel Debugger
  111.         ■  System Trace Utilities
  112.  
  113.  
  114.  
  115.         1.1 DUMP FORMATTER
  116.  
  117.         With WARP Server SMP and Warp 4.0, each FixPak installs the
  118.         corresponding version of the Dump Formatter and related symbol
  119.         files in
  120.  
  121.         \OS2\SYSTEM\PMDF                        Warp Server SMP
  122.         \OS2\PDPSI\PMDF\WARP4                   Warp 4.0
  123.  
  124.  
  125.         If multiple versions of the Dump Formatter are required then they
  126.         must be installed in directories outside the \OS2 directory tree
  127.         since the fix installation tool will replace all versions of
  128.         DF_RET.EXE and DF_DEB.EXE if finds in the \OS2 directory tree.
  129.  
  130.         Thus, prior to installation of a FixPak the
  131.  
  132.         \OS2\SYSTEM\PMDF                        Warp Server SMP
  133.         \OS2\PDPSI\PMDF\WARP4                   Warp 4.0
  134.  
  135.  
  136.         directory should be copied if it is required for use after the
  137.         FixPak has been installed.
  138.  
  139.         When multiple versions of the Dump Formatter are used the
  140.  
  141.         \OS2\SYSTEM\PMDF\PMDFVERS.LST           Warp Server SMP
  142.         \OS2\PDPSI\PMDF\WARP4\PMDFVERS.LST      Warp 4.0
  143.  
  144.  
  145.         file should be updated to cross reference each system version with
  146.         its corresponding Dump Formatter directory location. The format of
  147.         PMDFVERS.LST entries are:
  148.  
  149.         df-path;build-level;description
  150.  
  151.  
  152.         Dump Formatters and fuller sets of symbols file for various OS/2
  153.         versions may be obtained from:
  154.  
  155.  
  156.         
  157.                                                                 Overview  1
  158.  
  159.                             July 15, 1998 - Warp Debug
  160.  
  161.            ftp://service.boulder.ibm.com
  162.                  in the
  163.            /ps/products/os2/fixes/debug directory.
  164.  
  165.  
  166.         Files begining with the last 4 characters of the Fixpak name are
  167.         the ones you need to download. For example, once connected you
  168.         would do a:
  169.  
  170.            dir w034*.*
  171.  
  172.  
  173.          to see what debug images are available for Fixpak XR_W034.
  174.         W034S*.* are for SMP systems, W034U*.* are for UNI systems.
  175.  
  176.         ■  SMP means you are running Warp Server SMP
  177.         ■  UNI means you are running any of the other Warp 3.x family
  178.  
  179.  
  180.  
  181.         1.2 KERNEL DEBUGGER
  182.  
  183.         If the debug kernel is installed when a FixPak is installed then it
  184.         will be replaced by the retail version of new version of the
  185.         kernel, together with any symbol files are that are installed by
  186.         the FixPak.  If these files are required after installation of a
  187.         FixPak then they should be copied to a private directory not on the
  188.         boot drive.
  189.  
  190.         After installation of a FixPak the associated debug (ALLSTRICT and
  191.         HSTRICT) kernel and system symbol files may be obtained from:
  192.  
  193.            ftp://service.boulder.ibm.com
  194.                  in the
  195.            /ps/products/os2/fixes/debug directory.
  196.  
  197.  
  198.         Files begining with the last 4 characters of the Fixpak name are
  199.         the ones you need to download. For example, once connected you
  200.         would do a:
  201.  
  202.            dir w034*.*
  203.  
  204.  
  205.          to see what debug images are available for Fixpak XR_W034.
  206.         W034S*.* are for SMP systems, W034U*.* are for UNI systems.
  207.  
  208.         ■  SMP means you are running Warp Server SMP
  209.         ■  UNI means you are running any of the other Warp 3.x family
  210.  
  211.  
  212.  
  213.         
  214.                                                                 Overview  2
  215.  
  216.                             July 15, 1998 - Warp Debug
  217.  
  218.         1.3 SYSTEM TRACE UTILITIES
  219.  
  220.         Each FixPak installs version specific trace formatting (*.TFF) and
  221.         definition files (*.TDF) in the \OS2\SYSTEM\TRACE directory.  If
  222.         users service multiple versions of OS2 they may need to copy the
  223.         *.TFF files to a private directory in order to allow a trace taken
  224.         from another system version to format correctly.  The /T= parameter
  225.         of TRACEFMT will allow the user to specify the TFF path from the
  226.         command line. The TFF path may also be specified by selecting the
  227.         File pull-down and Set TFF path option of TRACEFMT.
  228.  
  229.         In general TFFs are changed for a given release of OS2 except for
  230.         corrective purposes. The TDFs however are dependent on being
  231.         precisely matched to the module version to which they apply. TDFs
  232.         are used by the TRACE command to apply dynamic trace points. If the
  233.         debug kernel is installed then the associated OS2KRNL.TDF must be
  234.         installed if kernel tracing is required.  The TDFs for the HSTRICT
  235.         and ALLSTRICT kernels are packaged with the dump formatter symbols
  236.         as OS2KRNLB.TDF and OS2KRNLD.TDF. These may be obtained from:
  237.  
  238.            ftp://service.boulder.ibm.com
  239.                  in the
  240.            /ps/products/os2/fixes/debug directory.
  241.  
  242.  
  243.         Files begining with the last 4 characters of the Fixpak name are
  244.         the ones you need to download. For example, once connected you
  245.         would do a:
  246.  
  247.            dir w034*.*
  248.  
  249.  
  250.          to see what debug images are available for Fixpak XR_W034.
  251.         W034S*.* are for SMP systems, W034U*.* are for UNI systems.
  252.  
  253.         ■  SMP means you are running Warp Server SMP
  254.         ■  UNI means you are running any of the other Warp 3.x family
  255.  
  256.         Note: With OS/2 3.0 Fix Pack 29 and OS/2 4.0 GA the combined
  257.         SYSTEM.TDF and SYSTEM.TFFs were obsoleted.  Individual TFFs and
  258.         TDFs are installed.  However SYSTEM.TFF is sill supported by the
  259.         TRACEFMT command and may be used for earlier versions of OS/2.
  260.  
  261.         Warp 3.0 FixPak 29 and Warp 4.0 GA introduce three new trace
  262.         utilities: TRACEGET, TRSPOOL and DTRACE. These are described below:
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.         
  271.                                                                 Overview  3
  272.  
  273.                             July 15, 1998 - Warp Debug
  274.  
  275.         1.3.1 TRACEGET
  276.  
  277.         The TACEGET command will extract the System Trace buffer and save
  278.         it in a file. The command syntax:
  279.  
  280.                TRACEGET file
  281.  
  282.  
  283.  
  284.  
  285.         1.3.2 TRSPOOL
  286.  
  287.         TRSPOOL extends the usefulness of the OS/2 system trace facility by
  288.         capturing the single system trace buffer and spooling it a
  289.         cyclically used sequence of disk files.  The captured trace disk
  290.         files may be later formatted using TRACEFMT, by selecting the Open
  291.         option of the File menu.
  292.  
  293.         TRSPOOL operates by polling the system trace buffer until halted by
  294.         pressing Ctrl-C.
  295.  
  296.         The system trace buffer may be captured at regular intervals or by
  297.         "Adaptive polling".
  298.  
  299.         Adaptive polling mode attempts to capture the system trace buffer
  300.         when the system trace buffer is a certain per-centage used.  The
  301.         polling time is adjusted according to the actual usage of the last
  302.         captured buffer.  The adaptive algorithm has a built in hysteresis
  303.         to avoid the affects of short bursts of intensive tracing or
  304.         moments of inactivity.  Because there is no system notification of
  305.         when the trace buffer wraps, TRSPOOL may loose trace events under
  306.         very erratic system performance.
  307.  
  308.         TRSPOOL will operate without parameter specification in adaptive
  309.         polling mode. However the following parameters may be specified:
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.         
  328.                                                                 Overview  4
  329.  
  330.                             July 15, 1998 - Warp Debug
  331.  
  332.          /An Specifies the target per-centage trace buffer usage for adaptive
  333.              spooling.
  334.              Default: 30(%%). This is the default spooling method.
  335.          /Fn Specifies the number of spooled trace buffer files.
  336.              Default: 10.
  337.          /Tn Specifies fixed time trace buffer spooling, in mili-seconds,
  338.              or if specified with /A the initial sleep time.
  339.              Default: Adaptive spooling - /A option + initial sleep time
  340.              2000ms.
  341.              Note: when adaptive spooling is active, the sleep time interval
  342.              is limitated to a range between 50ms and 60000ms. Any time interval
  343.              may be specified with fixed time spooling.
  344.          /Q  Specifies quiet operation - messages are suppressed.
  345.              Default: non-quiet mode.
  346.          /W  Specifies write-through mode. Trace files are pre-allocated
  347.              and opened in write-through mode.
  348.              Default: normal file open mode.
  349.          /P  Specifies trace files should be pre-allocated.
  350.              Default: files are not pre-allocated unless /W is specified.
  351.          /?  Display help.
  352.  
  353.  
  354.         The generated trace buffer files have names: TRACEBUF.nnn, where
  355.         nnn ranges from 000 to the value specified by /Fn.
  356.  
  357.         The /W option is provided for use where tracing precedes a system
  358.         outage and there is no orderly shutdown. This disadvantage of using
  359.         this option is that writing to the TRACEBUG.nnn files is made
  360.         synchronous, consequently the time take to spool the trace buffer
  361.         will be longer.
  362.  
  363.         The /P option pre-allocates and initialises all TRACEBUF.nnn files
  364.         to nulls. This ensures that space is available on hard disk for the
  365.         requisite TRACEBUF.nnn files. In addition there is an improved
  366.         chance that data written to these files will be committed should a
  367.         system outage occur. The /P option is implied by /W.
  368.  
  369.         Note: Neither of the /P or /W options is fail-safe. If a system
  370.         outage occurs after the trace buffer has been read, but before data
  371.         has been committed to disk then it will not be recorded. However,
  372.         the segment allocated by TRSPOOL for the local copy of the trace
  373.         buffer is reported at initialisation. This may also be located from
  374.         a system dump by searching for the eye-catcher "TRSPOOL RAS DATA"
  375.         in the TRSPOOL stack segment. The trace buffer selector follows the
  376.         eye-catcher. The file number of the last file written is also
  377.         recorded as a word following the trace buffer selector.
  378.  
  379.         To use TRSPOOL, the system trace must first be enabled by
  380.         specifying
  381.  
  382.  
  383.  
  384.         
  385.                                                                 Overview  5
  386.  
  387.                             July 15, 1998 - Warp Debug
  388.  
  389.            TRACEBUF=63
  390.  
  391.  
  392.         in the CONFIG.SYS.
  393.  
  394.         The system trace is activated by using the TRACE command or TRACE=
  395.         statement of CONFIG.SYS.
  396.  
  397.  
  398.         1.3.3 DTRACE
  399.  
  400.         DTRACE exploits the DosDynamicTrace facility at a low-level.  This
  401.         may be used to implement ad-hoc tracing in DLLs, Device Drivers,
  402.         File System Drivers and the OS2 Kernel.  EXE files are also
  403.         included.  Dynamic Trace may be used for diagnostic purposes and
  404.         performance monitoring.
  405.  
  406.         Dynamic trace is a facility available within the OS/2 kernel.
  407.         Tracepoints are implemented by modifying dynamically code of
  408.         modules loaded in memory. This is in contrast to Static tracepoints
  409.         which are implemented when applications call the DosSysTrace API.
  410.  
  411.         Dynamic tracepoints are implemented by replacing machine
  412.         instructions at specified points within a module by INT3
  413.         instructions.  This is done by the DosDynamicTrace API.  When the
  414.         INT3 instruction executes, control is passed to the system TRAP3
  415.         exception handler, which in turn passes control to Dynamic Trace if
  416.         the TRAP3 was due to a known tracepoint.  Dynamic Trace interprets
  417.         instructions, which are in Reverse Polish Notation, that were
  418.         passed to it when the trace point was defined.  These instructions
  419.         allow data to be logged in the system trace buffer and local
  420.         variables associated with the tracepoint to be manipulated.  After
  421.         the RPN instruction stream is complete, the original instruction is
  422.         single-stepped then normal execution resumed.
  423.  
  424.         The overhead of dynamic trace is a few milliseconds per tracepoint.
  425.         Normally this is small enough not to make a noticeable difference
  426.         to system performance.
  427.  
  428.  
  429.         1.3.4 USER GUIDE
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.         
  442.                                                                 Overview  6
  443.  
  444.                             July 15, 1998 - Warp Debug
  445.  
  446.         Command Syntax:
  447.  
  448.                DTRACE APPLY trpgm_file [/h=hmte │ /n=name] [/m=major] [/i=id] [/q] [/d]
  449.                DTRACE BUILDTDF trpgm_file [tdf_file] [/m=major] [/n=name] [/i=id] [/q]
  450.         [/d]
  451.                DTRACE REMOVE [trpgm_file │ /h=hmte │ /n=name] [/q] [/d]
  452.                DTRACE CLEARALL [/q] [/d]
  453.                DTRACE QUERY [/h=hmte │ /n=name] [/i=id] [/q] [/d]
  454.                DTRACE GETVARS [/h=hmte │ /n=name] [/i=id] [/v=n:m] [/z] [/r] [/q] [/d]
  455.  
  456.  
  457.         Numeric values may be specified in hexadecimal or decimal.
  458.         Hexadecimal values are signified with either the (C -style) 0x
  459.         prefix, e.g. 0x2f8; or the (assembler-style) h suffix, e.g. 2f8h
  460.  
  461.         Optional command line parameters (/i, /m,  /h and /n) set defaults
  462.         which override the default settings in the header of the trace
  463.         program file.  Overrides for specific tracepoints take precedence
  464.         over the command line and the header in the trace program file.
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.         
  499.                                                                 Overview  7
  500.  
  501.                             July 15, 1998 - Warp Debug
  502.  
  503.         hmte: module handle (any module with an MTE). May be specified also in
  504.               the trace program file.
  505.  
  506.         name: module name.
  507.               name may specify a simple name, a name and extension or a
  508.               fully qualified name with path information.
  509.  
  510.               If a fully qualified name is specified then it is used without
  511.               modification to determine the module handle. If this is unccessful
  512.               the no attempt is made to search for the module.
  513.  
  514.               For partially specified names DTRACE attempts to work out the
  515.               module handle according to the following assumptions:
  516.  
  517.                  if a simple name without extension is specified then .DLL is
  518.                  assumed. If the DLL is not loaded then LIBPATH is used to search
  519.                  and load the DLL.
  520.  
  521.                  All other module types must specify at the very least
  522.                  name and extension. If the module is not already loaded then
  523.                  PATH is seached for determine the fully qualified module name
  524.                  and hence the module handle.
  525.  
  526.  
  527.               The following types of module may be traced:
  528.  
  529.                  Physical Device Drivers
  530.                  Virtual Device Drivers
  531.                  File System Drivers
  532.                  Printer Drivers
  533.                  Queue Drivers
  534.                  Custom DLLs (DLLs with non-DLL extension names)
  535.                  EXE modules
  536.                  Custom EXE modules (EXEs with a non_EXE extension or no extension)
  537.                  Base device drivers.
  538.                  Any of the above in non-PATH or LIBPATH directories.
  539.  
  540.               For BASEDEVs the system records the path name as
  541.               being the root directory of the boot drive regardless of which
  542.               directory the driver was loaded from. DTRACE will attempt to
  543.               derive the module handle of a BASEDEV automatically if only
  544.               name and extension are supplied.
  545.  
  546.               Build BUILDTDF may be used for non-DLL modules however under
  547.               OS/2 3.0+ JR09872 is required for the TRACE command to process
  548.               TDFs for non-DLL modules.
  549.  
  550.         major: The default major code. May also be specified in the trace program
  551.                file. Major codes specified with specific tracepoints in the trace
  552.                program file override any other specification.
  553.  
  554.  
  555.         
  556.                                                                 Overview  8
  557.  
  558.                             July 15, 1998 - Warp Debug
  559.  
  560.         id: Superset grouping of tracepoints. May include more than one major
  561.             code. Defaults to 0 when defining tracepoints. NB dynamic trace
  562.             generated by TRCUST uses id=0, unless overridden by TDFID=. Id may
  563.             be specified also in the trace program file.
  564.  
  565.             Id is intended for use with the  QUERY and GETVARS functions.
  566.             These functions will assume all non-zero ids are to be processed if
  567.             id is not specified.
  568.  
  569.         n:m Variables n to m. Dynamic Trace variables are referred to by index number
  570.             starting with 0. Number of variables defined is determined by the
  571.             vars= statement of the trace program file.
  572.  
  573.         z:  Zero variables.
  574.  
  575.         r:  Read variables.
  576.  
  577.         q:  Suppress copyright and incidental informational messages.
  578.  
  579.         d:  Debugging switch. This is provided for diagnosing problems with DTRACE.
  580.             It should only be used at the request of Service personnel.
  581.             Note: DTRACE also has associated DTRACE.TDF and TRC0063.TFF files which
  582.             permit inernal tracing of DTRACE itself by means of TRACE ON DTRACE.EXE
  583.  
  584.         trpgm_file: Trace program file. If a simple name is specified then
  585.             an extension of .RPN is assumed.
  586.             See below. for the file description.
  587.  
  588.         tdf_fiie: The generated Trace Definition File name. See below.
  589.  
  590.  
  591.         Options that may also be specified in the trace program file are
  592.         overridden when specified on the command line.
  593.  
  594.  
  595.         1.3.5 DTRACE FUNCTIONS
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.         
  613.                                                                 Overview  9
  614.  
  615.                             July 15, 1998 - Warp Debug
  616.  
  617.         APPLY:    Insert dynamic tracepoints, specified by the trace program
  618.                   file for a module specified by name or hmte. A full
  619.                   description of the trace program file is given below.
  620.  
  621.         BUILDTDF: Build a Trace Definition File (TDF) from the definitions
  622.                   supplied in the trace program file. The OS/2 TRACE command
  623.                   may be used subsequently to apply or removed all or selected
  624.                   tracepoints defined in the TDF.
  625.  
  626.                   TFD files must be stored in the current directory, DPATH or
  627.                   in \OS2\SYSTEM\TRACE.
  628.  
  629.                   BUILDTDF permits group and type classifications to be
  630.                   specified with each tracepoint. These may be used by the
  631.                   OS/2 TRACE command to select subsets of tracepoints to be
  632.                   activated. The TRACE command also permits specific minor
  633.                   codes, or ranges of minor codes to be specified.
  634.  
  635.                   The syntax for the TRACE command using a TDF file is as
  636.                   follows:
  637.  
  638.                          TRACE ON│OFF tdf_file
  639.  
  640.                     or   TRACE ON tdf_file(minor spec)
  641.  
  642.                     or   TRACE ON tdf_file(group spec)
  643.  
  644.                     or   TRACE ON tdf_file(type spec)
  645.  
  646.                   where:
  647.  
  648.                          tdf_file is the file name, excluding path and
  649.                          extension of the tdf_file.
  650.  
  651.                          minor spec is a combination of minor code or
  652.                          ranges of minor codes separated by commas.
  653.                          In the following example KERNEL minor codes
  654.                          (decimal) 1, 2 through 10 and 401 are traced.
  655.  
  656.                             TRACE ON KERNEL(1,2-10,401)
  657.  
  658.                          group spec is a combination of groups separated by
  659.                          commas. Each group may further specify one or more
  660.                          types.
  661.                          In the following example KERNEL group FS (with
  662.                          all types) and TK with types PRE and POST is traced.
  663.  
  664.                             TRACE ON KERNEL(FS,TK:PRE+POST)
  665.  
  666.                          type spec is a combination of types separated by
  667.                          commas. In the following example all KERNEL PRE and
  668.  
  669.         
  670.                                                                Overview  10
  671.  
  672.                             July 15, 1998 - Warp Debug
  673.  
  674.                          POST type tracepoints are traced.
  675.  
  676.                             TRACE ON KERNEL(PRE,POST)
  677.  
  678.                   Notes:
  679.  
  680.                   Due to a limitation with the TRACE command, BUILDTDF
  681.                   can only be used to create TDFs for DLLs and OS2KRNL unless
  682.                   JR09872 is installed.
  683.  
  684.                   If the TRACE command fails to find the TDF in the DPATH it
  685.                   will look in \OS2\SYSTEM\TRACE\SYSTEM.TDF before looking
  686.                   finally for \OS2\SYSTEM\TRACE\tdf_file. The becomes an
  687.                   important consideration when one of the pre-existing system
  688.                   trace definitions is modified or replaced.
  689.  
  690.                   The TRACE command fails to find OS2KRNL.TDF in
  691.                   in OS2\SYSTEM\TRACE if executed from a command line where
  692.                   the current directory is other than on the boot drive.
  693.                   APAR PJ23293 addresses this problem.
  694.  
  695.                   See the accompanying TRCTOOLS documentation for further
  696.                   information of modifying and replacing system trace
  697.                   definitions.
  698.  
  699.         REMOVE:   Remove dynamic tracepoints for a module specified by name or
  700.                   handle.
  701.  
  702.         CLEARALL: Remove all dynamic tracepoints for all modules.
  703.  
  704.         QUERY:    Query by id or hmte all traced modules, their ids and number
  705.                   of Dynamic Trace variables.
  706.  
  707.                   By default all non-zero ids are queried.
  708.  
  709.                   Note: Standard system dynamic trace definitions and user
  710.                   definitions that are defined using TRCUST are always defined
  711.                   with id=0.
  712.  
  713.         GETVARS:  Retrieve and/or set to zero the Dynamic Trace variables for
  714.                   a given id or module.
  715.  
  716.                   By default all variables of all non-zero ids are retrieved.
  717.  
  718.                   Variables are displayed as a list in hexadecimal and decimal
  719.                   formats.
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.         
  727.                                                                Overview  11
  728.  
  729.                             July 15, 1998 - Warp Debug
  730.  
  731.         1.3.6 FORMAT OF THE TRACE PROGRAM FILE
  732.  
  733.         This file specifies one or more tracepoints for a module.  Each
  734.         tracepoint may have an associated program that species to
  735.         DynamicTrace what variables to manipulate and what data to log in
  736.         the system trace buffer when the tracepoint fires.
  737.  
  738.         Comments may appear after the instructions or on whole lines. They
  739.         are prefixed with a semi-colon.
  740.  
  741.         Blanks are ignored by DTRACE.
  742.  
  743.         The trace program consists of a header followed by one or more
  744.         tracepoint definitions. Each tracepoint definition has a header
  745.         followed by an optional program specified as a sequence of Reverse
  746.         Polish Notation instructions.  The RPN commands use a circular
  747.         stack of 16 double-word elements as a work space.  The top element
  748.         of the stack is the only immediately accessible element.  As each
  749.         element is accessed the top of stack (TOS) pointer is moved to
  750.         point to the preceding stack element - this is referred to as a POP
  751.         operation even though the popped stack element is not actually
  752.         removed from the stack.  Thus an RPN command that takes two stack
  753.         parameters pops the two topmost elements from the stack.  Whenever
  754.         data on the stack is referenced it is done so in integral numbers
  755.         of elements.  Thus pushing or popping a word will move the stack
  756.         pointer as if a double-word had been pushed or popped. Word and
  757.         byte length data is always padded to a double-word when pushed on
  758.         to the stack.
  759.  
  760.         The trace program may be used for three purposes (which may be
  761.         combined):
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.         
  784.                                                                Overview  12
  785.  
  786.                             July 15, 1998 - Warp Debug
  787.  
  788.         1) To cause one or more items of data to be logged in the system
  789.            trace buffer.
  790.  
  791.         2) To update local variables which are associated with a particular
  792.            module being traced.
  793.         3) To detect a specific condition (value of a register, value in
  794.            memory or code path) and force a System Dump when that condition
  795.            occurs.
  796.  
  797.            NB: this function is not available in all releases of OS/2.
  798.  
  799.  
  800.         The entire set of trace definitions and local variables for a
  801.         particular module is referred to as a Dynamic Trace Object (DTO).
  802.  
  803.  
  804.         One DTO may exist per module. DosDynamicTrace will not merge an
  805.         existing DTO with additional definitions for the same module.
  806.  
  807.  
  808.         DTOs for several modules may be grouped under the same id - see
  809.         the /i parameter above and the id= parameter below.
  810.  
  811.  
  812.         1.3.7 RPN COMMAND SYNTAX
  813.  
  814.         RPN command syntax rules are as follows:
  815.  
  816.         [label:] operator [operand1 [,operand2 [, ..... ]]] [; comment]
  817.         [;comment]
  818.  
  819.         Where:
  820.  
  821.         label
  822.               is an optional string of 1 - 255 characters, excluding ':',
  823.               initiated with a non-numeric character and delimited by a ':'.
  824.               A label must always precede a command, but the command my be
  825.               coded on the following line. Labels are for use by the jump
  826.               instructions as an alternative to coding an explicit numeric
  827.               value. Backward jumping is not permitted.
  828.  
  829.         operator
  830.               is one of the valid RPN commands listed below.
  831.  
  832.         operand1,...
  833.               are operands as defined by each RPN command.
  834.  
  835.  
  836.         A comment is initiated by a ';' and may follow on the same line as
  837.         a command or on a new line.
  838.  
  839.  
  840.         
  841.                                                                Overview  13
  842.  
  843.                             July 15, 1998 - Warp Debug
  844.  
  845.         RPN commands,labels and operators are case insensitive.
  846.  
  847.         Imbedded blanks are ignored.
  848.  
  849.         Data logged by DTRACE may be formatted using TRACEFMT. The format
  850.         will be in hexadecimal bytes unless a custom trace format file has
  851.         been generated using the TRCUST utility. When using TRCUST, specify
  852.         the TP parameter as @STATIC. The prefixes %P and %R may be used.
  853.         See the OS/2 Debugging Handbook (SBOF-8617).
  854.  
  855.         Refer to the OS/2 Debugging Handbook, Volume 1 and 3 for further
  856.         information on the system trace utility.
  857.  
  858.  
  859.         1.4 FILE HEADER
  860.  
  861.         Zero or more of the following may be specified, in any order:
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.         
  898.                                                                Overview  14
  899.  
  900.                             July 15, 1998 - Warp Debug
  901.  
  902.         vars=     Number of Dynamic Trace variables to be defined
  903.                   (initialised to zero).
  904.         major=    Major code
  905.         hmte=     Module handle
  906.         id=       DTO grouping id - not to be confused with typedef or
  907.                   groupdef ids. This is a gouping of Dynamic Trace Objects.
  908.                   The default DTO id is 0. Id is used with GETVARS and QUERY
  909.                   functions.
  910.         logmax=   Maximum data to be logged in the trace buffer (default 512
  911.                   bytes).
  912.         name=     Module name. See name specification above.
  913.         typedef=  Defines a type keyword. This is used only by the BUILDTDF
  914.                   function. The definition is specified as:
  915.  
  916.                        typedef=keyword,id.
  917.  
  918.                    Keyword is a string, which is used by type statements, see
  919.                    below.
  920.  
  921.                    id is a value equal to a power of two in the range 2**1 to
  922.                    2**31.
  923.  
  924.                    Multple typedef statements my be specified.
  925.  
  926.         groupdef= Defines a group keyword. This is used only by the BUILDTDF
  927.                   function. The definition is specified as:
  928.  
  929.                        groupdef=keyword,id.
  930.  
  931.                    Keyword is a string, which is used by group statements, see
  932.                    below.
  933.  
  934.                    id is a value in the rande 0x to 0xffffffff.
  935.  
  936.                    Multple groupdef statements my be specified.
  937.  
  938.  
  939.         Major code and hmte are required but may be specified or overridden
  940.         by the command line parameters.
  941.  
  942.         If name and hmte are specified then the first parameter encountered
  943.         takes precedence.
  944.  
  945.         id defaults to zero.
  946.  
  947.         vars defaults to zero.
  948.  
  949.         logmax defaults to 512.
  950.  
  951.         The BUILDTDF function requires all definitions to be completely
  952.         specified within the trace program file. Furthermore name must be
  953.  
  954.         
  955.                                                                Overview  15
  956.  
  957.                             July 15, 1998 - Warp Debug
  958.  
  959.         specified rather than a module's hmte.
  960.  
  961.  
  962.         1.5 TRACEPOINT HEADER
  963.  
  964.         The following must be specified, in any order, with the exception
  965.         that minor= must appear first.
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.         
  1012.                                                                Overview  16
  1013.  
  1014.                             July 15, 1998 - Warp Debug
  1015.  
  1016.         minor=    Tracepoint minor code
  1017.  
  1018.         major=    Tracepoint major code - this may be respecified for
  1019.                   each tracepoint and overrides the major code specified
  1020.                   in the file header. This applies to which the current
  1021.                   tracepoint.
  1022.  
  1023.         opcode=   Byte of opcode in module where the tracepoint will be
  1024.                   inserted.
  1025.  
  1026.         object=   Relative object of module where trace point will be
  1027.                   applied. Objects are numbered from 1.
  1028.  
  1029.         offset=   Offset within object where tracepoint will be applied.
  1030.  
  1031.         major=    The major code override for a specific tracepoint. The
  1032.                   default major code must be specified in the header to the
  1033.                   trace program file.
  1034.  
  1035.         type=     Type is an optional parameter that is used only by the
  1036.                   BUILDTDF function. Its purpose is to associate with each
  1037.                   tracepoint one or more types. These are used by the
  1038.                   OS/2 TRACE command as a means of selecting a subset of the
  1039.                   tracepoints defined in the generated TDF. The operand to the
  1040.                   type= statement is be specified as a sequence of one or more
  1041.                   keyword names defined by typedef statements, separated
  1042.                   '+' signs as follows:
  1043.  
  1044.                       type=[keyword1[+keyword2 ...]]
  1045.  
  1046.                   A typical use of the trace type is to associate a particular
  1047.                   tracepoint with a particular characteristic. For example,
  1048.                   tracepoints in DOSCALL1 and KERNEL use type=PRE for API
  1049.                   pre-invocation tracepoints and type=POST for
  1050.                   API post-invocation tracepoints.
  1051.  
  1052.                   Only one type statement is permissible per tracepoint.
  1053.  
  1054.         group=    Group is an optional parameter that is used only by the
  1055.                   BUILDTDF function. Its purpose is to associate related
  1056.                   subsets of the set of tracepoints defined in the generated
  1057.                   TDF. These are used by the OS/2 TRACE command as a means of
  1058.                   selecting a subset of the tracepoints defined in the
  1059.                   generated TDF. The operand to the group= statement is
  1060.                   specified as a single keyword name that has been defined by
  1061.                   the groupdef statements.
  1062.  
  1063.                   A typical use of the trace group is to associate all
  1064.                   tracepoints that relate to a particular component of the
  1065.                   system. For example, the group FS is used to associate all
  1066.                   tracepionts in DOSCALL1 and KERNEL that relate to the
  1067.  
  1068.         
  1069.                                                                Overview  17
  1070.  
  1071.                             July 15, 1998 - Warp Debug
  1072.  
  1073.                   file-system.
  1074.  
  1075.                   Group is intended to be an exclusive classification of
  1076.                   tracepoints compared with Type. Only one group may be
  1077.                   associated with a particular tracepoint, whereas a
  1078.                   tracepoint may have several type.
  1079.  
  1080.                   Only one group statement is permissible per tracepoint.
  1081.  
  1082.  
  1083.  
  1084.  
  1085.         1.6 THE TRACE PROGRAM
  1086.  
  1087.         Trace program may specify any meaningful combination of the
  1088.         following RPN instructions. (TOS = Top of Stack).
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.         
  1126.                                                                Overview  18
  1127.  
  1128.                             July 15, 1998 - Warp Debug
  1129.  
  1130.         Leng  Mnem  Operand(s)  Description
  1131.         -th   -onic
  1132.         Bytes
  1133.         ---------------------------------------------------------------------
  1134.         1     Abort             Abort - Log No Information
  1135.         1     Add               Add top 2 DWORD stack elements
  1136.         1     Cnvrt DXS         Convert Dword to Segmented
  1137.         1     Cnvrt FXS         Convert Flat to Segmented
  1138.         1     Cnvrt SXD         Convert Segmented to Dword
  1139.         1     Cnvrt SXF         Convert Segmented to Flat
  1140.         3     Inc   V,word      Increment Immediate Variable
  1141.         1     Inc   VIi         Increment indexed Variable
  1142.         3     Jmp   N,word      Jump forward N bytes or to a label
  1143.         3     Jmp   NN,word     Jump forward N bytes or to a label if TOS < 0
  1144.         3     Jmp   PN,word     Jump forward N bytes or to a label if TOS > 0
  1145.         3     Jmp   ZN,word     Jump forward N bytes or to a label if TOS = 0
  1146.         1     Log   ARF         Log ASCIIZ at Flat Range
  1147.         1     Log   ARS         Log ASCIIZ at Segmented Range
  1148.         2     Log   DN,byte     Log N DWORDs
  1149.         1     Log   MRF         Log Memory at Flat Range
  1150.         1     Log   MRS         Log Memory at Segmented Range
  1151.         2     Log   WN,byte     Log N WORDs
  1152.         3     Move  V,word      Move top of stack to Immediate Var.
  1153.         1     Move  VIi         Move top of stack to indexed Var.
  1154.         1     Mul               Multiply top 2 stack elements
  1155.         3     Or    V,word      OR immed. indexed variable with TOS
  1156.         2     Pop   N,byte      Rotate stack down (pop) N times
  1157.         1     Push  CS          Push contents of (CS)
  1158.         5     Push  D,dword     Push DWORD Immediate
  1159.         1     Push  DS          Push contents of (DS)
  1160.         1     Push  EAX         Push contents of (EAX)
  1161.         1     Push  EBP         Push contents of (EBP)
  1162.         1     Push  EBX         Push contents of (EBX)
  1163.         1     Push  ECX         Push contents of (ECX)
  1164.         1     Push  EDI         Push contents of (EDI)
  1165.         1     Push  EDX         Push contents of (EDX)
  1166.         1     Push  EFlags      Push contents of (EFlags)
  1167.         1     Push  EIP         Push contents of (EIP)
  1168.         1     Push  ES          Push contents of (ES)
  1169.         1     Push  ESI         Push contents of (ESI)
  1170.         1     Push  ESP         Push contents of (ESP)
  1171.         1     Push  FIF         Push Flat Indirect Flat
  1172.         1     Push  FS          Push contents of (FS)
  1173.         1     Push  GS          Push contents of (GS)
  1174.         5     Push  OXF,dword   Push (DWORD Object to Flat Address)
  1175.         2     Push  OXS,byte    Push (Object to Selector)
  1176.         1     Push  SIS         Push Segmented Indirect Segmented
  1177.         1     Push  SS          Push contents of (SS)
  1178.         3     Push  V,word      Push Immediate Variable
  1179.         1     Push  VIi         Push indexed Variable
  1180.         3     Push  W,word      Push WORD Immediate
  1181.  
  1182.         
  1183.                                                                Overview  19
  1184.  
  1185.                             July 15, 1998 - Warp Debug
  1186.  
  1187.         1     Push  WIS         Push WORD Indirect Segmented
  1188.         1     Remove            Remove the current tracepoint
  1189.         1     Sub               Subtract top 2 stack elements
  1190.         1     SysDump           Force a system Dump (*)
  1191.         1     And               AND top 2 stack elements (*)
  1192.         1     Or                OR top 2 stack elements (*)
  1193.         1     Xor               XOR top 2 stack elements (*)
  1194.         1     Neg               1's complement TOS (*)
  1195.         1     Exit              Log data and exit tracepoint (*)
  1196.         3     SetMin W,word     Override the tracepoint minor code with 'word' (**)
  1197.         1     SetMin            Override the tracepoint minor code from TOS    (**)
  1198.         3     SetMaj W,word     Override the tracepoint major code with 'word' (**)
  1199.         1     SetMaj            Override the tracepoint major code from TOS    (**)
  1200.         1     Xchg              Swap top two elements on the stack.            (**)
  1201.  
  1202.  
  1203.         * Each of the commands flagged with (*) require APAR PJ22196
  1204.         applying to the OS2KRNL (available with Warp 3.0 FixPak 29 and Warp
  1205.         4.0 GA).
  1206.  
  1207.         ** Each of the commands flagged with (**) will be supported the GA
  1208.         version of OS/2 Warp 4.0 and Warp 3.0 FixPak 29.
  1209.  
  1210.         Each of these commands acts as follows:
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.         
  1240.                                                                Overview  20
  1241.  
  1242.                             July 15, 1998 - Warp Debug
  1243.  
  1244.         PUSH: Push a value on to the RPN stack
  1245.  
  1246.            In Push SS and Push ESP the value of SS and ESP is dependent on whether the
  1247.            tracepoint occurred at ring 0 or not.
  1248.  
  1249.            In Push EIP, the EIP on the stack is one too large, due to the
  1250.            INT3.
  1251.  
  1252.            Push W takes a word operand, zero extends it, and pushes
  1253.            it on to the RPN stack.
  1254.  
  1255.            Push OXS converts its byte operand into a selector,
  1256.            zero extends that value, and pushes it on to the stack.
  1257.            The byte operand is on object number of the module which
  1258.            is currenlty being traced.
  1259.            Because MTEs may eventually become nonresident, the selectors
  1260.            (up to 256) are stored in an array by DynamicTrace  when the tracepoints
  1261.            were inserted.  The word operand indexes this array to get the sel.
  1262.  
  1263.            Push WIS pops an offset, then a selector, from the RPN stack,
  1264.            fetches the user word at that 16:16 address, zero extends it,
  1265.            and pushes that on to the RPN stack.
  1266.            If the address is invalid or not present, a GP fault or Page
  1267.            fault record will be logged in the buffer, and the interpreter
  1268.            will exit.
  1269.  
  1270.            Push SIS pops an offset, then a selector, from the RPN stack,
  1271.            fetches the user dword at that 16:16 address and pushes that on to
  1272.            the RPN stack in the segmented address format.* That is,
  1273.            the high word (selector) is zero extended and pushed, and then
  1274.            the low word (offset) is zero extended and pushed.
  1275.            If the address is invalid or not present, a GP fault or Page
  1276.            fault record will be logged in the buffer, and the interpreter
  1277.            will exit.
  1278.  
  1279.            Push OXF converts its dword operand into a flat address,
  1280.            and pushes that on to the stack. See description of PUSH OXS for
  1281.            more details.
  1282.  
  1283.            Push FIF pops a Dword from the RPN stack, and then
  1284.            pushes the dword at that flat address on to the stack.
  1285.  
  1286.            Push V takes a word operand. Push V uses that to index
  1287.            to the Dynamic Trace variable in the current DTO, and pushes the value
  1288.            it finds there.
  1289.  
  1290.            Push VIi fetches an index of a Dynamic Trace variable from
  1291.            the top of the stack, (without doing a pop), and then
  1292.            pushes the value of that variable on to the stack.
  1293.  
  1294.         LOG: Log data in the system trace buffer.
  1295.  
  1296.         
  1297.                                                                Overview  21
  1298.  
  1299.                             July 15, 1998 - Warp Debug
  1300.  
  1301.  
  1302.            Log WN takes a byte operand, and repeats the following operation
  1303.            that many times:
  1304.               Pop the value from the top of the RPN stack
  1305.               Log the low word of that value, ignoring the high word.
  1306.            If the log overflows, the interpreter will exit without continuing,
  1307.            but will record as much as it can.
  1308.  
  1309.            Log MRS pops the following from the RPN stack:
  1310.              Offset
  1311.              Selector
  1312.              Length
  1313.  
  1314.            Log MRS then zero extends all these values, and attempts to
  1315.            move Length number of bytes from the given 16:16 address into
  1316.            the log buffer.
  1317.  
  1318.            The logged memory is prefixed by 3 bytes :
  1319.              Token byte of 0,
  1320.              Length word (length of logged information, in bytes)
  1321.  
  1322.            If an address is invalid or not present, a GP fault or Page
  1323.            fault record will be logged in the buffer, and the interpreter
  1324.            will exit.
  1325.  
  1326.            If the log overflows, the interpreter will exit without continuing,
  1327.            and without logging the memory.
  1328.  
  1329.            Log ARS pops the following from the RPN stack:
  1330.              Offset
  1331.              Selector
  1332.              Length
  1333.  
  1334.            Log ARS then zero extends all these values, and attempts to
  1335.            move Length number of bytes from the given 16:16 address into
  1336.            the log buffer.  The data transfer will be discontinued if a
  1337.            null byte is fetched.  The null byte will not be logged.
  1338.  
  1339.            The logged string is prefixed by 3 bytes :
  1340.              Token byte of 1,
  1341.              Length word (length of logged information, in bytes)
  1342.  
  1343.            If an address is invalid or not present, a GP fault or Page
  1344.            fault record will be logged in the buffer, and the interpreter
  1345.            will exit.
  1346.  
  1347.            If the log overflows, the interpreter will exit without continuing,
  1348.            and without logging the string.
  1349.  
  1350.            Log DN takes a byte operand, and repeats the following operation
  1351.            that many times:
  1352.  
  1353.         
  1354.                                                                Overview  22
  1355.  
  1356.                             July 15, 1998 - Warp Debug
  1357.  
  1358.               Pop the value from the top of the RPN stack
  1359.               Log the value (as a DWORD)
  1360.  
  1361.            If the log overflows, the interpreter will exit without continuing,
  1362.            but will record as much as it can.
  1363.  
  1364.            Log MRF pops the following from the RPN stack:
  1365.               Flat Address
  1366.               Length
  1367.  
  1368.            Log MRF then zero extends the length, and attempts to move
  1369.            Length number of bytes from the given flat address into
  1370.            the log buffer.
  1371.  
  1372.            The logged memory is prefixed by 3 bytes :
  1373.               Token byte of 0,
  1374.               Length word (length of logged information, in bytes)
  1375.  
  1376.            If an address is not present, a Page fault record will be
  1377.            logged in the buffer, and the interpreter will exit.
  1378.  
  1379.            If the log overflows, the interpreter will exit without continuing,
  1380.            and without logging the memory.
  1381.  
  1382.  
  1383.            Log ARF pops the following from the RPN stack:
  1384.               Flat Address
  1385.               Length
  1386.  
  1387.            Log ARF then zero extends the length, and attempts to move
  1388.            Length number of bytes from the given flat address into
  1389.            the log buffer.  The data transfer will be discontinued if a
  1390.            null byte is fetched.  The null byte will not be logged.
  1391.  
  1392.            The logged string is prefixed by 3 bytes :
  1393.               Token byte of 1,
  1394.               Length word (length of logged information, in bytes)
  1395.  
  1396.            If an address is not present, a Page fault record will be
  1397.            logged in the buffer, and the interpreter will exit.
  1398.  
  1399.            If the log overflows, the interpreter will exit without continuing,
  1400.            and without logging the string.
  1401.  
  1402.  
  1403.            When memory references are invalid the token byte is set to one of
  1404.            the following to indicate the type of error encountered:
  1405.  
  1406.               -1  Invalid Selector
  1407.               -2  Selector not Present
  1408.               -3  Page not Present
  1409.  
  1410.         
  1411.                                                                Overview  23
  1412.  
  1413.                             July 15, 1998 - Warp Debug
  1414.  
  1415.  
  1416.            The byte count is set to 4 and the data logged is the fault
  1417.            address.
  1418.  
  1419.  
  1420.         ADD/SUB/MUL/AND/OR/XOR: Add/Subtact/Multiply the top two stack
  1421.            elements
  1422.  
  1423.            Add pops two DWORDs from the RPN stack, and pushes their sum.
  1424.  
  1425.            Sub pops two DWORDs from the RPN stack, and pushes their
  1426.            difference.   The first value popped is subtracted from the second.
  1427.  
  1428.            Mul pops two DWORDs from the RPN stack, and pushes their
  1429.            product.
  1430.  
  1431.            And pops two DWORDs from the RPN stack, and pushes their
  1432.            bit-wise AND.
  1433.  
  1434.            Or pops two DWORDs from the RPN stack, and pushes their
  1435.            bit-wise Or.
  1436.  
  1437.            Xor pops two DWORDs from the RPN stack, and pushes their
  1438.            bit-wise Xor.
  1439.  
  1440.         NEG: 1's complement top of stack.
  1441.  
  1442.            Neg 1's complements the TOS. No data is pushed or popped.
  1443.  
  1444.         CNVRT: Convert an address
  1445.  
  1446.            Cnvrt FXS pops a dword from the RPN stack, uses CRMA
  1447.            to translate that flat pointer to a 16:16 segmented pointer.
  1448.            It then pushes the selector (zero extended) and then the
  1449.            offset (zero extended) on to the stack.
  1450.  
  1451.            If the flat address does not lie within the compatibility
  1452.            region, the interpreter will exit immediately.
  1453.  
  1454.  
  1455.            Cnvrt SXF pops a selector, then an offset from the RPN stack,
  1456.            uses CRMA to translate that 16:16 pointer to a flat address,
  1457.            and pushes that flat address on to the stack.
  1458.  
  1459.            If the segmented address does not lie within the comparability
  1460.            region (GDT selector), the interpreter will exit immediately.
  1461.  
  1462.            Cnvrt DXS pops a DWORD, then pushes the high word (zero
  1463.            extended) and then the low word (zero extended).  No CRMA is
  1464.            applied.
  1465.  
  1466.  
  1467.         
  1468.                                                                Overview  24
  1469.  
  1470.                             July 15, 1998 - Warp Debug
  1471.  
  1472.            Cnvrt SXD pops a low word, then a high word, then
  1473.            concatenates them into a DWORD, and pushes the result.
  1474.  
  1475.  
  1476.         POP: Pop a value from the RPN stack.
  1477.  
  1478.              Pop N takes a byte operand, and pops that many operands
  1479.              from the stack.  As the values are not actually removed from
  1480.              the 16-element circular stack, Pop N effectively rotates
  1481.              the stack down.
  1482.  
  1483.  
  1484.         MOVE: Move a value to a variable.
  1485.  
  1486.            Move V takes a word operand. Move V then moves
  1487.            the value on the top of the stack to the Dynamic Trace variable
  1488.            in the current DTO at that index.  The top of stack pointer
  1489.            is not changed.
  1490.  
  1491.            Move VIi pops a variable index off the top of the stack,
  1492.            and then pops a value off the top of the stack.  The value is moved
  1493.            into the Dynamic Trace variable in the current DTO at that index.
  1494.            The variable and the index are then pushed back on to the stack,
  1495.            so that there is no net change on the stack at all.
  1496.  
  1497.            If the index is too large, the interpreter will exit with an error.
  1498.  
  1499.         INC: Increment a variable.
  1500.  
  1501.            Inc V takes a word operand, and increments the value in the
  1502.            Dynamic Trace variable in the current DTO at that index.
  1503.  
  1504.            Inc VIi fetches an index of a Dynamic Trace variable from
  1505.            the top of the stack, (without doing a pop), and then
  1506.            increments the value of that variable.
  1507.  
  1508.            If the index is too large, the interpreter will exit with an error.
  1509.  
  1510.  
  1511.         JMP: Jump forward in the RPN program.
  1512.  
  1513.            Jmp takes a word or label as operand.  Jmp causes an
  1514.            unconditional jump forward in the instruction stream by
  1515.            that number of bytes, relative to the first byte of the next
  1516.            instruction.
  1517.  
  1518.            Therefore, Jmp by 0 bytes is a NOP (i.e jmp n,0)
  1519.  
  1520.  
  1521.            Jmp ZN takes a word or label as operand.  Jmp ZN causes an
  1522.            unconditional jump forward in the instruction stream by
  1523.  
  1524.         
  1525.                                                                Overview  25
  1526.  
  1527.                             July 15, 1998 - Warp Debug
  1528.  
  1529.            that number of bytes, relative to the end of the instruction,
  1530.            but only if the value on the top of the stack is zero.
  1531.  
  1532.            Jmp NN takes a word or label operand.  JmpNN causes an
  1533.            unconditional jump forward in the instruction stream by
  1534.            that number of bytes, relative to the end of the instruction,
  1535.            but only if the value on the top of the stack is negative.
  1536.  
  1537.            Jmp PN takes a word or label operand.  Jmp PN causes an
  1538.            unconditional jump forward in the instruction stream by
  1539.            that number of bytes, relative to the end of the instruction,
  1540.            but only if the value on the top of the stack is positive.
  1541.  
  1542.            To prevent loops, no backward jumps are permitted.  Also, it is
  1543.            illegal to jump into the code stream for another tracepoint.
  1544.  
  1545.            If labels are specified, DTRACE calculates the relative forward
  1546.            offset.
  1547.  
  1548.         REMOVE: Remove and Abort the current tracepoint.
  1549.  
  1550.         ABORT:  Abort the tracepoint.
  1551.  
  1552.            Abort aborts the tracepoint entirely.  The interpreter
  1553.            exits, but does not log any information.  The data logged
  1554.            by this tracepoint is lost.
  1555.  
  1556.            However, alterations to the variables remain.
  1557.  
  1558.            By using Abort in combination with the Jmp
  1559.            instructions, unnecessary tracepoints can be filtered
  1560.            at run time, without crowding or overflowing the log buffer.
  1561.  
  1562.         EXIT:  Exit the tracepoint.
  1563.  
  1564.            Exit terminates the tracepoint.  The interpreter
  1565.            exits, and logs any information requested so far. The tracepoint
  1566.            remains in tact.
  1567.  
  1568.            By using Exit in combination with the Jmp
  1569.            instructions, specific conditions can be detected before logging
  1570.            additional data.
  1571.  
  1572.            If Exit is not available (systems without PJ22196) then the
  1573.            equivalent may be achieved by coding:
  1574.  
  1575.                  jmp n,exit
  1576.                  .
  1577.                  .
  1578.                  .
  1579.                  .
  1580.  
  1581.         
  1582.                                                                Overview  26
  1583.  
  1584.                             July 15, 1998 - Warp Debug
  1585.  
  1586.            exit: jmp n,0 ;nop
  1587.  
  1588.  
  1589.         ORV: OR a Dynamic Trace variable with TOS.
  1590.  
  1591.         SYSDUMP: Force a System Dump.
  1592.  
  1593.            SysDump transfers control to the stand alone dump process. No
  1594.            data is logged. No system shutdown is performed and normal
  1595.            system execution is terminated immediately.
  1596.  
  1597.            Use this command with the Jmp instructions to detect illusive error
  1598.            conditions that require dump analysis at the point of error.
  1599.  
  1600.  
  1601.         SETMAJ: Override the tracepoint major code
  1602.  
  1603.            SetMaj takes the word value from the TSO to override the tracepoint
  1604.            major code. The override remains in effect until the current RPN
  1605.            program exits. Since data is not logged to the system trace buffer
  1606.            until the RPN program exits, the major code may be overridden at any
  1607.            point and remain effective for the whole trace entry.
  1608.  
  1609.            SetMaj may be specified with the W,word operand form. In this case
  1610.            'word' forms the major code override.
  1611.            Note: The system trace facility currently admits only major codes
  1612.            from 0 - 255. Any specification of a major code greater than 255
  1613.            will be treated as if the high-order byte value is zero.
  1614.  
  1615.            This is provided to allow trace formatting templates to be
  1616.            selected dynamically according to the data logged.
  1617.  
  1618.         SETMIN: Override the tracepoint minor code
  1619.  
  1620.            SetMin takes the word value from the TSO to override the tracepoint
  1621.            minor code. The override remains in effect until the current RPN
  1622.            program exits. Since data is not logged to the system trace buffer
  1623.            until the RPN program exits, the minor code may be overridden at
  1624.            any point and remain effective for the whole trace entry.
  1625.  
  1626.            SetMin may be specified with the W,word operand form. In this case
  1627.            'word' forms the minor code override.
  1628.  
  1629.            The system trace facility admit minor codes in the range from
  1630.            0x0000 to 0xffff.
  1631.  
  1632.            This is provided to allow trace formatting templates to be
  1633.            selected dynamically according to the data logged.
  1634.  
  1635.  
  1636.         XCHG: Exchange the top two entries on the RPN Stack.
  1637.  
  1638.         
  1639.                                                                Overview  27
  1640.  
  1641.                             July 15, 1998 - Warp Debug
  1642.  
  1643.  
  1644.            Xchg pops the top two stack elements then pushes them back on to
  1645.            the stack in the reverse order.
  1646.  
  1647.  
  1648.  
  1649.  
  1650.         1.7 TRACE PROGRAM EXAMPLES
  1651.  
  1652.         The following examples illustrate common usages of the RPN
  1653.         commands.
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.         
  1696.                                                                Overview  28
  1697.  
  1698.                             July 15, 1998 - Warp Debug
  1699.  
  1700.         1) Log AX and BX registers:
  1701.  
  1702.                Push EBX
  1703.                Push EAX
  1704.                Log  WN,2 ;lower 16 bits of each DWORD
  1705.  
  1706.         2) Log EIP, EBP and EAX:
  1707.  
  1708.                Push EAX
  1709.                Push EBP
  1710.                Push EIP
  1711.                Log  DN,3  ;3 DWORDs from the stack
  1712.  
  1713.         3) Log value at EBP+ESI:
  1714.  
  1715.                Push W,4  ; push immediate value 4 - length to log
  1716.                Push EBP
  1717.                Push ESI
  1718.                Add       ; add top two DWORDs - puts EBP+ESI on stack
  1719.                Log  MRF  ; log memory at flat address range
  1720.  
  1721.         4) Log value at SS:SP using 16-bit segmented addressing:
  1722.  
  1723.                Push W,9  ; push immediate  value 9 - length to log
  1724.                Push SS
  1725.                Push ESP
  1726.                Log  MRS  ; log memory at segmented address range
  1727.  
  1728.         5) Log 16 bytes of data pointed to by the flat address at SS:SP+8
  1729.  
  1730.                Push W,16 ; push immediate value 16 - length to log
  1731.                Push SS
  1732.                Push ESP
  1733.                Push 8    ; offset 8
  1734.                Add       ; 8 added to ESP value on stack
  1735.                Push SIS  ; pop ESP then SS and pop Dword at that address
  1736.                          ; as two Words extended to Dwords (as if it was a sel:offset).
  1737.                          ; stack now contains the length and split address of data to log
  1738.                Cnvrt SXD ; Concatenate the two words to form a flat address
  1739.                Log  MRF  ; log the data.
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.         
  1753.                                                                Overview  29
  1754.