home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / maketsf.zip / maketsfuse.txt < prev   
Text File  |  2002-06-22  |  6KB  |  148 lines
  1. MAKETSF 1.1
  2. -----------
  3.  
  4. The purpose of MAKETSF is to extract dynamic trace definitions imbedded
  5. in C or ASM source file to which they relate. MAKETSF will also
  6. substitute line number information into those trace definions that are
  7. specified by line number and source file reference.
  8.  
  9. For example:
  10.  
  11.   TRACE TP=@myprog.c,1234
  12.  
  13. This specifies a tracepoint at location corresponding to line 1234
  14. in module whose source is "myprocg.c".
  15.  
  16. The problem with this type of specification is that line number
  17. reference will need to be updated whenever the source is changed.
  18.  
  19. MAKETSF allows the trace definitions to be imbedded in the source as
  20. comments but in extraction will generate the correct line number
  21. information. It does this be detecting the string "TP=@," or "TP=@ "
  22. and then inserting the line number specification. If the TP=
  23. keyword explicitly specifies an address expression then the trace
  24. definiton is extracted without modification.
  25.  
  26. To use line number references modules must be compiled and linked
  27. with debugging information. For CSET2 the compile option is /TI, and
  28. the LINK386 option is /DE.
  29.  
  30. Warning: Optimised code may not place tracepoints in the desired
  31. location.
  32.  
  33.  
  34. For example:
  35. in C:
  36.  
  37.     +-------------------------------------------+
  38.     |/***DT here is the header                  |
  39.     | * MODNAME=my.exe                          |
  40.     | * MAJOR=256                               |
  41.     | */                                        |
  42.     |                                           |
  43.     |                                           |
  44.     |                                           |
  45.     |void myproc(char * parm1) {                |
  46.     |int result;                                |
  47.     |                                           |
  48.     |.                                          |
  49.     |.                                          |
  50.     |.                                          |
  51.     |                                           |
  52.     |/***DT tracepoint definition               |
  53.     | *   TRACE TP=@,                           |
  54.     | *   DESC="a tracepoint",                  |
  55.     | *   MEM32=(.parm1,I,4),                   |
  56.     | *   MEM32=(.resut,D,4),                   |
  57.     | *   FMT="parm1=%p%f result=%f"            |
  58.     | */                                        |
  59.     |                                           |
  60.     |                                           |
  61.     |                                           |
  62.     +-------------------------------------------+
  63.  
  64.  
  65.  
  66.     in ASM:
  67.  
  68.     +-------------------------------------------+
  69.     |;***DT here is the header                  |
  70.     |;  MODNAME=my.exe                          |
  71.     |;  MAJOR=256                               |
  72.     |                                           |
  73.     |                                           |
  74.     |parm1 DD ?                                 |
  75.     |                                           |
  76.     |myproc proc                                |
  77.     |       push ebp                            |
  78.     |       move ebp,esp                        |
  79.     |.                                          |
  80.     |.                                          |
  81.     |.                                          |
  82.     |                                           |
  83.     |;***DT tracepoint definition               |
  84.     |;   TRACE TP=@,                            |
  85.     |;   DESC="a tracepoint",                   |
  86.     |;   MEM32=(.parm1,D,4),                    |
  87.     |;   FMT="parm1=%p%f"                       |
  88.     |                                           |
  89.     |                                           |
  90.     +-------------------------------------------+
  91.  
  92. Notes: The comment block must begin in column 1 with either
  93.        ;***DT or /***DT.
  94.  
  95.        If the C form is used then an * must appear in column 2 of each
  96.        line. A */ in column 2 ends the comment block.
  97.  
  98.        If the ASM form is used then a ; is required in every column.
  99.  
  100.        If TP=@ is coded then MAPTSF will insert the file name and line
  101.        number corresponding to the trace definition.
  102.  
  103. MAKETSF  will respond to the $include <filename> directive if coded
  104. in column 1. This is intended for use where multiple source modules
  105. comprise a single load module. A list of component source files can
  106. be coded in a single file using include statements then given to
  107. MAKETSF for processing. For example:
  108.  
  109.     +-------------------------------------------+
  110.     |;A sample include file for MAKETSF         |
  111.     |                                           |
  112.     |                                           |
  113.     |$include myprog.c                          |
  114.     |$include ..\asm\myproc.asm                 |
  115.     |$include ..\sub\subr.c  This is a comment  |
  116.     |                                           |
  117.     +-------------------------------------------+
  118.  
  119.  
  120. MAKETSF will ignore any line that is not part of a ;***DT or /***DT
  121. comment block or a $include statement.
  122.  
  123. TSF output form MAKETSF is written to the output file if specified,
  124. otherwise to STDOUT.
  125.  
  126. Messages are written to STDERR.
  127.  
  128. There are five switch options that MAKETSF supports:
  129.  
  130. -v verbose mode - this gives information about number of files read
  131.    and blocks processed.
  132.  
  133. -n no includes - this forces MAKETSF to ignore $include directives.
  134.  
  135. -p include source file path info  - this forces MAKETSF to retain
  136.    the full file specification from $include statements or the
  137.    command line input file in the TP= keyword.
  138.    The default is to strip path information.
  139.  
  140. -a append output to output file. Default - replace output file
  141.  
  142. -o<output> specifies the output file. The default is to direct output
  143.    to STDOUT.
  144.  
  145. The syntax for MAKTSF is:
  146.  
  147.     MAKETSF <options> input
  148.