home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / pascal / library / dos / t_power / tpinfo.doc < prev    next >
Text File  |  1988-02-25  |  13KB  |  287 lines
  1.  
  2.                                ***************
  3.                                * TPINFO 1.01 *
  4.                                ***************
  5.  
  6. TPINFO is a utility for extracting information from the TPU, TPL, and TPM
  7. files created by Turbo Pascal version 4.0. It can display four kinds of
  8. information gathered from these files:
  9.  
  10.   1. General information: The amount of code and data (both initialized and
  11.      uninitialized) in a unit; the size of the symbol table, relocation table
  12.      (used by the linker), and line number table (used by TPMAP); the state of
  13.      the $N compiler directive ($N+/$N-); the names of all units USEd by the
  14.      unit; and the names of all source and object (.OBJ) files that the unit
  15.      depends on. This information is always displayed. Example:
  16.  
  17.         Unit name:          TPCRT
  18.         Total code:         4569
  19.         Initialized data:   25
  20.         Uninitialized data: 38
  21.         Symbol table:       4676
  22.         Relocation table:   1794
  23.         Line number table:  432
  24.         Numeric processing: $N-
  25.  
  26.         Uses:
  27.         system
  28.  
  29.         Source Files:
  30.         tpcrt.pas, tpcrt.obj, tpfast.obj
  31.  
  32.      The size of the line number table will be 0 if the $D+ compiler directive
  33.      was not in effect when the unit was compiled. Note that all values
  34.      displayed by TPINFO are in decimal format (not hex) and refer to bytes
  35.      (not paragraphs).
  36.  
  37.   2. The names of all interfaced symbols: types, constants, variables
  38.      (includes typed constants), procedures, and functions. Symbol names are
  39.      sorted alphabetically and grouped according to class. This information is
  40.      displayed only if the '/S' command line option is specified. Example:
  41.  
  42.         Constants:
  43.         (none)
  44.  
  45.         Types:
  46.         windowptr
  47.  
  48.         Variables:
  49.         currentwindow
  50.  
  51.         Procedures:
  52.         disposewindow, scrollwindow
  53.  
  54.         Functions:
  55.         displaywindow, erasetopwindow, makewindow, settopwindow, windowisactive
  56.  
  57.      The Constants category includes symbols found in enumerated type
  58.      declarations, such as 'Beatles = (John, Paul, George, Ringo)'. The
  59.      Variables category includes typed constants and absolute variables (more
  60.      on these below).
  61.  
  62.   3. The sizes of all interfaced procedures and functions: This information,
  63.      displayed only if the '/P' command line option is specified, sometimes
  64.      involves guesswork. In a TPU file, all routines (procedures and
  65.      functions) are associated with a particular "code block". If the routine
  66.      is written in Pascal, the size of the code block is the size of the
  67.      routine, and the "entry point" displayed by TPINFO will indicate where
  68.      the code for the routine actually starts, relative to the beginning of
  69.      the block; everything prior to the entry point is presumably constant
  70.      data (probably strings). If the routine is an external assembly language
  71.      routine linked from an OBJ file, however, the size of the code block is
  72.      the size of the OBJ file, and the entry point is the offset into the OBJ
  73.      file for the routine. Example:
  74.  
  75.         Block Entry Approx Procedure/
  76.          Size Point  Size  Function
  77.         ----- ----- -----  ----------
  78.          2628  2443    40  assigncrt
  79.            46     0    46  blockcursor
  80.           465   306    70  changeattribute
  81.  
  82.      (The large entry point values are good indications that 'assigncrt' and
  83.      'changeattribute' are both assembly language routines located in OBJ
  84.      files, whereas 'blockcursor', which has an entry point of 0, is probably
  85.      written in Pascal.)
  86.  
  87.      The size of the code block and the entry point will always be correct.
  88.      The "approximate size" of the routine, however, is guaranteed to be
  89.      correct only for routines written in Pascal--neither the compiler nor
  90.      TPINFO has any way of knowing where an assembly language routine ends. So
  91.      what TPINFO does is to estimate the size of the routine by searching for
  92.      a second routine in the same code block, one with a higher entry point.
  93.      If no such routine is found, the size shown is simply the size of the
  94.      code block minus the entry point. If one is found, however, the size
  95.      shown represents the difference between the two entry points. This
  96.      estimated size will frequently be accurate if nothing intervenes between
  97.      the two routines, but even so there's no guarantee that the bulk of the
  98.      work done by the routine isn't performed by low-level routines hidden in
  99.      the OBJ file. In short, TPINFO's "approximate size" figures should be
  100.      taken with a grain of salt where assembly language routines are
  101.      concerned.
  102.  
  103.      Special case: Inline macros such as
  104.  
  105.         procedure InterruptsOff; inline($FA);
  106.           {-Turn interrupts off}
  107.  
  108.      do appear in the symbol table as procedures and functions, but they do
  109.      not belong to a particular code block, and their sizes are not readily
  110.      available (though they can be calculated). For now TPINFO simply ignores
  111.      them.
  112.  
  113.   4. Information about global variables and typed constants: their type
  114.      (integer, byte, etc.), class (global variable, typed constant, absolute
  115.      variable), and size. This information is displayed only if the '/V'
  116.      command line option is selected. Example:
  117.  
  118.         Type     Class  Size Name
  119.         -------- ----- ----- ---------------
  120.         boolean  const     1 biosscroll
  121.         word     var       2 buflen
  122.         boolean  var       1 checkbreak
  123.         boolean  var       1 checkeof
  124.         boolean  var       1 checksnow
  125.         boolean  var       1 ctrlbreakflag
  126.         enum     var       1 currentdisplay
  127.  
  128.      There are a couple of noteworthy limitations here. First, TPINFO does not
  129.      bother to track down the precise name of the variable type (e.g., if the
  130.      type is 'CharSet = set of Char', TPINFO will report 'set' rather than
  131.      'charset'). Due to the way that the symbol table is arranged, finding the
  132.      precise name for the type would be very difficult. Second, TPINFO will
  133.      report the type and size only if the type is declared either in the
  134.      current unit or in SYSTEM (where simple types such as byte and integer
  135.      are declared). It does not search other units in TPL or TPM files to try
  136.      to locate this information, even though it is sometimes available,
  137.      because doing so would add a considerable amount of overhead for minimal
  138.      gain. If the type information is not found, the type will be 'unknown',
  139.      and the size will be 0. (The class--var, const, or abs--is always known.)
  140.  
  141.      Notes about absolute variables: TPINFO displays the addresses of absolute
  142.      variables immediately following the name of the variable. Example:
  143.  
  144.         Type     Class  Size Name
  145.         -------- ----- ----- ---------------
  146.         word     abs       2 equipmentflags (0040:0010)
  147.  
  148.      Variables declared absolute 'on top of' other variables (e.g.,
  149.      'OutputHandle : Word absolute Output') appear in the symbol table as
  150.      regular global variables, not absolute variables.
  151.  
  152. The information mentioned above can be extracted from all three kinds of
  153. files: TPU, TPL, and TPM. TPINFO can also extract some additional information
  154. from TPM files:
  155.  
  156.   1. The total amount of code in the program, the total amount of data, the
  157.      amount of stack space it has, and the minimum and maximum heap settings.
  158.      Example:
  159.  
  160.         From .TPM file header:
  161.         Total code:         17664
  162.         Total data:         13703
  163.         Stack space:        8192
  164.         Min heap:           0
  165.         Max heap:           65520
  166.  
  167.      This information is always reported for TPM files.
  168.  
  169.   2. If the '/P' option is specified, TPINFO can tell you what routines were
  170.      stripped by the linker. These routines are flagged by a series of
  171.      asterisks where you would normally expect to see values. Example:
  172.  
  173.         Block Entry Approx Procedure/
  174.          Size Point  Size  Function
  175.         ----- ----- -----  ----------
  176.         ***** ***** *****  cancelallprintfiles
  177.         ***** ***** *****  cancelprintfile
  178.         ***** ***** *****  defaultdrive
  179.            36     0    36  dosversion
  180.  
  181.      Note that the linker cannot strip unused code located in OBJ files. If a
  182.      single routine in the OBJ file (considered a single code block) is used,
  183.      the entire OBJ file will be linked in. This explains why routines that
  184.      are never actually used will sometimes appear in the list without
  185.      asterisks beside them.
  186.  
  187. Note that a program is treated just like a unit by the compiler, except that
  188. it cannot be pre-compiled, and that the first "unit" in a TPM file is always
  189. the program itself.
  190.  
  191. Special note about the SYSTEM unit
  192. ----------------------------------
  193.  
  194. The compiler does not treat built-in procedures and functions (MemAvail, New,
  195. BlockRead, etc.) like ordinary routines. If you do a hex dump of SYSTEM.TPU,
  196. you'll see their names, but I have been unable to find a reliable way to
  197. determine what code block they're in, their sizes, etc., so for now TPINFO
  198. just ignores them.
  199.  
  200. Running TPINFO
  201. --------------
  202.  
  203. TPINFO is command-line driven and expects a command line of the following
  204. form:
  205.  
  206.    TPINFO tpufile[.TPU] [Options] [>Output]
  207.  
  208. "tpufile" is the name of the TPU, TPL, or TPM file to be analyzed, and an
  209. extension of "TPU" is assumed. If the file is not in the current directory,
  210. TPINFO will search DOS's PATH in an attempt to find it. If no "tpufile" is
  211. specified, an error message will be displayed.
  212.  
  213. The following options, discussed above, are currently available:
  214.  
  215.     /S  Generate a list of symbol names.
  216.     /P  Generate a list of procedures/functions and their sizes.
  217.     /V  Generate a list of variables and their types and sizes.
  218.  
  219. TPINFO will accept either '/' or '-' as an option delimiter, and the case of
  220. the option character ('S', 's', etc.) is not important.
  221.  
  222. TPINFO writes to the DOS standard output device, so its output may be
  223. redirected to a file or piped to a filter program such as MORE. Redirecting
  224. output is especially advisable if you are specifying the '/P' option, since it
  225. can produce several screens full of information in the blink of an eye, or if
  226. you are examining a TPL or TPM file. (Error and status messages are always
  227. written to the screen.)
  228.  
  229. If you enter "TPINFO" without any parameters or "TPINFO ?", a brief help
  230. screen will be displayed.
  231.  
  232.  
  233. Limitations
  234. -----------
  235. Like TPMAP and the compiler itself, TPINFO loads the entire TPU/TPL/TPM file
  236. into memory at once, so memory consumption can be high if the file is large,
  237. although 128K of available memory should usually be more than adequate. TPINFO
  238. is further limited to 2500 symbols in any one unit, a limitation that you are
  239. not likely to encounter.
  240.  
  241. TPINFO is also version-dependent: it's not likely to work with TPU/TPL/TPM
  242. files produced by future (post-4.0) versions of the compiler. I will try to
  243. update it to keep up with any changes, though.
  244.  
  245.  
  246. File Formats
  247. ------------
  248.  
  249. Borland has not yet made the format of TPU/TPL/TPM files public. TPINFO was
  250. made possible largely by spending countless hours staring at hex dumps, as
  251. well as a fair amount of time tracing through the compiler with Periscope. I
  252. have not seen any internal documents from Borland, nor has anyone at Borland
  253. told me anything about the file formats (except that they're secret).
  254.  
  255. Many thanks are due, however, to Jim Kyle, a pioneer in the field of
  256. TPU-snooping, who got me started; to Dave Baldwin, who pointed out several
  257. things about TPM files that I didn't know; and to Kim Kokkonen, who, besides
  258. helping me figure out a few stumpers, kindly allowed me to work on TPINFO on
  259. company time (well, maybe he had a motive...).
  260.  
  261. Anyway, please don't ask to see the source code for TPINFO. If Borland ever
  262. makes the file formats public, the source code for TPINFO will be made public
  263. too. Until then I feel obliged not to reveal any of their secrets for them.
  264.  
  265.  
  266. Distribution of TPINFO
  267. ----------------------
  268.  
  269. TPINFO is hereby placed in the public domain for private, non-commercial use.
  270. It may be distributed freely by means of public bulletin boards and other
  271. distribution channels for public domain software, so long as no fee is charged
  272. for it.
  273.  
  274. TPINFO is copyright (c) 1987 by TurboPower Software.
  275.  
  276.  
  277. Comments
  278. --------
  279.  
  280. Please address any comments/suggestions to
  281.  
  282.   Brian Foley, CompuServe [76317,3247]
  283.   TurboPower Software
  284.   3109 Scotts Valley Dr., Suite 122
  285.   Scotts Valley, CA 95066
  286.   408-438-8608 (9-5 M-F)
  287.