Documentation for

TPU2ASM.EXE

A symbolic disassembler for
Turbo Pascal version 5.0 units

Copyright (C) 1989 by Per Bent Larsen
All rights reserved

Version 1.02, March 1989




What it is

TPU2ASM is a symbolic disassembler capable of extracting compiled code from a
version 5.0 Turbo Pascal TPU file. The output is a TASM compatible assembly
file.


What it can be used for

The utility can be used as an aid in developing EXTERNAL procedures and func-
tions for Turbo Pascal, allowing the programmer to write a template function or
procedure with parameter and local variable allocation set up automatically by
the compiler.

You can also choose to write the entire routine in pascal and then do manual
optimization on the code produced by the compiler. The code generated by Turbo
Pascal leaves much room for improvement as you will soon find out.

Another use for the utility is studying the code generated by the compiler to
determine which pascal constructs are preferable to others in terms of execu-
tion speed and code size. You'll be surprised.

Finally this utility makes it theoretically possible to convert an entire pro-
gram to assembler thus allowing you to link it with other languages like C or
PROLOG. To do this you must have the Turbo Pascal Runtime Library Source avai-
lable from Borland Int'l. It requires a conversion of the RTL into pure assem-
bler. Be warned - this may not be a trivial process.


What it isn't

This utility was not meant to be a reverse engineering tool, though it can be
used as such to a limited extend. All references are shown symbolically and
when a symbol is not known due to lack of information in the symbol tables, the
program does not attempt to make a symbol of it's own. When TPU2ASM can not
find the symbol for a reference, it is always because one ore more units were
compiled with $D- or $L-. References that can not be resolved symbolically are
left as ???? in the output file. Exceptions to this are items which are always
unnamed like the CS constant block. These items are named by TPU2ASM.


How to use it

The program is invoked from the DOS prompt as follows:

TPU2ASM UnitName OutputFile [Procedure|Function]

The UnitName is of course the name of the unit to extract from. The unit is
assumed to be in a file with the same name and a TPU extension or in TURBO.TPL.

The OutputFile specifies where the assembly should go to. The extension de-
faults to ASM. If the file exists you are prompted for overwrite permission.

The last parameter is an optional procedure or function name. If you omit this
entry it is assumed that you wish to extract all procedures and functions from
the unit. You are prompted for verification in this case. Only global procedu-
res and functions can be extracted. This is because local routines always have
an access link to the local data in the owner routine, more on that later. Glo-
bal routines will pull all their local routines into the disassembly as well.


Limitations

TPU2ASM reads the symbol table from all referenced units into RAM. This imposes
a restriction on the number and size of units referenced. However I haven't
encountered any heap overflows on my 640K machine even when extracting from
very large units with many references. Only symbol tables are kept in RAM, not
entire units.

Extracting EXTERNAL routines can not always be done correctly. A Turbo Pascal
procedure or function is always stored in the TPU as a single block. If the
entry point is zero, the entire block is known to be executable code, otherwise
the first part of the block is known to be CS constants (literal data like
strings, sets, range checking values and so on) and the rest is executable
code. Not so with externals. OBJ files can have multiple routines in them and
they can have data areas anywhere in both the data and code segments. Turbo
Pascal does not keep track of anything but the data size, the code size (inclu-
ding CS data) and the entry points for the PUBLIC routines. When extracting EX-
TERNALS from a TPU, TPU2ASM initially assumes that the entire block up to the
entry point is data. When it does the disassembly, it checks for jumps and
calls into the assumed data part. If such a branch is encountered, the disas-
sembly process is restarted with this new address as starting point. This pro-
cess is repeated as required. The consequence of this strategy is that if the
external module has multiple PUBLIC symbols, you may get the same routine in
the output more than once. Also any data after the starting point is assumed
to be code.

TPU2ASM attempts to create an ASM file which can be compiled directly by TASM.
However TPU2ASM does not attempt to solve symbolic conflicts between Turbo
Pascal and TASM. There are two types of errors likely to occur in an ASM file
produced by TPU2ASM: Either you have used an identifier name in you pascal pro-
gram which happens to be a reserved word in TASM, or you have local and global
identifiers with duplicate names. TASM does not handle scope concepts as does
pascal. Both types of errors can be dealt with by choosing other identifier
names in the pascal source.

A very important detail when working with Turbo Pascal EXTERNALS is the dis-
tinction between NEAR and FAR routines. Depending on the $F flag, the compiler
generates code for one of the two models. When a routine is extracted with
TPU2ASM, the assembler code follows the model which happened to be selected
when the unit was compiled. When Turbo Pascal meets an external reference in
the program, it assumes that the model used in the assembler routine is the
same as the current model in the Pascal source. Therefore you should specify
a $F directive in the unit to protect against accidental change of the model
assumed by the compiler. If you wish to be able to change the $F directive
for other code in the unit, you must protect the external against the change
using a $DEFINE, like this:

{$IFOPT F-}
{$DEFINE RESET_TO_NEAR}
{$F+}
{$ENDIF}
PROCEDURE ExternalFar; External; {$L ExtFar.OBJ}
{$IFDEF RESET_TO_NEAR}
{$F-}
{$ENDIF}

This example assumes that the external is a FAR procedure.


Symbols defined by TPU2ASM

When disassembling a code or data reference, TPU2ASM uses the symbol from the
pascal source if it's available. Data and code external to the unit is referen-
ced by the pascal symbol directly. Parameters and local variables have a BP
EQUate immediately following the PROC header, and all subsequent references are
done with the EQU symbol. All local variables and labels are preceded with @@
to avoid conflict with other PROCs. When disassembling functions, TPU2ASM de-
fines a BP EQUate to $RESULT which denotes the function result buffer. When
disassembling local routines, an additional BP symbol $LINK is defined, which
denotes the Base Page link to the calling routines local data. Local label
names are defined as @@: , the exception being when call or jumps out-
side the PROC-ENDP pair is encountered (this can only occur in EXTERNALS). In
this case the label names are defined as $. If the unit has
initialization code, it is given the name $INIT.

TASM offers a TPASCAL model directive to simplify creation of EXTERNALs for
Turbo Pascal. TPU2ASM does not use it, however. This is to give you complete
flexibility to change the code. When you use TPASCAL, TASM always sets up a
so called base frame, which is not always necessary.


References to the SYSTEM unit

The SYSTEM unit in TURBO.TPL has special properties. Only a few of the SYSTEM
routines listed in the manual or on the on line help screens for the unit actu-
ally correspond to a routine in SYSTEM.TPU. Some routines like WRITELN and
READLN produce a _number_ of calls to different built in SYSTEM routines depen-
ding on the actual variables being written or read. Others like LENGTH, SIZEOF,
SEG, OFS, PTR, HI, LO etc are coded inline by the compiler. Yet other routines
are service routines not described in the documentation. Among these are routi-
nes for range- and stack checking, program initialization and error reporting.

The problem with the SYSTEM unit in relation to TPU2ASM is, that it does not
interface any procedures or functions at all. The compiler has a symbol table
for the SYSTEM unit built into it, and the Turbo Pascal smart linker is smart
enough to recognize calls to these routines. In order to be able to solve refe-
rences to built in SYSTEM procedures, TPU2ASM too has a built in symbol table
of all SYSTEM procedures. Unfortunately this only solves half of the problem.
Having the names of the SYSTEM procedures makes it possible for TPU2ASM to show
calls and jumps to these routines, but because the symbols are not present in
SYSTEM.TPU (as they are not interfaced), the linker can not resolve these refe-
rences. To draw your attention to this, TPU2ASM places a # in front of all
calls and jumps to SYSTEM routines. There are two ways out of this problem:

The simplest solution is to avoid direct access to SYSTEM routines. You can
create a shell unit, which exports routines with the same names as the SYSTEM
procedures you wish to use. Example:


Unit Shell;
Interface
PROCEDURE GetMem(VAR P;Size:WORD);
PROCEDURE WriteLn(S:STRING);

Implementation
PROCEDURE GetMem(VAR P;Size:WORD);
BEGIN
SYSTEM.GetMem(Pointer(P),Size);
END;

PROCEDURE WriteLn(S:STRING);
BEGIN
SYSTEM.WriteLn(S);
END;

e.t.c.

The routines in the shell unit can be called freely from both pascal and assem-
bler programs.

The other approach requires that you have the Turbo Pascal Runtime Library
Source, available from Borland Int'l. You must change the SYSTEM.PAS to inter-
face all procedures. Then you must re-compile the TURBO.TPL using the MAKEFILE
supplied with the package. This will not only allow TPU2ASM to solve all refe-
rences to SYSTEM.TPU just like it solves references to all other units, namely
by doing a lookup in the units symbol table, it will also allow you to call the
routines directly from your EXTERNALS. You should be aware, however that chan-
ging and recompiling TURBO.TPL will invalidate _all_ TPUs created before the
change. This is especially a problem with units for which you don't have the
source code.


Unit search strategy

Apart from the unit containing the code, TPU2ASM must be able to locate all
units that contain definitions used by the code unit. When invoked, TPU2ASM
looks for TPC.CFG or TURBO.TP in 1) the current directory, 2) the DOS path, 3)
the TPU2ASM directory (DOS 3+ only). If either file is found, the Unit Direc-
tories definition is read and appended to the search path used internally by
TPU2ASM. When attempting to locate a unit, TPU2ASM uses the same search strate-
gy as mentioned for TPC.CFG/TURBO.TP. TPU2ASM does not look at the Turbo Direc-
tory or in TURBO.EXE for search paths. If you get a "unit not found" message,
you should create a TURBO.TP or TPC.CFG file specifying the Unit Directory in
your current directory.


System requirements

You'll need at least 128K RAM and DOS 2.0 or later to run TPU2ASM. To assemble
the output file you'll need TASM 1.0 or later.


Disclaimer of warranty

This software and it's documentation are sold as is without any express or im-
plied warranties whatsoever. The programs relies heavily upon the internal
structure of TPU files generated by the Turbo Pascal version 5.0 compiler. No
information has been made available officially or unofficially about this for-
mat by Borland Int'l. Because of this and because of the diversity of condi-
tions under which this program may be used, no warranty of fitness for a parti-
cular purpose is offered. I do not assume any liability for the use of this
program beyond the original purchase price. In no event will I be liable to you
for any lost profits or other damages arising out of the use of this program,
even if I have been advised of the possibility of such.


How to register

This program is sold under the ShareWare concept. This means that you may keep
a copy of it for a period of 30 days for the sole purpose of testing it. After
you have reviewed it, you should register it if you plan to continue using it.
As a benefit of registration, you will receive the full source code for TPU2ASM
(requires Turbo Professional 5.0 to compile) plus a few public domain utilities
for Turbo Pascal, also written by me. You are encouraged to distribute the sha-
reable version of TPU2ASM along with this documentation to others via BBS or on
diskette.

The price for the TPU2ASM package is $25 (or DKR. 175), including P&H.

The entire profit gained from selling this program will go into developing
other utilities for Turbo Pascal.

You can register with me directly by sending check or money to

Per Bent Larsen
Vesterled 24
8600 Silkeborg
DK-Denmark

or by paying via Giro (available in most european countries) to account
# 6 72 62 40.

or you can register with the Public (Software) Library (PSL) by calling
1-800-2424-PSL or by writing

PSL
P.O. Box 35707
Houston
TX 77235-5705

MC/Visa Accepted.

Please specify 5 1/4 inch or 3 1/2 inch disk.


Acknowledgements

TPU2ASM was originally based on the source code for the TINFO utility, which is
part of the famous Analyst package created and marketed by TurboPower Software.

Without the knowledge and cooperation of the TurboPower people and Brian Foley
in particular, this would not have been possible.


Product names and Copyrights

Parts of the source code for TPU2ASM is copyrighted by TurboPower software and
used by permission.

Analyst is a trademark of TurboPower Software.
Turbo Professional is a registered trademark of Sunny Hill software licensed to
TurboPower Software.
Turbo Pascal and TASM are trademarks or registered trademarks of Borland
International.


Comments and suggestions

Feel free to contact me if you have comments or suggestions to this product or
perhaps any future product, you would like to see. I can be reached on the
address mentioned above or on CompuServe 75470,1320. Just drop a note in the
Borland programming forum A (Go BPROGA), or send an E-Mail. In Europe I can
also be reached via Borland Scandinavia's BBS as Per Larsen (+45 02 14 04 94,
1200/2400,N,8,1).


Happy computing

Per B Larsen

3/17/89


Typing "TPU2ASM > TPU2ASM.DOC" at the DOS prompt will extract this information
to the file TPU2ASM.DOC.

This is a non registered evaluation copy. The standard version comes with the
documentation stored in a separate file.