home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / trcust.zip / trcustuse.txt < prev   
Text File  |  2002-06-22  |  8KB  |  208 lines
  1. TRCUST
  2. ------
  3.  
  4. The base version of TRCUST shipped with the Warp 3.0 and 4.0 ToolKits is 2.0.
  5.  
  6. TRCUST 3.05 provides the following enhancements and fixes since version 2.0:
  7.  
  8. Regression for NE modules, which may result in a TRAP D but also
  9. results in an invalid TDF being generated.
  10.  
  11. MODNAME is not required for Static Tracepoints.
  12.  
  13. Supports MAXDATALEN may be specified upto 4099. Note, MAXDATALEN above 512
  14. is permissible only on Warp 3.0 Fix Pack 35 and higher.
  15.  
  16. MAXDATALEN defaults to 512
  17.  
  18. Allows formatting controls to be specified in lower case.
  19.  
  20. Supports Major codes up to 0xffff.  Note, MAJOR code above 255 are
  21. permissible only on Warp 3.0 Fix Pack 35 and higher.
  22.  
  23. Fixed problems with keyword order on the TRACE statement.
  24.  
  25. Allows the %C formatting control to specify an ASCII character interpretation of
  26. a byte of trace data.
  27.  
  28. Allows the /NODE switch to bypass module debug information processing.
  29.  
  30. RETEP has been extended to work with MAP files and HLL version 4
  31. style debugging information.
  32.  
  33. Case insensitive references to MAP file symbols is allowed.
  34.  
  35. Line number support for HLL 4 (VisualAge C++)
  36.  
  37. All TSF keywords are case insensitive.
  38.  
  39. All TRCUST parameters are case insensitive.
  40.  
  41. TSF TRACE statement keywords are now order independent.
  42.  
  43. /L= parameter introduce to allow MODNAME to specify a different filespec
  44.     to the load module read by TRCUST.
  45.  
  46. /P  allows the path information specified with MODNAME to be retained in
  47.     the built TDF.
  48.  
  49. Fixes a TRAP caused by large line number tables with HLL3 (CSET++ 2.01)
  50.  
  51. Fixes a TRAP caused by using non-code DLLs.
  52.  
  53. Fixes a problem where TEST, NOT and NEG instructions with opcode byte 0XF6
  54. or 0XF7 were disallowed as tracepoints.
  55.  
  56. Fixes a problem with RETEP compatibility processing with previous versions,
  57. adds the /RP parameter and extends /RM options.
  58.  
  59.  
  60. The syntax for TRCUST 3.05 is as follows:
  61.  
  62. Usage1:  Trcust filename1 filename2 /M=mapfile /W{0|1|2} /D +
  63.                 /L=loadmod /NODE /NOLN /RM{0-6} /RSnnn /I /P
  64.  
  65.         filename1  is Trace Source File
  66.         filename2  is Trace Defintion File      (Optional)
  67.         /M=mapfile is map filename to use       (Optional)
  68.         /W{0|1|2}  is warning level to use      (Optional)
  69.         /D         allows duplicate minors      (Optional)
  70.         /L=loadmod is file name of load module  (Optional)
  71.         /NODE      ignore debug information     (Optional)
  72.         /NOLN      ignore line numbers          (Optional)
  73.         /RM{0-7}   RETEP match criteria         (Optional)
  74.         /RSnnn     RETEP search range           (Optional)
  75.         /RP        RETEP Pascal returns allowed (Optional)
  76.         /I         Case insensitive map symbols (Optional)
  77.         /P         Retain MODNAME Path Info     (Optional)
  78.  
  79. Usage2:  Trcust filename1 /C=dest_tff /W{0|1|2}
  80.  
  81.         filename1  is Trace Combine File containing TFF filenames
  82.         dest_tff   is destination TFF name for combined records
  83.         /W{0|1|2}  is warning level to use      (Optional)
  84.  
  85.  
  86. Usage 1 has introduced sever new parameters and some previouly
  87. undocumented parameters, which are now described:
  88.  
  89. /L=loadmod allows TRCUST to use a different file specification to the
  90.        name specified by the MODNAME TSF statement.
  91.  
  92.        TRCUST needs to exctract information from the load module to
  93.        generate the TDF. The module name is also required by the
  94.        TRACE command and so is recorded in the TDF from the MODNAME
  95.        statemenmt. /L is useful in cases where a module is built
  96.        using one name and subsequenlty renamed when installed,
  97.        or where the load module is built in a target directory
  98.        which differs from that of the TSF.
  99.  
  100.  
  101. /NODE  forces TRCUST to ignore debugging information even if present.
  102.        This is provide for cases where
  103.  
  104.        a)  the user wishes to use MAP symbols in preference to
  105.            debugging info.
  106.        b)  the level of debugging info in not supported by TRCUST and errors
  107.            are produces if it is used.
  108.  
  109.  NB debugging information is not a public standard. Some compilers may
  110.  appear to emulate Code View level 0, HLL 3 or HLL4, which not
  111.  actually doing so.
  112.  
  113. /NOLN forces TRCUST to ignore module line number records but honor
  114.       any other debugging informantion present.
  115.       This option is provided for cases where line number information
  116.       does not conform to supported specifications.
  117.  
  118.       N.B /NODE implies /NOLN
  119.  
  120. /I allows MAP file references to public symbols to be made case
  121. insensitively.
  122.  
  123. /RM{0-7} specfifes the default Return Entry Point (RETEP) match
  124.          criteria. By default, RETEP will use mode 2, however the
  125.          following modes may be specified:
  126.  
  127.          0  - Disallow RETEP.
  128.  
  129.          1 - Take RETEP from Code View symbol records only. NB HLL does
  130.              not provide return information.
  131.  
  132.          2 - Use mode 1 then search for a LEAVE+RET  or POP EBP 
  133.              instruction sequence near the end of the routine.
  134.  
  135.          3 - Use mode 2 then search for an isolated LEAVE instruction
  136.              near the end of the routine.
  137.  
  138.          4 - Use mode 2 then search for an isolated RET instruction
  139.              near the end of the routine.
  140.  
  141.          5 - Use modes 2 and 3 combined. Version 2.0 of TRCUST uses this
  142.              search mode. 
  143.  
  144.          6 - Use mode 4 then search for an isoloted JMP instruction
  145.              near the end of the routine.
  146.  
  147.          7 - Use mode 6 but search for an isolated LEAVE instruction
  148.              near the end of the routine, before searching for JMP.
  149.  
  150.         NB Determination of RETEP is subject to the following
  151.            limitations:
  152.  
  153.          1 - Only the last return from a routine is located.
  154.  
  155.          2 - Only mode 1 can accurately determine the last return, however
  156.              this is only available to code-view version 0 modules.
  157.  
  158.          3 - Searching for instruction sequences may result in a tracepoint
  159.              erroneously being placed within an instruction.
  160.  
  161.          4 - It may not be possible to use RETEP to define the return
  162.              tracepoint for modules that  use private (particularly optimised)
  163.              calling conventions.
  164.  
  165.          5 - The default mode is 2. This reasonably safe. Higher modes are less
  166.              safe.
  167.  
  168.          6 - Use mode 5 for compatible behaviour with earlier versions of TRCUST.
  169.              However, note that earlier versions of TRCUST erroneously permitted 
  170.              certain tracepoints which are not permitted using mode 5.
  171.  
  172.          7 - To avoid possible errors, JMP instructions with opcode 0xff are not 
  173.              selected.
  174.  
  175. /RP modifies RETEP processing to allow Pascal Return instructions (RET n) to be 
  176.     included in the search criteria with normal returns. Use this with 16-bit 
  177.     code where you know pascal returns are generated.
  178.  
  179.  
  180. /RSnnn specifies how far RETEP will search from the end of a routine
  181.        to find the return instruction sequence. This defaults to
  182.        18 bytes however RETEP will not search before the start of the routine.
  183.  
  184.  
  185. The RETEP keyword of the TSF  TRACE statement has been extended to
  186. allow specific RETEP search criteria to be specified per tracepoint.
  187. The syntax for RETEP is:
  188.  
  189.  RETEP[=options]
  190.  
  191. where options may be a combination of the following keywords
  192. separated by + signs:
  193.  
  194. CV    - use CV information
  195.  
  196. LRET  - search for a LEAVE+RET or POP EBP + RET sequence near
  197.         the end of the routine.
  198.  
  199. RET   - search for RET instruction near the end of the routine.
  200.  
  201. JMP   - search for JMP instruction near the end of the routine.
  202.  
  203. LEAVE - search for a LEAVE instruction near the end of the routine.
  204.  
  205. If more than one option is specified the RETEP uses the
  206. following order of precidence:
  207.  
  208. CV, LRET, RET, LEAVE, JMP