apout.1

   1 .\" Copyright Warren Toomey
   2 .\"
   3 .\" $Revision: 1.10 $
   4 .\" $Date: 2008/05/15 03:20:52 $
   5 .\"
   6 .Dd December, 2000
   7 .Dt APOUT 1
   8 .Os
   9 .Sh NAME
  10 .Nm apout
  11 .Nd run PDP-11 UNIX a.out binaries
  12 .Sh SYNOPSIS
  13 .Nm apout
  14 .Op Fl inst
  15 .Op Fl trap
  16 .Op Fl jsr
  17 .Op Fl fp
  18 .Ar file
  19 .Op Ar arguments ...
  20 .Sh DESCRIPTION
  21 .Nm apout
  22 runs the
  23 .Ar file
  24 which contains a PDP-11 UNIX a.out binary from one of the following
  25 versions of UNIX: 1st Edition, 2nd Edition, 5th Edition, 6th Edition,
  26 7th Edition, 2.9BSD or 2.11BSD. Any arguments after the named
  27 .Ar file
  28 are passed as arguments to the a.out binary.
  29 .Pp
  30 User-mode PDP-11 instructions are interpreted and executed by
  31 .Nm apout,
  32 and system calls made by the interpreted a.out binary are performed
  33 by making real systems calls to the underlying native operating system.
  34 In this way, the interpreted a.out binary can interact with the real
  35 files and processes on the system.
  36 .Pp
  37 If
  38 .Nm apout
  39 has been compiled with debugging enabled, the following options are available:
  40 .Bl -tag -width trap
  41 .It Fl inst
  42 Output a line for each instruction emulated which gives:
  43 the PC in octal, the instruction in octal, the instruction's name,
  44 r0 to r6 in octal, and the values of the N, Z, V and C flags.
  45 .It Fl trap
  46 Output a line for each system call, which gives the name of the system
  47 call, possibly a list of arguments, and the value returned by the system
  48 call.
  49 .It Fl jsr
  50 Output a line for each
  51 .Ar jsr
  52 or
  53 .Ar rts
  54 giving the value of the new PC. For 2.11BSD overlay binaries, also output
  55 a line describing each overlay change.
  56 .It Fl fp
  57 For many of the emulated floating-point instructions, output a line
  58 describing the operation.
  59 .El
  60 .Pp
  61 If
  62 .Nm apout
  63 was not compiled with debugging enabled, none of these options exist.
  64 Any debugging output is directed to the file
  65 .Ar apout.dbg
  66 in the directory where
  67 .Nm apout
  68 was started. The debugging output is primarily designed to aid the
  69 developers of
  70 .Nm apout,
  71 and so it isn't exhaustive for all instructions, traps or floating-point
  72 operations.
  73 .Sh ENVIRONMENT VARIABLES
  74 .Nm apout
  75 requires one environment variable to be set:
  76 .Ev APOUT_ROOT.
  77 This variable names the `root' of the emulated filesystem.
  78 .Pp
  79 When
  80 .Nm apout
  81 works with filenames, if the filenames are relative, then they
  82 stay relative i.e all files on the system can be named, as long as they are
  83 given relative names. However, if the filenames are absolute, i.e they
  84 start with a slash, then
  85 .Nm apout
  86 prepends the value of the environment variable
  87 .Ev APOUT_ROOT
  88 to the filename. Therefore, if you have the 7th Edition files located in
  89 .Ar /usr/misc/v7root
  90 and you do:
  91 .Bd -literal
  92     %  setenv APOUT_ROOT /usr/misc/v7root
  93     %  apout $APOUT_ROOT/bin/sh
  94     $
  95 .Ed
  96 .Pp
  97 then you will be greeted with the 7th Edition Bourne shell prompt as shown:
  98 you will still be in the directory where you started
  99 .Nm apout,
 100 but if you cd to /, then you will be taken to
 101 .Ar /usr/misc/v7root
 102 .Pp
 103 Note that you must set
 104 .Ev APOUT_ROOT
 105 before you can run
 106 .Nm apout.
 107 .Pp
 108 There is one other optional environment variable:
 109 .Ev APOUT_UNIX_VERSION.
 110 This is mainly required for UNIX binaries that use the 0407 header,
 111 which was used across several versions of UNIX, each with a different set
 112 of system calls. If APOUT_UNIX_VERSION is set,
 113 .Nm apout
 114 will use the given version when it cannot determine which version of UNIX a
 115 binary belongs to. The available values are "V1", "V2", "V3", "V4", "V5", "V6",
 116 "V7", "2.9BSD" and "2.11BSD".
 117 .Pp
 118 .Sh EMULATED ENVIRONMENT VARIABLES
 119 Initially, PDP-11 binaries run via
 120 .Nm apout
 121 receive the following set of emulated environment variables:
 122 .Bd -literal
 123     PATH  /bin:/usr/bin:/usr/sbin:/usr/ucb:/usr/games:/usr/local/bin:.
 124     HOME  /
 125     TERM  vt100
 126 .Ed
 127 .Pp
 128 Emulated programs can, of course, change this emulated environment;
 129 they can also fork and exec other PDP-11 binaries, which will inherit the
 130 modified emulated environment.
 131 .Sh INTERACTION WITH NATIVE PROGRAMS
 132 Binaries that are interpreted by
 133 .Nm apout
 134 can interact with native programs in several ways: through files in the
 135 filesystem, and through pipes. For example, you can do the following:
 136 .Bd -literal
 137     %  ls -lR | apout $APOUT_ROOT/bin/wc | lpr
 138     %  apout $APOUT_ROOT/bin/sort < file | uniq > newfile
 139 .Ed
 140 .Pp
 141 where
 142 .Ar ls,
 143 .Ar lpr
 144 and
 145 .Ar uniq
 146 are native programs.
 147 .Pp
 148 If
 149 .Nm apout
 150 is compiled with the NATIVES preprocessor directive enabled, then native system
 151 binaries can be executed as well as PDP-11 binaries. For example:
 152 .Bd -literal
 153     % cd $APOUT_ROOT
 154     % ln -s `which vi` bin/vi       Add vi into the filespace
 155     % apout bin/sh
 156     $ ls -l                         Run the PDP-11 ls
 157       ....
 158     $ vi kim.c                      Run the native vi
 159     $ cc -o kim kim.c               Compile with the PDP-11 compiler
 160 .Ed
 161 .Pp
 162 Note that native executable receive the same environment variables inherited
 163 by the
 164 .Nm apout
 165 process, and not the emulated environment that
 166 .Nm apout
 167 passes to emulated executables.
 168 .Sh ERROR MESSAGES
 169 So as to distinguish from error messages generated by the interpreted PDP-11
 170 binaries,
 171 .Nm apout
 172 prepends the word `Apout' to the beginning of its error messages. Below is
 173 the list of error messages that
 174 .Nm apout
 175 can generate:
 176 .Bd -ragged
 177    Apout - V1 sectosixty too big
 178    Apout - can't malloc overlay!
 179    Apout - can't switch to empty overlay %d
 180    Apout - could not read 1st line of script
 181    Apout - couldn't load %s
 182    Apout - open_dir couldn't open %s
 183    Apout - out of argv space in script
 184    Apout - pid %d bad FP register used at PC 0%o
 185    Apout - pid %d bpt instruction at PC 0%o
 186    Apout - pid %d bus error at PC 0%06o
 187    Apout - pid %d emt instruction at PC 0%o
 188    Apout - pid %d halt instruction at PC 0%o
 189    Apout - pid %d illegal instruction %o at PC 0%o
 190    Apout - pid %d iot instruction at PC 0%o
 191    Apout - pid %d mark instruction at PC 0%o
 192    Apout - pid %d mfpd instruction at PC 0%o
 193    Apout - pid %d mtpd instruction at PC 0%o
 194    Apout - pid %d segmentation fault at PC 0%06o
 195    Apout - pid %d trap instruction at PC 0%o
 196    Apout - pid %d unimplemented instruction at PC 0%o
 197    Apout - pid %d unknown KE11 register 0%o
 198    Apout - pid %d waiti instruction at PC 0%o
 199    Apout - the %s syscall is not yet implemented
 200    Apout - the 2.11BSD %s syscall is not yet implemented
 201    Apout - unknown a.out format 0%o
 202    Apout - unknown magic in header: 0x%x
 203    Apout - unknown syscall %d at PC 0%o
 204    Apout cannot set the environment for the a.out %s
 205    Apout not compiled to support 1st Edition binaries
 206    Apout not compiled to support 2nd Edition binaries
 207    Apout not compiled to support 2.11BSD binaries
 208 .Ed
 209 .Sh CAVEATS
 210 As far as is known, the emulation of user-mode integer instructions is correct.
 211 The emulation of floating-point instructions is seriously deficient:
 212 only 32-bit floats are emulated: the extra 32-bits of precision in PDP-11
 213 doubles goes unused. None of the FP errors are emulated.
 214 .Pp
 215 The emulation of each of the emulated UNIX environments is mostly,
 216 but not fully, complete. Any UNIX system call environment is very
 217 sophisticated, and
 218 .Ar apout
 219 must translate from the emulated UNIX environment to the native one, and
 220 back. For an authorative description of what is missing from, or deficient
 221 in, each of the emulated UNIX environments, see the source files
 222 .Ar v1trap.c,
 223 .Ar v7trap.c
 224 and
 225 .Ar bsdtrap.c
 226 in the source directory for
 227 .Nm apout.
 228 You should also consult the file
 229 .Ar LIMITATIONS
 230 in the source directory for
 231 .Nm apout.
 232 .Sh SEE ALSO
 233 The latest source for
 234 .Nm apout
 235 can be obtained via anonymous ftp at minnie.tuhs.org in the directory
 236 pub/PDP-11/Sims/Apout. The directory pub/PDP-11/Sims/Apout/UnixBins
 237 contains tar archives of a.out binaries from several versions of UNIX.
 238 Information on PDP-11 UNIX can be found on the PUPS web page at
 239 http://minnie.tuhs.org/PUPS/
 240 .Sh HISTORY
 241 The first version of
 242 .Nm apout
 243 appeared in 1995, and provided support for 6th and 7th Edition
 244 UNIX binaries. In 1998/1999, support was added for 2.11BSD binaries.
 245 In 1999/2000, support was added for 1st and 2nd Edition UNIX binaries.