	       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 7th Edition UNIX a.out binaries.
The user-mode PDP-11 instructions are simulated, and TRAP instructions
are simulated 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 Seventh Edition binaries
run fine. All of the Seventh Edition system calls are caught, but some are
ignored and some generate EPERM errors. 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 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 v7 binary, e.g 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 two options:

	-debug	turns on instruction tracing, which is _very_ verbose
	-trap	turns on TRAP tracing; not all syscalls have debugging code

All debugging output goes out to the file `apout.dbg'.

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
