	       Apout -- Simulate PDP-11 Unix a.out binaries
			    Version 2.1 Beta

		     Warren Toomey  wkt@cs.adfa.oz.au
			      November 1995

Introduction
------------
This program is a user-level simulator for Seventh Edition 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.1 Beta. There are still a few errors here and there,
but 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.
I don't try to handle signal() etc. as yet. Finally, the simulator won't run on a
big-endian machine.

	EPERM syscalls			Ignored syscalls
	--------------			----------------
	   acct				    brk
	   phys				    ioctl
	   profil			    lock
	   ptrace			    signal
	   mount			    stime
	   times
	   umount


INSTALLATION
------------
I have only tested this program on a i486 running FreeBSD 2.1 and 1.1. 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.

The file `defines.h' has two pre-processor macros which you can either define or
undefine. The first, `DEBUG', includes debugging code into the program, and I
use it quite heavily when trying to fix niggling problems.

The second, `STREAM', compiles in code which uses stdio buffering on all the
simulated file descriptors, which improves I/O. It mostly works but is still
experimental, and so by default it is turned off.

If your compilers 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 `apout'.

Now go find an old v7 binary, e.g cal, and say:

	% 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

	+ Complete some of the syscalls that are	med priority
	     not fully simulated
	+ Try and get the stream buffering currently	med priority
	     ifdef'd out in trap.c to work
	+ Get some floating point code working		med priority
	+ Speed the simulator up by using cpp		med priority
	     macros, losing lots of f'n calls etc
	+ Allow APOUT_xxx env variables to		med priority
	     become simulated xxx env variables

	+ Test for #! a.out magic on exec, and		low priority
	     load the v7 shell to interpret it
	+ Support the binaries for other PDP Unixes	low priority
