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