bintrans - A Dynamic Binary Translator
======================================
These are the first attempts at installation instructions and
documentation for bintrans. The information you find in here should
be correct, but it is certainly not comprehensive. If there is
anything you would like to know which is not contained in here, please
mail me.
Overview
--------
bintrans currently has working i386->PPC and PPC->Alpha translators.
There is also a i386->Alpha translator which is currently defunct,
because I have not kept it up-to-date with other parts of bintrans.
If you need it, please mail me, and I'll see what I can do to help
you.
bintrans can also run as an interpreter, in which case it can emulate
the i386 and the PPC. Running bintrans as an interpreter should work
on almost all native architectures (like i386, SPARC, MIPS, ...).
Mail me if you have any problems running the interpreter.
WARNING: bintrans does not currently run real-world applications. It
runs the SPECINT95 benchmarks and some small X11 applications (it runs
xedit and xdvi on i386->PPC and xbattle on PPC->Alpha). The main
thing holding bintrans back is the system call interface and signal
handling. I'll soon start implementing signals, but I'm currently
mostly dependent on contributors regard the system call interface. If
you want to help out, please mail me.
Homepage
--------
bintrans's homepage is
http://www.complang.tuwien.ac.at/schani/bintrans/
Prerequisites
-------------
The i386->PPC translator requires the uClibc library. You can get it
from
http://www.uclibc.org/
Also, if you want to play with the machine descriptions, get a Common
Lisp implementation. I have only tested this with CLISP, so if you
use something else, you're on your own. CLISP's homepage is
http://clisp.sourceforge.net/
Compiling
---------
First, modify the Makefile. Search for the string "ATT" and follow
the instructions you find there. You shouldn't have to change
anything other than the ATT-annotated parts.
There are four different modes bintrans can run in. They are:
COMPILER
This is the mode of operation which you'll most likely want to
use. In this mode, bintrans will operate as a dynamic binary
translator.
INTERPRETER
This mode uses the interpreter to execute foreign instructions.
That means it's slow, but it should run on almost all native
architectures.
DEBUGGER
This runs the interpreter with a simple machine level debugger
interface. Type "help" on the debugger prompt for a summary
of commands.
CROSSDEBUGGER
In this mode, the compiler and the interpreter run in
tandem. After each executed fragment, the state of both is
compared and if they differ, execution stops. This makes finding
bugs in the compiler very easy, provided that the interpreter
works correctly.
The DEFINES variable can be used to specify several options. These
are the most important ones:
USE_HAND_TRANSLATOR
This must be enabled if you use COMPILER or CROSSDEBUGGER mode.
COLLECT_STATS
Collects all sorts of useful and lots of uttely meaningless
statistics and prints them out when the program is finished. I
always keep it turned on.
DUMP_CODE
Prints out the native code generated during executions, together
with the corresponding original foreign code.
EMULATED_MEM
This can and should be used in interpreter and debugger mode for
better portability. It makes bintrans emulate the foreign address
space instead of using the native address space directly.
Installing
----------
Installation of bintrans mainly involves creating a root file system
for the emulated machine. Simply create a directory and copy all the
files you want there, or NFS mount the root partition of a system you
want to emulate. Then, create a file ".bintransrc" in your home
directory, which should look like this:
(root ppc linux "/nethome/hansolo/schani/Work/unix/bintrans/ppc-root")
(root i386 linux "/nethome/hansolo/schani/Work/unix/bintrans/i386-root")
Of course, you have to change the paths accordingly.
You can download example i386 and PPC root file systems from the
bintrans homepage.
NOTE: In order for dynamic executables to work, you have to make sure
all shared libraries (including the dynamic loader ld.so) are in the
correct places in the emulated root file system.
Running Programs
----------------
Simply invoke bintrans with the name and arguments of the foreign
executable. Let's say you copied a hello-world program called "hello"
to the directory /usr/bin in the emulated root file system. Invoke it
with
bintrans /usr/bin/hello
It seems X11 applications don't work yet with X11 authentication, so
you have to turn it off, by doing
xhost +
Contributing
------------
bintrans needs YOUR help! Play around with it and mail me if
something doesn't work. Again, don't expect Mozilla to run, but
simple X11 applications should run without too much difficulty,
i.e. there will probably a few unsupported system calls and maybe one
or the other opcode which isn't implemented yet.
One area which needs lots of help is the system call interface.
Fortunately, this part of bintrans isn't too hard to work on. Please
mail me if you want to have a go at it.
If you are interested in getting bintrans to support other
foreign-native combinations, I'm also very interested and willing to
help.
Also, the name "bintrans" is slightly boring and is a testament to my
lack of phantasy. If you can think of a better name, please let me
know.
Machine Descriptions
--------------------
bintrans uses machine descriptions to automatically generate
interpreters, disassemblers, composer macros, and liveness analysers.
Currently, there are machine descriptions for the i386, the PPC and
the Alpha, residing in the files "i386.lisp", "ppc.lisp", and
"alpha.lisp", respectively.
Should you choose to play around with them, here's how to generate the
various C files from them:
1. Start CLISP
2. (load "init.lisp")
then:
3a. (generate-all-alpha-files) ; to generate the Alpha files
3b. (generate-all-ppc-files) ; to generate the PPC files
3c. (generate-all-intel-files) ; to generate the i386 files
Loading and generating might take quite some time, so don't worry if
it takes a little longer.
---
Mark Probst
schani@complang.tuwien.ac.at