sync to release 4.1

[unix-history] / usr / src / old / games.vax / compat / Readme

.\"
.\"	Readme	4.1	82/05/12
.\"
.sp
.ce 100
A Package to Support VAX Compatability Mode on UNIX-32V
.sp
Arthur W. Wetzel
.br
735 LIS Bldg
.br
Interdisciplinary Department of Information Science
.br
University of Pittsburgh
.br
Pittsburgh, Pa. 15260
(412)-624-5203
.ce 0
.sp 2
This is a brief description of a 
package to support the execution of PDP-11 programs on
VAX UNIX-32V
or Berkeley VMUNIX
in compatability mode.
The major functions are to
.in +5
.sp
.ti -5
1) allocate a block
of memory as the PDP-11 memory space (this must start at location 0),
.ti -5
2) read compatability
mode program images into memory and lay them out properly (with arguments etc),
.ti -5
3) actually handle the change to and from compatability mode,
.ti -5
4) simulate system calls for what ever operating system is being simulated
and
.ti -5
5) simulate floating point (FPU and FIS) instructions.
.sp
.in -5
Unfortunately programs requiring separated I/D space can not be run.
Loading of the package is rather slow since the entire process is about
80K bytes
(64K is the PDP-11 space).
Once execution begins however, the speed is similar to a PDP-11/70.
There is considerable overhead for each exception condition
so that programs with a lot of system calls or especially with
floating point will be greatly slowed down.
Note that the text segment must be writable since the PDP-11
memory space is there.
.sp
Three quick changes to UNIX-32V and Berkeley VMUNIX
were made in the course of constructing this package.
.in 5
.sp
.ti -5
First, it is necessary to patch a bug in the original mchdep.c.
The bug in the sendsig routine is that the condition codes are masked out
of the psl before it is stacked when catching signals.
This affects all
programs not just compatability mode ones although is is not usually a frequent
problem execept in this application.
The mask which was 0xfff1
should be changed to 0xffff.
If this is not done, the condition codes
after a signal trap routine returns will always be cleared which can result
in many strange problems when condition codes are being checked in loops
or in this case after an "illegal instruction" trap.
This same bug remains in the
Third Berkeley Software Tape version of Virtual Memory UNIX.
.sp
.ti -5
Second, although it is easy to get into compatability mode one also
needs a way to get back when an exception condition arises.
This can be done
by changing another mask in the last line of the same routine.
The 0x1f
mask should be changed to 0x8000001f.
This clears the compatability mode bit
so that all signals are necessarily caught in native mode where native code
can do something about the situation.
.sp
.ti -5
Finally, if one wants compatibility
mode programs to have SETUID and SETGID status, there must be a way to change
the effective uid or gid without clobbering the real uid or gid.
This is
easily done by adding seteuid and setegid system calls to UNIX-32V.
My method
of doing this was to modify setuid and getuid so that the high order 16 bits
of the argument in the actual system calls is a flag (uids and gids are only
16 bits in the low order part of the word) to indicate either a regular
setuid or getuid function or alternately a seteuid and setegid function.
Appropriate functions seteuid() and setegid() have been added to our libc.a
which automatically set up the flags while setuid() and setgid() insure
that the flags are zeroed.
.in -5
.sp
Most of the programming was done in late August 1979 with additions being made
occasionally thru August 1980.
Compilation procedures are specified in Makefile.
An effort was made to minimize the amount of assembly language coding
so that only two small assembler routines are found here.
One of these (memsiz.s) simply specifies
how much memory is being allocated for PDP-11 images
and makes it available through certain global variables.
The other assembler file (compat.s) handles the protocol for getting
into compatability mode at a certain pc and with a certain ps.
It also includes a getreg function which copies machine registers into
known places.
The heart of the entire package is runcompat.c which is used for all RTSs
(Run Time Systems).
The function main here simply checks for the existence of the
file to be executed and sets the required uid and gid.
The execute function actually copies the file to memory
and sets trap conditions.
Finally illtrap() catches illegal instructions and goes to the
code appropriate for what is found as the illegal instruction.
The bulk of the lines of C code are in unixtraps.c and dofloat.c
which do UNIX system calls in either version 6 or 7 format
and simulate floating point operations.
(Since PWB-UNIX is upward compatable with version 6, the version 6
system support also includes PWB sys calls.)
There are probably a number of bugs in the floating point simulation
code just waiting to be found.
If you are running programs which already include the PDP-11
floating point interpretation code, you may want to disable
dofloat as the illegal instructions can be caught and simulated
in the PDP-11 code.
To do this just make dofloat.o with "cc -c -O -DNOFPSIM dofloat.c".
.sp
A shell which will automatically invoke compatability mode programs
is in the modshell directory as difference listings from the original
UNIX-32V shell.
Most of the new code is in a new function compat.c.
The automatic recognition of PDP-11 UNIX version 6/7 programs
relies on the fact that the second word (16 bit) of a PDP-11
a.out file (text size) is nonzero whereas it is 0 for 32V a.outs.
No easy distinction can be made between version 6 and version 7 a.outs
so that a shell variable RTS sets up the name of a default Run
Time System.
On our system version 6 a.outs have been patched so that word 6 of the header
which is unused is a 1.
This hoaky? method seems to work just fine.
A program v6flag.c is in the modshell directory to do this.
.sp
One possible use of this package is to get programs like INGRES running
on the VAX without going through what appears to be a nontrivial
conversion effort.
There are two ways of running such programs.
Firstly if the shell is patched to automatically recognize and
run compatability mode a.outs (as in modshell), the PDP-11 a.out files
for the program can be just put on the system with their
normal names and run as usual.
Note however that you will be using the UNIX-32V shell so that
any shell files from PDP-11 version 6 will have to be modified
for this to work correctly with something like INGRES.
The second approach
is to make a directory hierarchy somewhere which corresponds
to what would be on a PDP-11 including the appropriate PDP-11 shell.
In that case just execute that shell in compatability mode with
the root directory set to the top of the PDP-11 hierarchy.
This is the quickest way to get something going in a hurry since no
changes are required to existing PDP-11 code or shell files.
.sp
Emulation of RT-11 system calls provided by Dan Strick are not being
distributed at this time.
.sp
Please foreward any comments, bug fixes or quick questions to the author
at the above address.