	       Apout -- Simulate PDP-11 Unix a.out binaries
			    Version 2.2 Alpha

		     Warren Toomey  wkt@cs.adfa.edu.au
			      December 1998

Introduction
------------
This program is a user-level simulator for UNIX a.out binaries. Binaries
for V5, V6, V7 and 2.11BSD can be run with this simulator. The user-mode
PDP-11 instructions are simulated, and TRAP instructions are emulated by
calling equivalent native-mode system calls.

The advantages of an a.out simulator over a full-blown PDP-11 simulator are:

   + system calls can be done natively, thus speeding up execution
   + the simulator is less of a CPU-hog than a full-blown PDP-11 simulator
   + you don't need a simulated operating system or a simulated file system

Status
------
The program is now at release 2.2 Alpha. Most of the binaries from V5, V6
and V7 run fine. All of the V5/V6/V7 system calls are caught, but some are
ignored and some generate EPERM errors. The 2.11BSD environment is still
under construction: see the file LIMITATIONS for details. Finally, the
simulator won't run on a big-endian machine.

INSTALLATION
------------
I have only tested this program on FreeBSD 2.x and 3.0. It should compile on a
32-bit little-endian machine with some form of Unix; you may need to change
some header file includes etc.

If you define the C pre-processor macro `DEBUG', then this includes debugging
code into the program. I use it quite heavily when trying to fix niggling
problems.

If you remove the -DEMU211 macro definition from the Makefile, the emulation
of 2.11BSD will not be compiled in to the simulator.

If your compiler doesn't have char=1 byte, short= 2 bytes, int=4 bytes, alter
the relevant typedefs in `defines.h'.

Now type `make'. Hopefully, things will compile ok. You will eventually get
the `apout' program.

Now go find an old PDP-11 UNIX binary, e.g 7th Edition cal, and say:

	% setenv APOUT_ROOT /		# for now
	% apout cal 1970

If the simulator is working, the calendar for 1970 will be printed out.
The V7 shell works, and from there, you can run other programs.

	% apout sh
	# ls -l
	    output of ls
	#

OPTIONS
-------
When debugging is compiled in, the program has several options:

	-inst	turns on instruction tracing, which is _very_ verbose
	-trap	turns on TRAP tracing; not all syscalls have debugging code
	-jsr	prints out the details of each jsr and rts
	-fp	prints out some details of floating-point instructions

All debugging output goes out to the file `apout.dbg'. These debugging options
are mainly used for testing apout, and so the output in apout.dbg may not be
very useful to you.

ENVIRONMENT VARIABLES
---------------------
Apout has the concept of a simulated root filesystem for the simulated v7
binaries. When working with filenames, if the filenames are relative, they
stay relative. If the filenames are rooted (i.e /usr/...), then apout prepends
the value of the environment variable APOUT_ROOT to the filename. This allows
you to say:

	# setenv APOUT_ROOT /usr/misc/v7root

before running apout to set the `root' of the filesystem wherever you want.
You MUST set APOUT_ROOT before running apout.

TODO
----
There's lots to do. Here's what I'd like to do, in a somewhat ordered list.

	+ Verify that the instruction simulation and	high priority
	     the syscalls all work correctly
	+ Get some floating point code working		high priority

	+ Support the binaries for other PDP Unixes	med priority

	+ Test for #! a.out magic on exec, and		med priority
	     load the v7 shell to interpret it
	+ Complete some of the syscalls that are	low priority
	     not fully simulated
	+ Speed the simulator up 			low priority

SOURCE ORGANISATION
-------------------

main.c		parses any arguments, loads the binary and calls run()
cpu.c		holds the main instruction decode/execute loop
itab.c		holds function lookup tables for all instructions
ea.c		holds functions to decode the PDP-11 addressing modes

single.c	single.c, double.c and branch.c hold most of the functions
double.c	 which perform the PDP-11 user-mode instructions. The code
branch.c	 in these files comes from a PDP-11 simulator by Eric Edwards
fp.c		will one day hold a full FP emulator. Currently nearly empty

aout.c		determines what type of a.out the binary is, and what UNIX
v7trap.c	 environment to set up. If V5/V6/V7, trap instructions fall
v7trap.h	 into v7trap.c which runs them using native system calls

bsdtrap.c	if the binary is a 2.11BSD binary, trap instructions fall
bsdtrap.h	 into bsdtrap.c, which likewise does the syscalls natively

defines.h	holds function & typedef prototypes and useful cpp macros
