home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tracecmd.zip / trace.doc next >
Text File  |  1998-07-09  |  62KB  |  1,618 lines
  1.         Trace enhancements for FixPack 35
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.         
  18.  
  19.         
  20.         
  21.  
  22.  
  23.  
  24.         July 9, 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 9, 1998 - Warp Debug
  42.  
  43.  
  44.  
  45.                              July 9, 1998 - Warp Debug
  46.  
  47.         CONTENTS
  48.  
  49.  
  50.           1.0 System Trace (SysTrace) facility  . . . . . . . . . . . . . 1
  51.           1.1 Config.sys statements   . . . . . . . . . . . . . . . . . . 2
  52.           1.2 Command Line Interfaces and Utilities   . . . . . . . . . . 4
  53.             1.2.1 TRACE   . . . . . . . . . . . . . . . . . . . . . . . . 4
  54.               1.2.1.1 TRACEPOINT CONTROL  . . . . . . . . . . . . . . . . 5
  55.               1.2.1.2 CONTROL OPTIONS   . . . . . . . . . . . . . . . . . 9
  56.               1.2.1.3 OPTIONAL DATA CONTROL  . . . . . . . . . . . . . . 10
  57.               1.2.1.4 BUFFER CONTROL   . . . . . . . . . . . . . . . . . 10
  58.             1.2.2 TRACE examples   . . . . . . . . . . . . . . . . . . . 11
  59.             1.2.3 TRACEFMT   . . . . . . . . . . . . . . . . . . . . . . 13
  60.             1.2.4 TRACEGET   . . . . . . . . . . . . . . . . . . . . . . 14
  61.             1.2.5 TRSPOOL  . . . . . . . . . . . . . . . . . . . . . . . 15
  62.             1.2.6 DTRACE   . . . . . . . . . . . . . . . . . . . . . . . 15
  63.             1.2.7 MAPTSF   . . . . . . . . . . . . . . . . . . . . . . . 15
  64.             1.2.8 SYSSPLIT   . . . . . . . . . . . . . . . . . . . . . . 18
  65.               1.2.8.1 Trace formatting files - SYSTEM.TFF  . . . . . . . 19
  66.             1.2.9 TDFLST   . . . . . . . . . . . . . . . . . . . . . . . 20
  67.             1.2.10 TFFLST  . . . . . . . . . . . . . . . . . . . . . . . 20
  68.           1.3 Appendix A New Tracepoints Cross-reference.    . . . . . . 21
  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.  
  101.  
  102.  
  103.  
  104.  
  105.         
  106.                                                                Contents  ii
  107.  
  108.                              July 9, 1998 - Warp Debug
  109.  
  110.         1.0 SYSTEM TRACE (SYSTRACE) FACILITY
  111.  
  112.         The system trace facility collects information about specific
  113.         events to be logged into the trace buffer as they occur. While
  114.         there are several uses for this information the main one is to
  115.         assist in problem resolution.
  116.  
  117.         Enhancements have been made to:
  118.  
  119.         ■  Select process to be traced by process short name
  120.  
  121.         ■  Enablement of Dynamic Tracing at interrupt time
  122.  
  123.         ■  Allow Dynamic Trace to handle forwarded DLLs.
  124.  
  125.         ■  The 256 major code limit has been removed for Dynamic
  126.            tracepoints. Static tracepoints will retain the restriction to
  127.            maintain compatibility with the rest of the system.
  128.  
  129.         ■  The buffer can be grown dynamically (and without requiring a
  130.            reboot) up to:
  131.  
  132.            -  5120 KB - from config.sys (TRACEBUF statement)
  133.  
  134.            -  Whatever is available - from a command line (TRACE function)
  135.  
  136.               Note: While not defined the upper limit will be somewhere
  137.               around 384 MB. This is variable and based on the current
  138.               state of the user's system.
  139.  
  140.         ■  Additional Buffer behavior
  141.  
  142.                The buffer will continue to be a wrapping buffer but the
  143.                user now has the option to have logging to the buffer
  144.                stopped when the buffer is full.
  145.  
  146.                A minimum size of 128k is imposed if a buffer is requested.
  147.                The user should request a buffer large enough to avoid loss
  148.                of data but small enough not to impact memory requirements.
  149.                In practice a buffer size no larger than 1Mb should be
  150.                suitable for most tracing requirements. If a larger capacity
  151.                is required the TRSPOOL utility (described later) can be
  152.                used as an alternative to defining a larger buffer.
  153.  
  154.                The buffer will be comprised of a series of 64KB segments.
  155.                This will be transparent to the user and is done for
  156.                efficiency purposes.
  157.  
  158.                Each trace record and buffer segment will be time-stamped.
  159.                The buffer segment will contain a starting time-stamp that
  160.                is set when the first record is written and an ending
  161.                time-stamp that is originally allocated to zero and updated
  162.                when:
  163.                1. The system selects the next buffer segment,
  164.                2. When TRACE OFF is entered
  165.                3. When TRACE OFF /P:ALL is entered
  166.                4. When TRACE /S is entered
  167.  
  168.         
  169.                                         System Trace (SysTrace) facility  1
  170.  
  171.                              July 9, 1998 - Warp Debug
  172.  
  173.                5. When no-wrap mode is in effect and the last trace buffer
  174.                   segment fills.
  175.  
  176.                Defaults for buffer options:
  177.                    Wrapping (/M:W)
  178.                    NonQueued (/M:NQ)
  179.                    Do not use IPI. (/M:NODTI)
  180.                    Buffer size = 128KB (will be set to 128 if anything less
  181.                    than 128 is requested)
  182.  
  183.  
  184.  
  185.  
  186.         1.1 CONFIG.SYS STATEMENTS
  187.  
  188.         The SysTrace facility has a config.sys statement (TRACEBUF) that
  189.         allows the user to specify information about the trace buffer.
  190.         While it is a good idea to specify this information so that it is
  191.         available at startup time it is not required since there is a
  192.         command line interface (TRACE ON /B:xxx) that can serve the same
  193.         purpose.
  194.  
  195.         WARNING: There should be only one (1) TRACEBUF statement in the
  196.         config.sys file. If there are more than one the buffer size from
  197.         the last one will be used. The /M and /D parameters function in a
  198.         cumulative manner so all of the requests in these functions will be
  199.         set as they are processed. An example is:
  200.  
  201.                         TRACEBUF=128,/M:W,Q,DTI
  202.                         TRACEBUF=512,/M:NW,NQ
  203.  
  204.                 The result of the previous 2 statements would be:
  205.                         TRACEBUF=512,/M:NW,NQ,DTI
  206.                 where:
  207.                         512 - came from the last statement
  208.                         NW - came from the last statement
  209.                         NQ - came from the last statement
  210.                         DTI - came from the first statement
  211.  
  212.  
  213.  
  214.         The syntax of this command is:      TRACEBUF=nnn [,/M] [,/D]
  215.  
  216.         ■  nnn - This mandatory field sets the size of the buffer (in KB).
  217.            The size must be between 1 and 5120.
  218.  
  219.         ■  /M=<mode> - This specifies the mode of the buffer. There are
  220.            several  acceptable values for <mode>and multiples can be
  221.            provided if separated by a comma. They are:
  222.  
  223.            -  W or WRAP - Wrapping mode.
  224.  
  225.                   This specifies that the buffer will wrap when it is full.
  226.                   This will cause the oldest data to be replaced with newer
  227.                   data. While this does cause lost data it is the most
  228.                   efficient way to see a current system activity. This mode
  229.                   (W) will be used unless the non-wrapping mode is
  230.  
  231.         
  232.                                         System Trace (SysTrace) facility  2
  233.  
  234.                              July 9, 1998 - Warp Debug
  235.  
  236.                   specified.
  237.  
  238.            -  NW or NOWRAP - Non-Wrapping mode
  239.  
  240.                   This specifies that the buffer will not wrap but will
  241.                   suspend the SysTrace facility when the buffer is full.
  242.                   While this will not overwrite data it also may not show a
  243.                   current view of system activity.
  244.  
  245.            -  NQ or NOQUEUED - Non-Queued mode.
  246.  
  247.                   Trace records will be discarded if the trace facility is
  248.                   busy at the time the write is attempted. This is not as
  249.                   bad as it sounds since the SysTrace facility is efficient
  250.                   in writing to the buffer and records are very seldom
  251.                   discarded. This mode (NQ) will be used unless the Queued
  252.                   mode is specified.
  253.  
  254.                   This option is provided for the case where tracing with
  255.                   Queued Mode would sufficiently alter timing dependencies
  256.                   of device drivers that handle interrupts from slow or
  257.                   asynchronous devices. The recommendation is that QUEUED
  258.                   mode be used unless a problem with I/O time-out or
  259.                   performance occurs.
  260.  
  261.                   Note: When trace events are lost due to non-queue mode
  262.                   being in effect then a "Lost Events" major code 0, minor
  263.                   code 1 is generated and the next available opportunity.
  264.                   This is done regardless of minor code 0 tracing being
  265.                   active.
  266.  
  267.            -  Q or QUEUED- Queued mode.
  268.  
  269.                   This will cause trace records to be queued (held) if the
  270.                   trace facility is busy. They will be written when the
  271.                   facility is available. This will maintain the integrity
  272.                   of the trace file but could have an adverse affect on
  273.                   performance.
  274.  
  275.            -  DTI - DTI mode
  276.  
  277.                   Dynamic Trace uses Inter Processor Interrupt (IPI) for
  278.                   single stepping tracepoints. While this may provide more
  279.                   reliable trace data it also locks out all of the other
  280.                   processors on a SMP system. This option should only be
  281.                   used when necessary because of the performance impact.
  282.  
  283.                   Note: DTI mode only takes affect on SMP systems. It will
  284.                   be overridden for certain tracepoints that occur within
  285.                   Ring 0 code to avoid deadlocks from occurring.
  286.  
  287.            -  NODTI or NDTI- Non-DTI mode
  288.  
  289.                   Dynamic Trace does not use IPI. This mode will be used
  290.                   unless the DTI mode is specified.
  291.  
  292.         ■  /D=<optional data> - This specifies what optional system data
  293.  
  294.         
  295.                                         System Trace (SysTrace) facility  3
  296.  
  297.                              July 9, 1998 - Warp Debug
  298.  
  299.            will be captured, if available. Acceptable values for <optional
  300.            data> are:
  301.  
  302.            -  PROCNAME - Capture the short name for the process
  303.  
  304.            -  TID - Capture the Task ID
  305.  
  306.            -  SLOT - Capture the Thread's Slot
  307.  
  308.            -  CSEIP - Capture the caller's CS:EIP
  309.  
  310.               Note: Will not be collected if trace is called directly
  311.               through the kernel interface (K_S_Systrace).
  312.  
  313.            -  SSESP - Capture the caller's SS:ESP
  314.  
  315.               Note: Will not be collected if trace is called directly
  316.               through the kernel interface (K_S_Systrace and K_D_SysTrace).
  317.  
  318.            -  TSC - Capture Pentium High Resolution Time-Stamp counter.
  319.               This will be ignored (no error) if not supported by the
  320.               hardware.
  321.  
  322.            -  ALL - Capture all of the optional data
  323.  
  324.            -  NONE - No optional data will be captured. This is the default
  325.               if the /D parameter is not specified.
  326.  
  327.  
  328.  
  329.  
  330.  
  331.         1.2 COMMAND LINE INTERFACES AND UTILITIES
  332.  
  333.  
  334.  
  335.  
  336.         1.2.1 TRACE
  337.  
  338.         The Trace command line interface has been enhanced to allow the
  339.         user to turn on Trace for a specific module by its shortname,
  340.         allocate or de-allocate the trace buffer, set the type of trace
  341.         buffer that is required (wrapping or non-wrapping), and query the
  342.         trace facility for its current status.
  343.  
  344.         All existing options will function as they currently do. The format
  345.         of the command with a discussion of the enhancements follows:
  346.  
  347.          TRACE [ON|OFF] [major_code_spec | (minor_code_spec) | tdf_spec |
  348.          (minor_code_spec) | (event_type_spec) | tdf_keyword |
  349.          (minor_code_spec) | (event_type_spec) | /P:pid_spec |
  350.          /N:<process  name>] [/S] [/R] [/C] [/B:<size of buffer in KB>]
  351.          [/M:<mode>] [/D:<optional data>] [/Q]
  352.  
  353.  
  354.  
  355.         The following sections illustrate parameters that are valid for
  356.  
  357.         
  358.                                         System Trace (SysTrace) facility  4
  359.  
  360.                              July 9, 1998 - Warp Debug
  361.  
  362.         functions provided by the TRACE command.
  363.  
  364.         Note: If "TRACE" is used without any parameters help information
  365.         will be returned showing the proper syntax of the command.
  366.  
  367.  
  368.  
  369.  
  370.         1.2.1.1 TRACEPOINT CONTROL
  371.  
  372.          TRACE ON|OFF {[major_code_spec [(minor_code_spec)]..} [/R|/S] [/C] [/Q]
  373.          TRACE ON|OFF {[module_spec [(event_type_spec)]..} [/R|/S] [/C] [/Q]
  374.          TRACE ON|OFF {[tdf_spec [(event_type_spec)]..} [/R|/S] [/C] [/Q]
  375.          TRACE ON|OFF [KERNEL [(event_type_spec)] [/R|/S] [/C] [/Q]
  376.          TRACE ON|OFF /N:<process name> [/R] [/S] [/C] [/Q]
  377.          TRACE ON|OFF /P:pid_spec [/R] [/S] [/C] [/Q]
  378.  
  379.  
  380.         ■  ON - The specified tracepoints are turned ON. This has a
  381.            cumulative effect and does not affect tracepoints that are
  382.            already on.
  383.  
  384.         ■  OFF - The listed tracepoints (All tracepoints if none are
  385.            listed) are being turned OFF.
  386.  
  387.         ■  major_code_spec - A tracepoint major code. The following major
  388.            code ranges have been defined.
  389.            -  0 - 244        Static and Dynamic trace for IBM use
  390.            -  245 - 255      Static and Dynamic for User use.
  391.            -  256 - 32767    Dynamic Trace for IBM use.
  392.            -  32768 - 65535  Dynamic Trace for User use.
  393.  
  394.         ■  minor_code_spec - A list of ranges of minor codes
  395.  
  396.            Note: More than one major_code_spec with minor_code_spec may be
  397.            specified.
  398.  
  399.         ■  module_spec - The module name for which an associated trace
  400.            definition file (TDF) exists.
  401.  
  402.            Note: The associated TDF assumes the same name as the module.
  403.            The TDF file is located by searching in the following order:
  404.            -  in the current directory
  405.            -  in DPATH
  406.            -  in \OS2\SYSTEM\TRACE
  407.            -  in \OS2\SYSTEM\TRACE\SYSTEM.TDF
  408.            -  in the load module directory
  409.            -  for base device drivers also in the root directory of the
  410.               boot drive.
  411.  
  412.            If the TDF specifies that the DLL is a fowarder DLL then the
  413.            forwarded DLL is searched for in the current directory and
  414.            LIBPATH if not already loaded.
  415.  
  416.         ■  event_type_spec - A list of minor code ranges, groups and types.
  417.  
  418.                If TRACE cannot find a module specified in module_spec then
  419.  
  420.         
  421.                                         System Trace (SysTrace) facility  5
  422.  
  423.                              July 9, 1998 - Warp Debug
  424.  
  425.                tdf_spec is assumed and TRACE searches directly for a TDF of
  426.                the name specified in the order specified above.  The module
  427.                name is then derived implicitly from the name specified
  428.                within the TDF.
  429.  
  430.                If KERNEL is specified then \OS2\SYSTEM\TRACE\OS2KRNL.TDF is
  431.                assumed with module OS2KRNL (or DOSCALLS.DLL).
  432.  
  433.            Note: More than one module_spec with event_type_spec may be
  434.            specified.
  435.  
  436.         ■  /N:<process name> - This will allow the user to control tracing
  437.            by the name of a module. More than one name can be entered as
  438.            long as they are separated by a comma. An example is
  439.            /N:name1,name2.
  440.  
  441.                This provides an alternate method of turning on Trace when
  442.                the PID is not known. This parameter is valid when turning
  443.                Trace ON or OFF but not valid if /P is also specified.
  444.  
  445.                NOTE: Verification of the name will follow the same method
  446.                as DosExecPgm. They are:
  447.  
  448.                1. If a path is specified, no search is performed. The name
  449.                   is registered even if it does not exist so that tracing
  450.                   will be started when the process is added to the system.
  451.                   Trace events will be logged only if the process exists
  452.                   when tracing is started.
  453.  
  454.                2. If a name is specified with an extension but no path, an
  455.                   attempt is made to find the process by searching the
  456.                   current directory. If not found in the current directory,
  457.                   the directories specified in the PATH statement (in
  458.                   config.sys) are searched.
  459.  
  460.                3. If a shortname is specified (no path, no extension), .exe
  461.                   is assumed as the extension and the method specified in
  462.                   method 2 is used.
  463.  
  464.         ■  /P:<pid_spec> - This allows the user to specify a PID number.
  465.            By default ALL pids are on.
  466.  
  467.         ■  /R - This resumes tracing if tracing was previously suspended.
  468.  
  469.         ■  /S - This suspends tracing.
  470.  
  471.         ■  /C - This clears the trace buffer.
  472.  
  473.         ■  /Q -  Returns the state of the Trace facility. Information will
  474.            be returned on all of the tracepoints and will include:
  475.  
  476.                Suspend command if the Trace facility is currently
  477.                suspended.
  478.  
  479.                Buffer Size
  480.  
  481.                Buffer collection mode (W or NW, Q or NQ, etc)
  482.  
  483.         
  484.                                         System Trace (SysTrace) facility  6
  485.  
  486.                              July 9, 1998 - Warp Debug
  487.  
  488.                Optional Data being captured
  489.  
  490.                PIDs being traced
  491.  
  492.                Tracepoints currently ON -  No group names will be
  493.                displayed; all tracepoints turned on as a result of using a
  494.                group name will be displayed.
  495.  
  496.            Note: /Q is valid with or without other keywords.
  497.  
  498.  
  499.  
  500.         Note: If "TRACE OFF" is used without any parameters ALL tracepoints
  501.         will be turned off.
  502.  
  503.  
  504.         The TRACE command provides additional flexibility of the previous
  505.         versions in the way it processes TDFs:
  506.  
  507.             TRACE OFF is now valid with a full tdf_spec or module_spec.
  508.             This allows individual and groups of tracepoints to be
  509.             selectively removed.
  510.  
  511.             TRACE no longer requires the TDF name to match the module name,
  512.             thus there is no longer a need to rename OS2KRNLD.TDF to
  513.             OS2KRNL.TDF when using the ALLSTRICT kernel. Tracepoints would
  514.             be activated by specifying TRACE ON OS2KRNLD
  515.  
  516.             The TRACE command will merge tracepoints with those already
  517.             activated when making repeated invocations that apply
  518.             tracepoints to the same load module. Thus in the case of
  519.             PMWIN.DLL, PMGRE.DLL and PMSHAPI.DLL, each of which is a
  520.             forwarder DLL and has its tracepoints located in PMMERGE.DLL,
  521.             their tracepoints may be applied cumulatively with three
  522.             invocations thus:
  523.                 TRACE ON PMWIN
  524.                 TRACE ON PMGRE
  525.                 TRACE ON PMSHAPI.
  526.  
  527.             Previous versions of the SYSTRACE facility did not permit this.
  528.  
  529.         For added serviceability: tracepoints definitions have been
  530.         provided for internal kernel interfaces. Each tracepoint records
  531.         32-bytes of stack on entry to the given routine. These definitions
  532.         are mainly intended for service personnel, however the following
  533.         may be of use to developers writing virtual device and file system
  534.         drivers:
  535.  
  536.             TRACE ON KRNLxFS(FSH) will trace File System Helper calls.
  537.             TRACE ON KRNLxVDM(VDH) will trace Virtual Device Helper calls.
  538.  
  539.             Note: In the above two commands "x" should be replaced with "R"
  540.             when using the RETAIL kernel, "B" when using the HSTRICT kernel
  541.             and "D" when using the ALLSTRICT kernel.
  542.  
  543.         Other kernel trace definitions provided are:
  544.  
  545.  
  546.         
  547.                                         System Trace (SysTrace) facility  7
  548.  
  549.                              July 9, 1998 - Warp Debug
  550.  
  551.            KRNLxTK:     Tasking and Scheduler   TK, SCH, VR, XCPT,
  552.                                                 SYSSERV, KM, SCI, SIG
  553.            KRNLxSEM:    Semaphore               SEM, KSEM, MUX, RAM, SYSSEM,
  554.            KRNLxPG:     Page Manager            PG
  555.            KRNLxSM:     Swapper Manager         SM
  556.            KRNLxVM:     Virtual Memory Manager  VM BMP RMP
  557.            KRNLxSEL:    Selector Manager        SEL
  558.            KRNLxTOM:    Timer Manager           TOM TIM
  559.            KRNLxLDR:    Loader                  LDR
  560.            KRNLxVDM:    Virtual Dos Machines    VDH EM86 DEM VDM VPM
  561.            KRNLxFS:     File System             FSH DIR EA FAT FCB FNotify
  562.                                                 FSD MFT SF VPB
  563.            KRNLxDEV:    Device and IO           DEV IO DRIVE DSK dh PSD
  564.            KERNEL:      Spin Lock APIs          LOCK (SMP Only)
  565.            DOSCALL1:    Spin Lock APIs          LOCK (SMP Only)
  566.            DOSCALL1:    Quecalls APIs           QUE
  567.            DOSCALL1:    Universal Thunks        UT
  568.                 *** Normally this should be turned off if tracing ALL APIs due to the
  569.                     large number of additional trace entries it will cause.
  570.                     So if you do:
  571.                         TRACE ON DOSCALL1
  572.                      you should also do:
  573.                         TRACE OFF DOSCALL1(UT).
  574.  
  575.         Each of these tracepoints in these TDFs have type specifications
  576.         as follows:
  577.  
  578.            PRE  - Entry point
  579.            POST - Exit point (currently not defined)
  580.            PRIV - Routines private to a component
  581.                   (name begins with a lower case character)
  582.            PUB  - Routines exported to other kernel components
  583.                   (name begins with an upper case character)
  584.  
  585.  
  586.         WARNING: Do not use DTI mode with any of the above KRNLxxxx
  587.         tracepoints on SMP systems that have 3 or more processors. This is
  588.         because there is an exposure to a 3-way deadlock arising from
  589.         tracepoints placed in ring 0 code that owns non-interruptable spin
  590.         locks.
  591.  
  592.         Note: In general when tracing system APIs it is recommended that
  593.         KERNEL and DOSCALL1 groups be specified together. This is because
  594.         for some APIs, processing is are split between DOSCALL1 and
  595.         OS2KRNL. Some information is traced at the DOSCALL1 interface and
  596.         the rest at the OS2KRNL interface.
  597.  
  598.         Similarly, TRACE ON DOSCSALL1(QUE) should be used with TRACE ON
  599.         QUECALLS to obtain complete information pertaining to QUECALLS API
  600.         tracing.
  601.  
  602.         New trace definitions have been added for exported interfaces to
  603.         the following modules:
  604.  
  605.  
  606.  
  607.  
  608.  
  609.         
  610.                                         System Trace (SysTrace) facility  8
  611.  
  612.                              July 9, 1998 - Warp Debug
  613.  
  614.            Module       Tracepoint Groups
  615.  
  616.            HPFS.IFS     -
  617.            CDFS.IFS     -
  618.            PMWP.DLL     WIN WP SHL NWI
  619.            PMVIOP.DLL   VDM WIN VIO
  620.            PMVDMP.DLL   VDM DOS
  621.  
  622.         Each of these tracepoints in these modules have type specifications
  623.         as follows:
  624.  
  625.            PRE  - Entry point
  626.            POST - Exit point (currently not defined)
  627.            PRIV - Routines private to a component
  628.                   (name begins with a lower case character)
  629.            PUB  - Routines exported to other kernel components
  630.                   (name begins with an upper case character)
  631.  
  632.  
  633.  
  634.         All System API tracepoints have been updated to include the
  635.         caller's return address. To facilitate this, all APIs that have a
  636.         thunking interface in DOSCALL1 have a corresponding tracepoint
  637.         defined their entry module to allow the caller's return address to
  638.         be recorded. This applies to QUECALLS, SESMGR and KERNEL.
  639.  
  640.         For example: 32-bit programs calling DosSleep enter DOSCALL1 at
  641.         DOS32SLEEP and then the KERNEL at DOSSLEEP, whereas 16-bit programs
  642.         calling DosSleep make a direct call to the Kernel at entry point
  643.         DOSSLEEP. The DOSSLEEP tracepoint in the Kernel records the
  644.         paramters and 16-bit return address. This should be used in
  645.         conjunction with the DOS32SLEEP tracepoint in DOSCALL1 to record
  646.         the return address to an original 32-bit caller.
  647.  
  648.         The Fast Safe RAMSEM APIs have been enhanced to record parameters
  649.         and details of the semphore.
  650.  
  651.         From Fix Pack 37, DOS32RAISEXCPETION will record parameters and
  652.         format the Exception Report Record.
  653.  
  654.         From Fix Pack 37, DOS32R3EXCEPTIONDISPATCHER,
  655.         DOS32EXCEPTIONCALLBACK and XCPTEXECUTEUSEREXCEPTIONHANDLER have
  656.         been added to DOSCALL1's EXMG tracepoint group. These record
  657.         Exception Context, Registration and Report Records during the
  658.         dispatching of user exception handler's.
  659.  
  660.         For a full list of the new API tracepoints to the KERNEL, DOSCALL1
  661.         and SESMGR, see Appendix A below.
  662.  
  663.  
  664.  
  665.         1.2.1.2 CONTROL OPTIONS
  666.  
  667.          TRACE [/R | /S] [/C] [/Q]
  668.  
  669.  
  670.  
  671.  
  672.         
  673.                                         System Trace (SysTrace) facility  9
  674.  
  675.                              July 9, 1998 - Warp Debug
  676.  
  677.         These options can be used with the ON parameter.  However, these
  678.         must follow all of the parameters of the ON parameter.
  679.  
  680.         ■  /R - This resumes tracing if tracing was previously suspended.
  681.  
  682.         ■  /S - This suspends tracing.
  683.  
  684.         ■  /C - This clears the trace buffer.
  685.  
  686.         ■  /Q -  Returns the state of the Trace facility. This is the same
  687.            as previously defined in the "TRACEPOINT CONTROL" section.
  688.  
  689.  
  690.  
  691.  
  692.         1.2.1.3 OPTIONAL DATA CONTROL
  693.  
  694.          TRACE ON | OFF [/D:<optional data>]
  695.  
  696.  
  697.         ■  ON - The specified optional data will be collected. This has a
  698.            cumulative effect.
  699.  
  700.         ■  OFF - The specified optional data will no longer be collected.
  701.  
  702.         ■  /D:<optional data> - This specifies what optional system data
  703.            will be captured.
  704.  
  705.                This is used with the ON  or OFF keywords and is valid only
  706.                when a buffer has been allocated.  This informational is
  707.                GLOBAL to the trace facility and not set on a per tracepoint
  708.                basis. Multiple entries are separated by a comma.
  709.  
  710.                Values and behavior will be the same as previously defined
  711.                in the TRACEBUF config.sys statement.
  712.  
  713.                The data will only be collected if available.
  714.  
  715.  
  716.  
  717.  
  718.         1.2.1.4 BUFFER CONTROL
  719.  
  720.          TRACE ON /B:<buffer size in KB> [/M:xxx] [/R | /S] [/D:<optional data>]
  721.          TRACE OFF /B
  722.  
  723.  
  724.         ■  ON - The buffer will be allocated using the specified options.
  725.  
  726.         ■  OFF - The buffer will be deallocated.
  727.  
  728.         ■  /B:[<buffer size>] - This sets the size of the buffer (in KB) if
  729.            used with the ON keyword and deallocates the buffer (no size
  730.            allowed) if used with the OFF keyword.
  731.  
  732.                When used with the ON keyword.
  733.  
  734.  
  735.         
  736.                                        System Trace (SysTrace) facility  10
  737.  
  738.                              July 9, 1998 - Warp Debug
  739.  
  740.                    The buffer size must be numeric.
  741.  
  742.                        Minimum Value = 1, Maximum value is unlimited (An
  743.                        error will be returned if the buffer can not be
  744.                        allocated. A value of 128 or less will cause a 128KB
  745.                        buffer to be allocated.
  746.  
  747.                        After the first 128KB, the size will be rounded up
  748.                        to the next multiple of 64KB so that the proper
  749.                        number of buffers can be created.
  750.  
  751.                When used with the OFF keyword.
  752.  
  753.                    No size is allowed. The parameter will be simply /B.
  754.                    When the buffer is deallocated the following happens:
  755.  
  756.                    The buffer is deallocated causing all data to be
  757.                    cleared.
  758.  
  759.  
  760.  
  761.         ■  /M:<mode> - This specifies the mode of the buffer and will be
  762.            accepted if a buffer is allocated. Values and behavior will be
  763.            the same as previously defined in the TRACEBUF config.sys
  764.            statement.
  765.  
  766.         ■  /R - This resumes tracing if tracing was previously suspended.
  767.  
  768.         ■  /S - This suspends tracing.
  769.  
  770.         ■  /D:<optional data> - This specifies what optional system data
  771.            will be captured.
  772.  
  773.                This is used with the ON  or OFF keywords and is valid only
  774.                when a buffer has been allocated.  This informational is
  775.                GLOBAL to the trace facility and not set on a per tracepoint
  776.                basis. Multiple entries are separated by a comma.
  777.  
  778.                Values and behavior will be the same as previously defined
  779.                in the TRACEBUF config.sys statement.
  780.  
  781.                The data will only be collected if available.
  782.  
  783.  
  784.         NOTE: The buffer options (/B:, /M:, and /D:) will be used until the
  785.         system is booted. If you want the options to be more permanent they
  786.         can be specified in the config.sys file (TRACEBUF statement).
  787.  
  788.  
  789.  
  790.         1.2.2 TRACE EXAMPLES
  791.  
  792.  
  793.         Allocate a wrapping 320KB trace buffer.
  794.  
  795.             TRACE ON /B:320 /M:W
  796.  
  797.  
  798.         
  799.                                        System Trace (SysTrace) facility  11
  800.  
  801.                              July 9, 1998 - Warp Debug
  802.  
  803.         Note: An error will be returned if the buffer is already allocated.
  804.  
  805.         Allocate a wrapping 320KB trace buffer using default values where
  806.         possible (Wrapping mode) and specify what optional data (shortname
  807.         and SS:ESP) to capture.
  808.  
  809.             TRACE ON /B:320 /D:PROCNAME,SSESP
  810.  
  811.         Allocate a wrapping 320KB trace buffer and put the Trace facility
  812.         in suspended mode. No tracing will be possible until the user puts
  813.         the trace facility in the resume mode.
  814.  
  815.             TRACE ON /B:320 /M:W /S
  816.  
  817.         Deallocate a previously allocated trace buffer.
  818.  
  819.             TRACE OFF /B
  820.  
  821.         Note: This command will not affect any optional system data or
  822.         tracepoints that have been previously defined. When the buffer is
  823.         next allocated (TRACE ON /B:xxx) the optional data and tracepoints
  824.         when again be active.
  825.  
  826.  
  827.         Change the optional system data that is being collected to be ALL
  828.         possible data.
  829.  
  830.             TRACE ON /D:ALL
  831.  
  832.         Change the optional system data that is being collected to NOT
  833.         collect the TID.
  834.  
  835.             TRACE OFF /D:TID
  836.  
  837.  
  838.         Enable for All available major codes. However, major code 1 is used
  839.         for performance testing and will only be enabled if a DEKKO card is
  840.         present in the hardware.
  841.  
  842.             Trace ON
  843.  
  844.         Enable for major code 13.
  845.  
  846.             Trace ON 13
  847.  
  848.         Enable for doscall1.
  849.  
  850.             Trace ON DOSCALL1
  851.  
  852.         Enable for processes (ffst and notes)
  853.  
  854.             TRACE ON /N:ffst,notes
  855.  
  856.  
  857.         The format for the command to stop tracing is the same as enabling
  858.         tracing except for the keyword. The keyword used to stop tracing is
  859.         OFF. The following command would stop tracing for major codes 6 and
  860.  
  861.         
  862.                                        System Trace (SysTrace) facility  12
  863.  
  864.                              July 9, 1998 - Warp Debug
  865.  
  866.         13.
  867.  
  868.             TRACE OFF 6,13
  869.  
  870.         Note: If TRACE OFF is used without any other parameters ALL
  871.         tracepoints will be turned OFF.
  872.  
  873.  
  874.         Suspend Tracing
  875.  
  876.             TRACE /S
  877.  
  878.         Resume Tracing
  879.  
  880.             TRACE /R
  881.  
  882.         Clear the Trace buffer. Tracing must be suspended or disabled for
  883.         this option to be valid.
  884.  
  885.             TRACE /C
  886.  
  887.         Query the Trace facility.
  888.  
  889.             TRACE /Q
  890.  
  891.         If the TRACE facility was ON (for major codes 3,4, and 5) with a
  892.         wrapping buffer of 256K this would return (all parameters will be
  893.         displayed even if they could have been defaulted) the following:
  894.  
  895.             TRACE ON /B:256 /M:W
  896.             TRACE ON 3,4,5
  897.  
  898.         The commands will be broken into a series of commands if the
  899.         command goes longer than 80 characters. The first command (no
  900.         longer than 80 characters) will have buffer information and
  901.         tracepoints that are ON while the rest of the commands will only
  902.         have tracepoints. EXAMPLE: If tracepoints 4-30 are on with a 512KB
  903.         non-wrapping buffer the data returned would be:
  904.  
  905.             TRACE ON /B:512 /M:NW
  906.             TRACE ON 4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22
  907.             TRACE ON 23,24,25,26,27,28,29,30
  908.  
  909.         NOTE: If you turn on tracepoints using GROUP names the QUERY will
  910.         return everything that was turned on (not the group name).
  911.  
  912.  
  913.  
  914.         1.2.3 TRACEFMT
  915.  
  916.         The Tracefmt command starts the trace formatter which provides a
  917.         user interface to the trace buffer. It has been enhanced to:
  918.  
  919.         ■  Display the System Optional Data
  920.  
  921.         ■  The Processor ID (CPU ID) has been added to the Select...
  922.            (Search) function (under VIEW action bar item) so that only the
  923.  
  924.         
  925.                                        System Trace (SysTrace) facility  13
  926.  
  927.                              July 9, 1998 - Warp Debug
  928.  
  929.            records for a single Processor can be displayed.
  930.  
  931.         ■  An option has been added to allow unformatted data to be
  932.            displayed in dump format (Hex and ASCII). This new option
  933.            "Display in Dump Format" is under the VIEW action bar item. It
  934.            will toggle on and off the same as the other display options.
  935.            This will not affect data that is subject to a formatting
  936.            control (except for %U).
  937.  
  938.         ■  The default display type has been changed to the new Dump
  939.            format. This will be used for data if formatting instructions
  940.            have not been provided.
  941.  
  942.         ■  There is a new command line switch (/f=output_file_name) that
  943.            allows the formatted output to be directed directly to an output
  944.            file.  When /f is specified TRACEFMT will close as soon as the
  945.            input trace data has been formatted and written to the output
  946.            file.  The full syntax for the TRACEFMT command is:
  947.  
  948.            TRACEFMT <input> </t=tff_path> </f=output>
  949.  
  950.  
  951.            where:
  952.  
  953.                   <input> specified either a RAW trace buffer (from TRACEGET or
  954.                           TRSPOOL) or an unformatted trace file saved by TRACEFMT.
  955.  
  956.                   </t=tff_path> specifies the TFF path name. This defaults to
  957.                           \OS2\SYSTEM\TRACE
  958.  
  959.                   <f=output> specifies the output formatted file name.
  960.  
  961.  
  962.  
  963.  
  964.         1.2.4 TRACEGET
  965.  
  966.  
  967.         The TRACEGET command will extract the System Trace buffer and
  968.         save it in a file. The command syntax is :
  969.  
  970.         TRACEGET file
  971.  
  972.  
  973.  
  974.         where:
  975.  
  976.         file    - The name of the file where the buffer will be written.
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.         
  988.                                        System Trace (SysTrace) facility  14
  989.  
  990.                              July 9, 1998 - Warp Debug
  991.  
  992.         1.2.5 TRSPOOL
  993.  
  994.  
  995.         TRSPOOL extends the usefulness of the OS/2 system trace facility
  996.         by capturing the system trace buffer and spooling it to a
  997.         cyclically used sequence of disk files (named TRACEBUF.nnn,
  998.         where nnn is a sequential number starting with 000).  The
  999.         captured trace disk files may be later formatted using TRACEFMT,
  1000.         by selecting the Open option of the File menu.
  1001.  
  1002.         For information about this utility please see the file
  1003.         TRSPOOL.DOC in the OS2\SYSTEM directory.
  1004.  
  1005.  
  1006.  
  1007.         1.2.6 DTRACE
  1008.  
  1009.         DTRACE is a utility that allows an experienced user to define
  1010.         dynamic tracepoints where tracepoints were not previously
  1011.         located.
  1012.  
  1013.         For information about this utility please see the file
  1014.         DTRACE.DOC in the OS2\SYSTEM directory.
  1015.  
  1016.  
  1017.  
  1018.         1.2.7 MAPTSF
  1019.  
  1020.         This utility will generate a TSF from a MAP file. One tracepoint is
  1021.         generated for each public code symbol. Optionally a return tracepoint
  1022.         may be generated for each public code symbol.
  1023.         The syntax is:
  1024.  
  1025.                  MAPTSF map_file [/MAJOR=major_code]
  1026.                                  [/MODNAME=name]
  1027.                                  [/MAXDATALENGTH=max_data_length]
  1028.                                  [/MINORSTART=minor_code]
  1029.                                  [/TEMPLATE=template_file]
  1030.                                  [/LOGSTACK=stack_bytes]
  1031.                                  [/EXCLUDE=string[*][,....]]
  1032.                                  [/INCLUDE=string[*][,....]]
  1033.                                  [/REGISTERS=reg[,reg]...]
  1034.                                  [/LOGRETURN]
  1035.                                  [/RETEP]
  1036.                                  [/CASESENSITIVE]
  1037.                                  [/TYPES]
  1038.                                  [/GROUPS=string[,.....]]
  1039.  
  1040.  
  1041.          The parameters are:
  1042.  
  1043.         ■  map_file (only REQUIRED parameter)
  1044.  
  1045.         ■  /MAJOR
  1046.  
  1047.                Specifies the major code to be used in the MAJOR= statement of the TSF.
  1048.                If omitted, TRCUST will select the default major code of 1 when compiling the TSF.
  1049.  
  1050.         
  1051.                                        System Trace (SysTrace) facility  15
  1052.  
  1053.                              July 9, 1998 - Warp Debug
  1054.  
  1055.         ■  /MODNAME
  1056.  
  1057.                Specifies the module name to be used in the MODNAME= statement of the TSF.
  1058.                If omitted, MAPTSF will use the module name that appears in the second line of
  1059.                the MAP file.
  1060.  
  1061.                Note: The MAP file excludes the module extension. TRCUST will assume an
  1062.                extension of DLL if not specified.
  1063.  
  1064.         ■  /MAXDATALENGTH
  1065.  
  1066.                Specifies the MAXDATALENGTH= statement of the TSF. If omitted, TRCUST will
  1067.                assume the default of 512 when compiling the TSF.
  1068.  
  1069.         ■  /MINORSTART
  1070.  
  1071.                Specifies the first minor code. Subsequent tracepoints have incremental minor
  1072.                codes. If omitted, the MINOR= statement is not generated. TRCUST will assume
  1073.                an initial minor code of 1 and increment for each tracepoint.
  1074.  
  1075.         ■  /INCLUDE
  1076.  
  1077.                Specifies a comma delimited list of case insensitive strings used as inclusion
  1078.                criteria for public symbols. An optional trailing * signifies a generic match. If
  1079.                both /INCLUDE and /EXCLUDE are specified then the logical OR of their criteria is
  1080.                used for selection.
  1081.  
  1082.                For example:
  1083.  
  1084.                    /INCLUDE=dos*,strupr
  1085.  
  1086.                        Inludes all public symbols beginning 'dos' or equal to 'strupr'.
  1087.  
  1088.                    /EXCLUDE=s* /INCLUDE=strupr
  1089.  
  1090.                        Excludes all public symbols beginning 's' except for 'strupr' and includes everything else.
  1091.  
  1092.         ■  /EXCLUDE
  1093.  
  1094.                Specifies a comma delimited list of case insensitive strings used as exclusion criteria for
  1095.                public symbols. An optional trailing * signifies a generic match. If both /INCLUDE and
  1096.                /EXCLUDE are specified then the logical OR of their criteria is used for selection.
  1097.                See the examples under /INCLUDE.
  1098.  
  1099.         ■  /CASESENSITIVE
  1100.  
  1101.                Switch that applies to /INCLUDE and /EXCLUDE. If specified then the include and
  1102.                exclude strings will be match on a case-sensitve basis.
  1103.  
  1104.         ■  /LOGSTACK=n
  1105.  
  1106.                Specifies the number of bytes of stack to log for entry tracepoints. This
  1107.                causes the following TSF statements to be generated for each entry tracepoint:
  1108.  
  1109.                    for 16-bit code:
  1110.  
  1111.  
  1112.  
  1113.         
  1114.                                        System Trace (SysTrace) facility  16
  1115.  
  1116.                              July 9, 1998 - Warp Debug
  1117.  
  1118.                 REGS=(SP,SS),
  1119.                 FMT="Stack pointer SS:SP=%A->",
  1120.                 MEM=(RSS+SP,D,n),
  1121.                 FMT="1W"
  1122.  
  1123.  
  1124.                    for 32-bit code:
  1125.  
  1126.                 REGS=(ESP),
  1127.                 FMT="Stack pointer ESP=%F->",
  1128.                 MEM32=(FESP,D,n)
  1129.                 FMT="1F"
  1130.  
  1131.  
  1132.  
  1133.            If /LOGSTACK is specified without a value then 16 bytes is assumed.
  1134.  
  1135.         ■  /LOGRETURN
  1136.  
  1137.                Specifies that for each return tracepoint, the return value in AX/EAX should be
  1138.                logged. This causes the following TSF statements to be generated:
  1139.  
  1140.                    for 16-bit code:
  1141.  
  1142.                 REGS=(AX)
  1143.                 FMT="Returns (ax) %W"
  1144.  
  1145.  
  1146.                    for 32-bit code:
  1147.  
  1148.                 REGS=(EAX)
  1149.                 FMT="Returns (eax) %F"
  1150.  
  1151.  
  1152.         ■  /REGISTERS or /REGS
  1153.  
  1154.                Specifies one or more processor registers to be logged, each separated by a
  1155.                comma. The following register mnemonics are supported:
  1156.  
  1157.                 AX,BX,CX,DX,CS,DS,ES,FS,GS,IP,SI,DI,SP,BP,FLAGS,
  1158.                 EAX,EBX,ECX,EDX,EIP,ESI,EDI,ESP,EBP,EFLAGS
  1159.  
  1160.  
  1161.  
  1162.         ■  /RETEP
  1163.  
  1164.                Specifies that for each public entry-point in the MAP file, a return tracepoint
  1165.                should be generated using the RETEP parameter on the TRACE statement in the TSF.
  1166.  
  1167.                Note: RETEP is only processed by TRCUST if the module has debugging information
  1168.                present. If this is not the case then TRCUST (2.20) will ignore the RETEP
  1169.                parameter and a warning message will be issued for the associated tracepoint.
  1170.  
  1171.         ■  /TYPES
  1172.  
  1173.                pre-defined types:
  1174.  
  1175.  
  1176.         
  1177.                                        System Trace (SysTrace) facility  17
  1178.  
  1179.                              July 9, 1998 - Warp Debug
  1180.  
  1181.                    PUB  = Public routines - names the begin upper case (ignoring leading underscores)
  1182.  
  1183.                    PRIV = Private routines - names the begin lower case (ignoring leading underscores)
  1184.  
  1185.                    PRE  = Entry tracepoint.
  1186.  
  1187.                    POST = Exit tracepoint.
  1188.  
  1189.         ■  /GROUPT
  1190.  
  1191.                Requests that each of the strings listed be used to define a group. Tracepoints
  1192.                are assigned to a group according to whether a group name matches the beginning
  1193.                of the tracepoint name, ignoring case and leading underscore characters
  1194.  
  1195.         ■  /TEMPLATE
  1196.  
  1197.                Specifies a file where up to four template tracepoint definitions may be
  1198.                specified, one for each of the following categories:
  1199.                    16-bit entry points
  1200.                    16-bit return points
  1201.                    32-bit entry points
  1202.                    32-bit return points
  1203.  
  1204.                The definitions are in a shortened form of the TRCUST TRACE statement syntax.
  1205.                They are appended to each tracepoint of the category to which they apply. All
  1206.                parameters other than MINOR and DESC are permissible. TP and RETEP are
  1207.                specified as follows:
  1208.                    TP=@16           signifies a 16-bit entry-point
  1209.                    TP=@16,RETEP     signifies a 16-bit return-point
  1210.                    TP=@32           signifies a 32-bit entry-point
  1211.                    TP=@32,RETEP     signifies a 32-bit return-point
  1212.  
  1213.                Only TP and RETEP may appear on the same line as the TRACE keyword.
  1214.                For example:
  1215.  
  1216.                 TRACE TP=@16
  1217.                       MEM=(SS:BP+8,I,0x10)
  1218.                       FMT="16-bytes of parameter 1: 1W"
  1219.  
  1220.  
  1221.                will append:
  1222.  
  1223.                       MEM=(SS:BP+8,I,0x10)
  1224.                       FMT="16-bytes of parameter 1: 1W"
  1225.  
  1226.  
  1227.                to every 16-bit entry tracepoint definition.
  1228.  
  1229.  
  1230.  
  1231.  
  1232.         1.2.8 SYSSPLIT
  1233.  
  1234.  
  1235.         If the system trace definitions for a particular module needs to be
  1236.         replaced or modified then SYSSPLIT may be used to split SYSTEM.TDF
  1237.         into its constituent TDF files. The resultant *.TDF files may be saved
  1238.  
  1239.         
  1240.                                        System Trace (SysTrace) facility  18
  1241.  
  1242.                              July 9, 1998 - Warp Debug
  1243.  
  1244.         in OS2\SYSTEM\TRACE. Because of the search order employed by TRACE.EXE
  1245.         it is recommended that SYSTEM.TDF be renamed after being split.
  1246.  
  1247.         When applying tracepionts to a DLL, TRACE.EXE will search the current path,
  1248.         then the DPATH for the dll_name.TDF file. If not found it searches
  1249.         OS2\SYSTEM\TRACE\SYSTEM.TDF and finally, OS2\SYSTEM\TRACE\dll_name.TDF.
  1250.  
  1251.         The file names of the split *.TDFs will be chosen to be the original
  1252.         names used to create SYSTEM.TDF.
  1253.  
  1254.         The syntax of the command is:
  1255.  
  1256.         SYSSPLIT <input_file>
  1257.  
  1258.  
  1259.             <input_file> is the system trace definition files - SYSTEM.TDF
  1260.  
  1261.  
  1262.         Note: The Trace definitions for the OS2KRNL may be in OS2KRNL.TDF or
  1263.         DOSCALLS.TDF. The TRACE command recognizes the keyword KERNEL as an
  1264.         alias for each of the kernel TDF names. TRACE.EXE searches the DPATH
  1265.         for DOSCALLS.TDF. Currently, TRACE ON KERNEL will only work
  1266.         for OS2KRNL.TDF if a directory from the boot drive is current.
  1267.  
  1268.  
  1269.         The TDFLST utility may be used with each of the resultant TDFs to
  1270.         format the trace point definitions.
  1271.  
  1272.  
  1273.  
  1274.  
  1275.         1.2.8.1 Trace formatting files - SYSTEM.TFF
  1276.  
  1277.  
  1278.         When formatting the system trace buffer, TRACEFMT.EXE will search
  1279.         OS2\SYSTEM\TRACE\SYSTEM.TFF for the formatting templates for each
  1280.         major code encountered in the trace buffer. If a major code is not
  1281.         found in SYSTEM.TFF then TRACEFMT will search for a file named
  1282.         TRC00xx.TFF, where xx is the major code number in hexadecimal.
  1283.  
  1284.         If the formatting templates for a particular module needs to be
  1285.         replaced or modified then SYSSPLIT may be used to split SYSTEM.TFF
  1286.         into its constituent TFF files. The resultant *.TFF files may be saved
  1287.         in OS2\SYSTEM\TRACE. Because of the search order employed by
  1288.         TRACEFMT.EXE it is recommended that SYSTEM.TFF be renamed after being
  1289.         split.
  1290.  
  1291.         The file names of the split *.TFFs will be chosen to be the original
  1292.         names used to create SYSTEM.TDF, that is names formed from their major
  1293.         codes.
  1294.  
  1295.         The TFFLST utility may be used with each of the resultant TFFs to
  1296.         format the trace point definitions.
  1297.  
  1298.         Note: TRCUST has the ability to combine TFFs for the same major code.
  1299.         This is not to be confused with the special SYSTEM.TFF and SYSTEM.TDF
  1300.         files that are concatenations of dissimilar major code definitions.
  1301.  
  1302.         
  1303.                                        System Trace (SysTrace) facility  19
  1304.  
  1305.                              July 9, 1998 - Warp Debug
  1306.  
  1307.  
  1308.  
  1309.  
  1310.         1.2.9 TDFLST
  1311.  
  1312.  
  1313.         TDF list formats a TDF as DTRACE compatible trace program file. The
  1314.         output is directed to STDOUT, which may be captured in a file using
  1315.         the redirection operator (>).
  1316.  
  1317.         Trace definitions may be modified or supplemented using an editor and
  1318.         the TDF rebuilt using DTRACE BUILDTDF.
  1319.  
  1320.         The syntax is:
  1321.  
  1322.         TDFLST <tdf_file>
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.         1.2.10 TFFLST
  1330.  
  1331.  
  1332.         TFF list formats a TFF as TRCUST compatible source. The
  1333.         output is directed to STDOUT, which may be captured in a file using
  1334.         the redirection operator (>).
  1335.  
  1336.         Trace formatting templates may be modified or supplemented using
  1337.         an editor and the TFF rebuilt using TRCUST.
  1338.  
  1339.         NOTES:
  1340.  
  1341.             TRCUST is used for generating TDFs and TFFs. The keyword,
  1342.             TP=@STATIC directs TRCUST solely to generate TFFs. Normally this is
  1343.             used with static trace but equally valid for dynamic trace where the
  1344.             tracepoints have already been defined.
  1345.  
  1346.             Large TDF and TFF files may take a few minutes to list.  A
  1347.             degree of searching and cross-referencing has to take place before the
  1348.             listing is produced.  Consequently there may be a considerable pause
  1349.             before the listing is produced.
  1350.  
  1351.  
  1352.         The syntax is:
  1353.  
  1354.         TFFLST <tdf_file>
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.         
  1366.                                        System Trace (SysTrace) facility  20
  1367.  
  1368.                              July 9, 1998 - Warp Debug
  1369.  
  1370.         1.3 APPENDIX A NEW TRACEPOINTS CROSS-REFERENCE.
  1371.  
  1372.  
  1373.         Those tracepoints flagged with an "*" are full tracepoints and record parameters
  1374.         as well as return address. Those not flagged only record the caller's return
  1375.         address and have to be used with their corresponding system tracepoint to record
  1376.         parameter information.
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.         
  1429.                                        System Trace (SysTrace) facility  21
  1430.  
  1431.                              July 9, 1998 - Warp Debug
  1432.  
  1433.         New "TRACE ON KERNEL" Tracepoints
  1434.  
  1435.         Tracepoint                        Minor Group Types    F  Remarks
  1436.         DOS32CANCELLOCKREQUEST            494   FS    PRE,API  *
  1437.         DOS32CANCELLOCKREQUEST            495   FS    POST,API *
  1438.         DOS32SETFILELOCKS                 496   FS    PRE,API  *
  1439.         DOS32SETFILELOCKS                 497   FS    POST,API *
  1440.         DOS32PROTECTSETFILELOCKS          498   FS    PRE,API  *
  1441.         DOS32PROTECTSETFILELOCKS          499   FS    POST,API *
  1442.         DOSCREATESPINLOCK                 500   LOCK  PRE,API  *  SMP only
  1443.         DOSCREATESPINLOCK                 501   LOCK  POST,API *  SMP only
  1444.         DOSACQUIRESPINLOCK                502   LOCK  PRE,API  *  SMP only
  1445.         DOSACQUIRESPINLOCK                503   LOCK  POST,API *  SMP only
  1446.         DOSRELEASESPINLOCK                504   LOCK  PRE,API  *  SMP only
  1447.         DOSRELEASESPINLOCK                505   LOCK  POST,API *  SMP only
  1448.         DOSFREESPINLOCK                   506   LOCK  PRE,API  *  SMP only
  1449.         DOSFREESPINLOCK                   507   LOCK  POST,API *  SMP only
  1450.         DOS32IPROTECTREAD                 508   FS    PRE,API  *
  1451.         DOS32IPROTECTREAD                 509   FS    POST,API *
  1452.         DOS32IPROTECTWRITE                510   FS    PRE,API  *
  1453.         DOS32IPROTECTRWITE                511   FS    POST,API *
  1454.  
  1455.  
  1456.         New "TRACE ON DOSCALL1" Tracepoints
  1457.  
  1458.         Tracepoint                        Minor Group Types    F  Remarks
  1459.         DOS32WAITCHILD                    262   TK    PRE,API     32-bit EP to KERNEL API
  1460.         DOS32BEEP                         263   IO    PRE,API     32-bit EP to KERNEL API
  1461.         DOS32PHYSICALDISK                 264   FS    PRE,API     32-bit EP to KERNEL API
  1462.         DOS32SETCP                        265   TK    PRE,API     32-bit EP to KERNEL API
  1463.         DOS32SETPROCESSCP                 266   TK    PRE,API     32-bit EP to KERNEL API
  1464.         DOS32SLEEP                        267   TK    PRE,API     32-bit EP to KERNEL API
  1465.         DOS32DEVCONFIG                    268   FS    PRE,API     32-bit EP to KERNEL API
  1466.         DOS32GETDATETIME                  269   FS    PRE,API     32-bit EP to KERNEL API
  1467.         DOS32SETDATETIME                  270   TIM   PRE,API     32-bit EP to KERNEL API
  1468.         DOS32EXECPGM                      271   TIM   PRE,API     32-bit EP to KERNEL API
  1469.         DOS32ENTERCRITSEC                 272   TK    PRE,API     32-bit EP to KERNEL API
  1470.         DOS32EXITCRITSEC                  273   TK    PRE,API     32-bit EP to KERNEL API
  1471.         DOS32EXIT                         274   TK    PRE,API     32-bit EP to KERNEL API
  1472.         DOS32KILLPROCESS                  275   TK    PRE,API     32-bit EP to KERNEL API
  1473.         DOS32SETPRIORITY                  276   TK    PRE,API     32-bit EP to KERNEL API
  1474.         DOS32RESUMETHREAD                 277   TK    PRE,API     32-bit EP to KERNEL API
  1475.         DOS32SUSPENDTHREAD                278   TK    PRE,API     32-bit EP to KERNEL API
  1476.         DOS32CREATEPIPE                   279   PIP   PRE,API     32-bit EP to KERNEL API
  1477.         DOS32CREATEQUEUE                  280   QUE   PRE,API     32-bit EP to QUECALLS API
  1478.         DOS32OPENQUEUE                    281   QUE   PRE,API     32-bit EP to QUECALLS API
  1479.         DOS32CLOSEQUEUE                   282   QUE   PRE,API     32-bit EP to QUECALLS API
  1480.         DOS32PEEKQUEUE                    283   QUE   PRE,API     32-bit EP to QUECALLS API
  1481.         DOS32PURGEQUEUE                   284   QUE   PRE,API     32-bit EP to QUECALLS API
  1482.         DOS32QUERYQUEUE                   285   QUE   PRE,API     32-bit EP to QUECALLS API
  1483.         DOS32WRITEQUEUE                   286   QUE   PRE,API     32-bit EP to QUECALLS API
  1484.         DOS32CALLNPIPE                    287   PIP   PRE,API     32-bit EP to KERNEL API
  1485.         DOS32CONNECTNPIPE                 288   PIP   PRE,API     32-bit EP to KERNEL API
  1486.         DOS32DISCONNECTNPIPE              289   PIP   PRE,API     32-bit EP to KERNEL API
  1487.         DOS32CREATENPIPE                  290   PIP   PRE,API     32-bit EP to KERNEL API
  1488.         DOS32PEEKNPIPE                    291   PIP   PRE,API     32-bit EP to KERNEL API
  1489.         DOS32QUERYNPHSTATE                292   PIP   PRE,API     32-bit EP to KERNEL API
  1490.  
  1491.         
  1492.                                        System Trace (SysTrace) facility  22
  1493.  
  1494.                              July 9, 1998 - Warp Debug
  1495.  
  1496.         DOS32RAWREADNPIPE                 293   PIP   PRE,API     32-bit EP to KERNEL API
  1497.         DOS32RAWWRITENPIPE                294   PIP   PRE,API     32-bit EP to KERNEL API
  1498.         DOS32QUERYNPIPEINFO               295   PIP   PRE,API     32-bit EP to KERNEL API
  1499.         DOS32QUERYNPIPESEMSTATE           296   PIP   PRE,API     32-bit EP to KERNEL API
  1500.         DOS32SETNPHSTATE                  297   PIP   PRE,API     32-bit EP to KERNEL API
  1501.         DOS32SETNPIPESEM                  298   PIP   PRE,API     32-bit EP to KERNEL API
  1502.         DOS32TRANSACTNPIPE                299   PIP   PRE,API     32-bit EP to KERNEL API
  1503.         DOS32WAITNPIPE                    300   PIP   PRE,API     32-bit EP to KERNEL API
  1504.         DOS32RESETBUFFER                  301   FS    PRE,API     32-bit EP to KERNEL API
  1505.         DOS32SETCURRENTDIR                302   FS    PRE,API     32-bit EP to KERNEL API
  1506.         DOS32SETFILEPTR                   303   FS    PRE,API     32-bit EP to KERNEL API
  1507.         DOS32PROTECTSETFILEPTR            304   FS    PRE,API     32-bit EP to KERNEL API
  1508.         DOS32CLOSE                        305   FS    PRE,API     32-bit EP to KERNEL API
  1509.         DOS32PROTECTCLOSE                 306   FS    PRE,API     32-bit EP to KERNEL API
  1510.         DOS32COPY                         307   FS    PRE,API     32-bit EP to KERNEL API
  1511.         DOS32DELETE                       308   FS    PRE,API     32-bit EP to KERNEL API
  1512.         DOS32FORCEDELETE                  309   FS    PRE,API     32-bit EP to KERNEL API
  1513.         DOS32DEVIOCTL                     310   FS    PRE,API     32-bit EP to KERNEL API
  1514.         DOS32DUPHANDLE                    311   FS    PRE,API     32-bit EP to KERNEL API
  1515.         DOS32EDITNAME                     312   FS    PRE,API     32-bit EP to KERNEL API
  1516.         DOS32FINDCLOSE                    313   FS    PRE,API     32-bit EP to KERNEL API
  1517.         DOS32FSATTACH                     314   FS    PRE,API     32-bit EP to KERNEL API
  1518.         DOS32FSCTL                        315   FS    PRE,API     32-bit EP to KERNEL API
  1519.         DOS32MOVE                         316   FS    PRE,API     32-bit EP to KERNEL API
  1520.         DOS32SETFILESIZE                  317   FS    PRE,API     32-bit EP to KERNEL API
  1521.         DOS32PROTECTSETFILESIZE           318   FS    PRE,API     32-bit EP to KERNEL API
  1522.         DOS32QUERYCURRENTDIR              319   FS    PRE,API     32-bit EP to KERNEL API
  1523.         DOS32QUERYCURRENTDISK             320   FS    PRE,API     32-bit EP to KERNEL API
  1524.         DOS32QUERYFHSTATE                 321   FS    PRE,API     32-bit EP to KERNEL API
  1525.         DOS32PROTECTQUERYFHSTATE          322   FS    PRE,API     32-bit EP to KERNEL API
  1526.         DOS32PQUERYFSATTACH               323   FS    PRE,API     32-bit EP to KERNEL API
  1527.         DOS32QUERYFSINFO                  324   FS    PRE,API     32-bit EP to KERNEL API
  1528.         DOS32QUERYHTYPE                   325   FS    PRE,API     32-bit EP to KERNEL API
  1529.         DOS32QUERYVERIFY                  326   FS    PRE,API     32-bit EP to KERNEL API
  1530.         DOS32DELETEDIR                    327   FS    PRE,API     32-bit EP to KERNEL API
  1531.         DOS32SEARCHPATH                   328   FS    PRE,API     32-bit EP to KERNEL API
  1532.         DOS32SETDEFAULTDISK               329   FS    PRE,API     32-bit EP to KERNEL API
  1533.         DOS32SETFHSTATE                   330   FS    PRE,API     32-bit EP to KERNEL API
  1534.         DOS32PROTECTSETFHSTATE            331   FS    PRE,API     32-bit EP to KERNEL API
  1535.         DOS32SETFSINFO                    332   FS    PRE,API     32-bit EP to KERNEL API
  1536.         DOS32SETMAXFH                     333   FS    PRE,API     32-bit EP to KERNEL API
  1537.         DOS32SETRELMAXFH                  334   FS    PRE,API     32-bit EP to KERNEL API
  1538.         DOS32SETVERIFY                    335   FS    PRE,API     32-bit EP to KERNEL API
  1539.         DOS32ERRCLASS                     336   FS    PRE,API     32-bit EP to KERNEL API
  1540.         DOS32ERROR                        337   TK    PRE,API     32-bit EP to KERNEL API
  1541.         DOS32LOADMODULE                   338   LDR   PRE,API     32-bit EP to KERNEL API
  1542.         DOS32FREEMODULE                   339   LDR   PRE,API     32-bit EP to KERNEL API
  1543.         DOS32QUERYMODULEHANDLE            340   LDR   PRE,API     32-bit EP to KERNEL API
  1544.         DOS32QUERYMODULENAME              341   LDR   PRE,API     32-bit EP to KERNEL API
  1545.         DOS32QUERYAPPTYPE                 342   LDR   PRE,API     32-bit EP to KERNEL API
  1546.         DOS32PFINDNEXT                    343   FS    PRE,API     32-bit EP to KERNEL API
  1547.         DOS32SHUTDOWN                     344   FS    PRE,API     32-bit EP to KERNEL API
  1548.         DOS32OPENCHANGENOTIFY             345   FS    PRE,API     32-bit EP to KERNEL API
  1549.         DOS32RESETCHANGENOTIFY            346   FS    PRE,API     32-bit EP to KERNEL API
  1550.         DOS32CLOSECHANGENOTIFY            347   FS    PRE,API     32-bit EP to KERNEL API
  1551.         DOS32CREATESPINLOCK               348   LOCK  PRE,API     SMP only, 32-bit EP to KERNEL API
  1552.         DOS32ACQUIRESPINLOCK              349   LOCK  PRE,API     SMP only, 32-bit EP to KERNEL API
  1553.  
  1554.         
  1555.                                        System Trace (SysTrace) facility  23
  1556.  
  1557.                              July 9, 1998 - Warp Debug
  1558.  
  1559.         DOS32RELEASESPINLOCK              350   LOCK  PRE,API     SMP only, 32-bit EP to KERNEL API
  1560.         DOS32FREESPINLOCK                 351   LOCK  PRE,API     SMP only, 32-bit EP to KERNEL API
  1561.         DOS32READQUEUE                    352   QUE   PRE,API     32-bit EP to QUECALLS API
  1562.         DOS16CREATEQUEUE                  353   QUE   PRE,API     16-bit EP to QUECALLS API
  1563.         DOS16OPENQUEUE                    354   QUE   PRE,API     16-bit EP to QUECALLS API
  1564.         DOS16CLOSEQUEUE                   355   QUE   PRE,API     16-bit EP to QUECALLS API
  1565.         DOS16PEEKQUEUE                    356   QUE   PRE,API     16-bit EP to QUECALLS API
  1566.         DOS16PURGEQUEUE                   357   QUE   PRE,API     16-bit EP to QUECALLS API
  1567.         DOS16QUERYQUEUE                   358   QUE   PRE,API     16-bit EP to QUECALLS API
  1568.         DOS16WRITEQUEUE                   359   QUE   PRE,API     16-bit EP to QUECALLS API
  1569.         DOS16READQUEUE                    360   QUE   PRE,API     16-bit EP to QUECALLS API
  1570.         DOS32R3EXCEPTIONDISPATCHER        361   EXMG  PRE,API  *  From FP37, Internal DOSCALL1 tracepoint
  1571.         DOS32EXCEPTIONCALLBACK            362   EXMG  PRE,API  *  From FP37, Internal DOSCALL1 tracepoint
  1572.         XCPTEXECUTEUSEREXCEPTIONHANDLER   363   EXMG  PRE,API  *  From FP37, Internal DOSCALL1 tracepoint
  1573.         UT16RETURN                        33028 UT    POST,INT    Internal DOSCALL1 tracepoint
  1574.         UT32RETURN                        33029 UT    POST,INT    Internal DOSCALL1 tracepoint
  1575.  
  1576.  
  1577.         New "TRACE ON SESMGR" Tracepoints
  1578.  
  1579.         Tracepoint                        Minor Group Types    F  Remarks
  1580.         DOS32SELECTSESSION                32          PRE,API     32-bit EP to SESMGR API
  1581.         DOS32SETSESSION                   33          PRE,API     32-bit EP to SESMGR API
  1582.         DOS32STARTSESSION                 34          PRE,API     32-bit EP to SESMGR API
  1583.         DOS32STOPSESSION                  35          PRE,API     32-bit EP to SESMGR API
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.  
  1594.  
  1595.  
  1596.  
  1597.  
  1598.  
  1599.  
  1600.  
  1601.  
  1602.  
  1603.  
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.         
  1618.