README

   1                Apout -- Simulate PDP-11 Unix a.out binaries
   2                             Version 2.3 Beta 1
   3
   4                      Warren Toomey  wkt@tuhs.org
   5                                 June 2002
   6
   7 Introduction
   8 ------------
   9 This program is a user-level simulator for UNIX a.out binaries. Binaries
  10 for V1, V2, V5, V6, V7, 2.9BSD and 2.11BSD can be run with this simulator.
  11 The user-mode PDP-11 instructions are simulated, and TRAP instructions
  12 are emulated by calling equivalent native-mode system calls.
  13
  14 The advantages of an a.out simulator over a full-blown PDP-11 simulator are:
  15
  16    + system calls can be done natively, thus speeding up execution
  17    + the simulator is less of a CPU-hog than a full-blown PDP-11 simulator
  18    + you don't need a simulated operating system or a simulated file system
  19
  20 Apout can be obtained via anonymous ftp at minnie.tuhs.org in the
  21 directory pub/PDP-11/Sims/Apout. The directory pub/PDP-11/Sims/Apout/UnixBins
  22 contains tar archives of a.out binaries from several versions of UNIX.
  23
  24 Status
  25 ------
  26 The program is now at release 2.3 Alpha2. Most of the binaries from V5, V6
  27 and V7 run fine. All of the V5/V6/V7 system calls are caught, but some are
  28 ignored and some generate EPERM errors. The V1, V2, 2.9BSD and 2.11BSD
  29 environments are still under construction: see the file LIMITATIONS for
  30 details. Finally, the simulator won't run on a big-endian machine.
  31
  32 INSTALLATION
  33 ------------
  34 I have only tested this program on FreeBSD 2.x and 3.x, and on RedHat
  35 Linux 2.2. It should compile on a 32-bit little-endian machine with
  36 some form of Unix; you may need to change some header file includes etc.
  37 See `defines.h' for the details. In particular, if your system doesn't have
  38 types for:
  39
  40         int8_t, int16_t, int32_t, u_int8_t, u_int16_t, u_int32_t
  41
  42 or if your compiler doesn't have char=1 byte, short= 2 bytes, int=4 bytes,
  43 then alter the relevant typedefs in `defines.h'.
  44
  45 The Makefile has two sets of CFLAGS/LDFLAGS: one set is for debugging, and
  46 the other set is for speed. If you define the C pre-processor macro `DEBUG',
  47 then this includes debugging code into the program. I use it quite heavily
  48 when trying to fix niggling problems.
  49
  50 If you remove the -DEMU211 macro definition from the Makefile, the emulation
  51 of 2.11BSD will not be compiled in to the simulator. Similarly, if you remove
  52 the -DEMUV1 macro definition from the Makefile, the emulation of 1st and 2nd
  53 Edition UNIX will not be compiled in to the simulator. By default, EMUV1
  54 is disabled.
  55
  56
  57 Once you have configured apout, now type `make'. Hopefully, things will
  58 compile ok. You will eventually get the `apout' program.
  59
  60 Now go find an old PDP-11 UNIX binary, e.g 7th Edition cal, and say:
  61
  62         % setenv APOUT_ROOT /           # for now
  63         % apout cal 1970
  64
  65 If the simulator is working, the calendar for 1970 will be printed out.
  66 The V7 shell works, and from there, you can run other programs.
  67
  68         % apout sh
  69         # ls -l
  70             output of ls
  71         #
  72
  73 Finally, install apout in /usr/local/bin, and the manual page apout.1 in
  74 the appropriate place. If you can't use the man page because of incompatible
  75 macros, then apout.0 is a text file which has the pre-formatted man page.
  76
  77 DEBUG OPTIONS
  78 -------------
  79 When debugging is compiled in, the program has several options:
  80
  81         -inst   turns on instruction tracing, which is _very_ verbose
  82         -trap   turns on TRAP tracing; not all syscalls have debugging code
  83         -jsr    prints out the details of each jsr and rts
  84         -fp     prints out some details of floating-point instructions
  85
  86 All debugging output goes out to the file `apout.dbg'. These debugging options
  87 are mainly used for testing apout, and so the output in apout.dbg may not be
  88 very useful to you.
  89
  90 ENVIRONMENT VARIABLES
  91 ---------------------
  92 Apout has the concept of a simulated root filesystem for the simulated PDP-11
  93 binaries. When working with filenames, if the filenames are relative, they
  94 stay relative. If the filenames are absolute (i.e /usr/...), then apout
  95 prepends the value of the environment variable APOUT_ROOT to the filename.
  96 This allows you to say:
  97
  98         # setenv APOUT_ROOT /usr/misc/v7root
  99
 100 before running apout to set the `root' of the filesystem wherever you want.
 101 You MUST set APOUT_ROOT before running apout.
 102
 103 TODO
 104 ----
 105 There's lots to do. Here's what I'd like to do, in a somewhat ordered list.
 106
 107         + Verify that the instruction simulation and    high priority
 108              the syscalls all work correctly
 109         + Complete some of the syscalls that are        med priority
 110              not fully simulated
 111         + Speed the simulator up                        med priority
 112
 113 SOURCE ORGANISATION
 114 -------------------
 115
 116 main.c          parses any arguments, loads the binary and calls run()
 117 cpu.c           holds the main instruction decode/execute loop
 118 itab.c          holds function lookup tables for all instructions
 119 ea.c            holds functions to decode the PDP-11 addressing modes
 120 debug.c         holds strings for all emulated opcodes
 121
 122 single.c        single.c, double.c and branch.c hold most of the functions
 123 double.c         which perform the PDP-11 user-mode instructions. The code
 124 branch.c         in these files comes from a PDP-11 simulator by Eric Edwards
 125 fp.c            partially emulates FP instructions
 126
 127 aout.c          determines what type of a.out the binary is, and what UNIX
 128 magic.c          environment to set up. If V5/V6/V7, trap instructions fall
 129 v7trap.c         into v7trap.c which runs them using native system calls
 130 v7trap.h
 131
 132 v1trap.c        if the binary is a 1st or 2nd Edition binary, traps fall
 133 v1trap.h         into v1trap.c, which likewise does the syscalls natively
 134 ke11a.c         emulates the KE11A extended arithmetic unit, used by V1/V2
 135
 136 bsdtrap.c       if the binary is a 2.11BSD binary, trap instructions fall
 137 bsdtrap.h        into bsdtrap.c, which likewise does the syscalls natively
 138 bsd_ioctl.c     2.11BSD ioctl calls are handled with this file
 139
 140 defines.h       holds function & typedef prototypes and useful cpp macros