home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 6 File / 06-File.zip / maptsf.zip / maptsfuse.txt < prev   
Text File  |  2002-06-22  |  6KB  |  178 lines
  1. MAPTSF 1.7
  2. ----------
  3.  
  4. Syntax:
  5.          MAPTSF map_file [/MAJOR=major_code]
  6.                          [/MODNAME=name]
  7.                          [/MAXDATALENGTH=max_data_length]
  8.                          [/MINORSTART=minor_code]
  9.                          [/TEMPLATE=template_file]
  10.                          [/LOGSTACK=stack_bytes]
  11.                          [/EXCLUDE=string[*][,....]]
  12.                          [/INCLUDE=string[*][,....]]
  13.                          [/REGISTERS=reg[,reg]...]
  14.                          [/LOGRETURN]
  15.                          [/RETEP]
  16.                          [/CASESENSITIVE]
  17.                          [/TYPES]
  18.                          [/GROUPS=string[,.....]]
  19.  
  20. This utility will generate a TSF from a MAP file. One tracepoint is
  21. generated for each public code symbol. Optionally a return tracepoint
  22. may be generated for each public code symbol.  map_file is the only
  23. required parameter.  The remaining optional parameters have the
  24. following meaning:
  25.  
  26.     /MAJOR specifies the major code to be used in the MAJOR= statement
  27.     of the TSF . If omitted, TRCUST will select the default major code
  28.     of 1 when compiling the TSF.
  29.  
  30.     /MODNAME specifies the module name to be used in the MODNAME=
  31.     statement of the TSF. If omitted, MAPTSF will use the module name
  32.     that appears in the second line of the MAP file. Note, the MAP file
  33.     excludes the module extension. TRCUST will assume an extension of
  34.     .DLL if not specified.
  35.  
  36.     /MAXDATALENGTH specifies the MAXDATALENGTH= statement of the TSF.
  37.     If omitted, TRCUST will assume the default of 512 when compiling
  38.     the TSF.
  39.  
  40.     /MINORSTART specifies the first minor code. Subsequent
  41.     tracepoints have incremental minor codes. If omitted, the MINOR=
  42.     statement is not generated. TRCUST will assume an initial minor
  43.     code of 1 and increment for each tracepoint.
  44.  
  45.     /INCLUDE specifies a comma delimited list of case insensitive
  46.     strings used as inclusion criteria for public symbols.  An optional
  47.     trailing * signifies a generic match. If both /INCLUDE and /EXCLUDE
  48.     are specified then the logical OR of their criteria is used for
  49.     selection.
  50.     For example:
  51.  
  52.        /I=dos*,strupr inludes all public symbols beginning 'dos' or
  53.        equal to 'strupr'.
  54.  
  55.        /E=s* /I=strupr excludes all public symbols beginning 's' except
  56.        for 'strupr' and includes everything else.
  57.  
  58.     /EXCLUDE specifies a comma delimited list of case insensitive
  59.     strings used as exclusion criteria for public symbols.  An optional
  60.     trailing * signifies a generic match. If both /INCLUDE and /EXCLUDE
  61.     are specified then the logical OR of their criteria is used for
  62.     selection.
  63.     For example:
  64.  
  65.        /E=_*,dos* excludes all public symbols beginning '_' or 'dos'.
  66.  
  67.        /E=s* /I=strupr excludes all public symbols beginning 's' except
  68.        for 'strupr' and includes everything else.
  69.  
  70.     /CASESENSITIVE switch applies to /INCLUDE and /EXCLUDE. If specified
  71.     then the inculde and exclude strings will be match on a case-sensitve
  72.     basis.
  73.  
  74.     /LOGSTACK=n specifies the number of bytes of stack to log for entry
  75.     tracepoints. This causes the following TSF statements to be
  76.     generated for each entry tracepoint:
  77.  
  78.     for 16-bit code -
  79.         REGS=(SP,SS),
  80.         FMT="Stack pointer SS:SP=%A->",
  81.         MEM=(RSS+SP,D,n),
  82.         FMT="%R%W"
  83.  
  84.     for 32-bit code -
  85.         REGS=(ESP),
  86.         FMT="Stack pointer ESP=%F->",
  87.         MEM32=(FESP,D,n)
  88.         FMT="%R%F"
  89.  
  90.  
  91.     If /LOGSTACK is specified without a value then 16 bytes is assumed.
  92.  
  93.  
  94.     /LOGRETURN specifies that for each return tracepoint, the return
  95.     value in AX/EAX should be logged. This causes the following TSF
  96.     statements to be generated:
  97.  
  98.     for 16-bit code:
  99.         REGS=(AX)
  100.         FMT="Returns (ax) %W"
  101.  
  102.     for 32-bit code:
  103.         REGS=(EAX)
  104.         FMT="Returns (eax) %F"
  105.  
  106.  
  107.     /REGISTERS specifies one or more processor registers to be logged, each
  108.     separated by a comma.  The following register mnemonics are supported:
  109.  
  110.         AX,BX,CX,DX,CS,DS,ES,FS,GS,IP,SI,DI,SP,BP,FLAGS,
  111.         EAX,EBX,ECX,EDX,EIP,ESI,EDI,ESP,EBP,EFLAGS
  112.  
  113.  
  114.     /REGS may be used as a synonym for /REGISTERS.
  115.  
  116.  
  117.     /RETEP specifies that for each public entry-point in the MAP file, a
  118.     return tracepoint should be generated using the RETEP parameter of
  119.     the TRACE statement in the TSF. Note: RETEP is only processed by
  120.     TRCUST if the module has debugging information present. If this is
  121.     not the case then TRCUST (2.20) will ignore the RETEP parameter and
  122.     a warning message will be issued for the associated tracepoint.
  123.  
  124.     /TYPES
  125.         pre-defined types:
  126.  
  127.             PUB  = Public routines - names the begin upper case
  128.             (ignoring leading underscores)
  129.  
  130.             PRIV = Private routines - names the begin lower case
  131.             (ignoring leading underscores)
  132.  
  133.             PRE  = Entry tracepoint.
  134.  
  135.             POST = Exit tracepoint.
  136.  
  137.     /GROUPS
  138.  
  139.         Requests that each of the strings listed be used to define a
  140.         group. Tracepoints are assigned to a group according to
  141.         whether a group name matches the beginning of the tracepoint
  142.         name, ignoring case and leading underscore characters
  143.  
  144.     /TEMPLATE specifies a file where up to four template tracepoint
  145.     definitions may be specified, one for each of the following
  146.     categories:
  147.  
  148.        16-bit entry points
  149.        16-bit return points
  150.        32-bit entry points
  151.        32-bit return points
  152.  
  153.     The definitions are in a shortened form of the TRCUST TRACE
  154.     statement syntax. They are appended to each tracepoint of the
  155.     category to which they apply. All parameters other than MINOR and
  156.     DESC are permissible. TP and RETEP are specified as follows:
  157.  
  158.        TP=@16           signifies a 16-bit entry-point
  159.        TP=@16,RETEP     signifies a 16-bit return-point
  160.        TP=@32           signifies a 32-bit entry-point
  161.        TP=@32,RETEP     signifies a 32-bit return-point
  162.  
  163.     Only TP and RETEP may appear on the same line as the TRACE keyword.
  164.  
  165.  
  166.     For example:
  167.  
  168.         TRACE TP=@16
  169.               MEM=(SS:BP+8,I,0x10)
  170.               FMT="16-bytes of parameter 1: %R%W"
  171.  
  172.  
  173.      will append
  174.  
  175.               MEM=(SS:BP+8,I,0x10)
  176.               FMT="16-bytes of parameter 1: %R%W"
  177.  
  178.      to every 16-bit entry tracepoint definition.