.if n .po 12
.hy 14
.nr SE 0 1
.nr SU 0 1
.nr PT 0 1
.de it
.ul
\\$1
..
.	Only works for 2 character arguments
.	The following contains backspace characters
.	Replace when the new nroff is available
.de bd
.if n \\$1\\$1\\$1
.if t .ft B
.if t \\$1
.if t .ft
..
.de hd
.cp
.if t 'tl '-''-'
.ev 2
.ps 9
'sp 2
.tr "'
.if t .if o 'tl 'RT-11 Emulator Maintenance and Installation Guide''%'
.if t .if e 'tl '%''RT-11 Emulator Maintenance and Installation Guide'
.if n 'tl 'RT-11 Emulator Maintenance and Installation Guide''%                '
.tr ""
'sp 2
.ev
..
.de fo
.ev 2
'sp 2
.ps 9
'tl ''Human Computing Resources Corporation''
'bp
.ev
..
.de BE
.wh 0 hd
.wh -6 fo
.nr % 0
..
.de se
.bp
.ps +1
\\n+(SE.
.nr SU 0 1
.nr PT 0 1
.ul
\\$1
.in 0
.ps -1
.br
..
.de su
.br
.ps +1
.ne 8
.sp 2
.nr PT 0 1
\\n(SE.\\n+(SU
.ul
\\$1
.br
.ps -1
..
.de pt
.br
.ne 5
.sp 2
\\n(SE.\\n(SU.\\n+(PT
\\$1
..
.de pg
.br
.ne 2
.sp
..
.de -
.sp
.ti -2
-\\ \\c
..
.de id
Identical to RT-11 SJ.
..
.sp 22
.nf
.ce 100
RT-11 Emulator
Maintenance and Installation Guide
Version 2
.sp
24 May 1979
.sp 5
Michael D. Tilson
Human Computing Resources Corporation
10 St. Mary Street
Toronto, Ontario, Canada
M4Y 1P9
.sp 2
ABSTRACT
.sp
.ce 0
.fi
.in +5
.ll -5
The RT-11* emulator allows most
RT-11 programs to run under UNIX* with no modifications.
This document describes some of the important implementation details,
and gives instructions for compiling and installing the emulator.
.sp
Information contained in this document is proprietary and is not to be
transmitted or reproduced
without permission.
.sp 3
.ps -1
* RT-11 is a trademark of Digital Equipment Corp.
.br
* UNIX is a trademark of Bell Laboratories.
.ps +1
.in -5
.ll +5
.BE
.bp
.ul
INTRODUCTION
.pg
This document discusses some of the implementation details of the RT-11
emulator program.
It is assumed that the reader is familiar with the
.ul
RT-11 Emulator User's Guide.
A copy of the source code should also be available.
.pg
The Maintenance and Installation Guide consists of:
.sp
.nf
.in +5
1.	Description of Files
2.	Trap Handling
3.	Core Layout
4.	I/O System
5.	Possible Upgrades
6.	Changes for UNIX Version 7
7.	Installing the Emulator
.in -5
.fi
.se "Description of Files"
.su "Supplied Directories"
.pg
The following directories are supplied with the emulator.
.in +10
.ta 5
.sp
.ti -5
bin	\c
Binaries of various programs.
.sp
.ti -5
docu	\c
Documentation.
.sp
.ti -5
emt	\c
Source files for emulator.  Described below.
.sp
.ti -5
misc	\c
Source for miscellaneous programs and UNIX system modifications.
.sp
.ti -5
test	\c
Test data to check out the operation of the emulator.
.in -10
.su "Source Files"
.pg
This section describes the source files which comprise the emulator.
.pg
There are several shell files and programs useful for compiling the
emulator:
.in +10
.sp
.ti -5
assemble	\c
assembles the assembly language support routines.
Requires one argument:
"nomod" means assemble the routines "as is".
"space" means assemble the routines to allow space for RT-11 user
programs.
(A conditional compilation flag is set.)
"nospace" means assemble the routines to allow zero space for user
programs.
(This is used to determine the size of the emulator itself.)
.sp
.ti -5
compile	\c
Takes one argument "file" and compiles "file.c".
The resulting "file.o" is stored in directory "lib".
.sp
.ti -5
load	\c
Assembles the assembly language files and links the result with
the object files in "lib".
The process is done twice:
First the emulator is loaded with no space for user programs.
Then the size of the emulator is determined, and
assem0.s is edited to patch the size in.
Then the emulator is re-assembled and loaded so that it occupies
exactly 56 Kbytes.
.sp
.ti -5
makefile	\c
Used with the University of Toronto version of "make".
Makefile is a dependancy list which shows which things must
be recompiled when some file changes.
You probably won't use it.
.sp
.ti -5
makerr	\c
Reads the file "errors.h" and produces the emulator error message
file as its argument.
Thus "makerr /lib/rt11/errs" suffices to install an up to date version.
.sp
.ti -5
print	\c
Prints the source on the standard output.
.sp
.ti -5
run	\c
Does everything necessary to build the entire system.
Compares the resulting "a.out" and "errs" files with the installed
version, but leaves the files in the source directory.
Removes all object files when done.
.sp
.ti -5
scrunch	\c
Manipulates the emulator "a.out" to speed up loading.
Described later.
Usage is "scrunch a.out scr.out".
Scr.out is the final version of the emulator to be installed
in /bin/ru.
.sp
.ti -5
assem0.s	\c
Constants and flags used by other assembly files.
Defines the size of the emulator (determined automatically by "load")
and whether space is to be allocated for user programs.
.sp
.ti -5
assem1.s	\c
Allocates half of the space for user programs.
(It does not allocate all of the space due to a bug in "ld".)
Also contains the code to "unscrunch" the emulator at run-time, if
it has been "scrunched".
.sp
.ti -5
assem2.s	\c
Allocates the other half of the user space.
.sp
.ti -5
assem3.s	\c
Assembly language support routines.
.in -10
.pg
Include files:
.in +10
.sp
.ti -5
decls.h	\c
Global declarations of general use.
.sp
.ti -5
defns.h	\c
Globally used define symbols.
.sp
.ti -5
errors.h	\c
Defines error codes.
The error messages are produced automatically from the associated
comments.
.sp
.ti -5
io.h	\c
Defines and declarations relevant to I/O.
.sp
.ti -5
stdaddrs.h	\c
Defines some standard addresses and offsets, and the contents of
some addresses.
.in -10
.pg
C source files:
.in +10
.sp
.ti -5
csi.c	\c
Command string interpreter (CSI).
.sp
.ti -5
diread.c	\c
Simulates non-file-structured reads of DK:, for the directory
section of the device only.
.sp
.ti -5
info.c	\c
Various informatory programmed requests, e.g. GTIM, DATE, GTJB, and GVAL.
.sp
.ti -5
init.c	\c
Main, initialization, and RT-11 program loading.
.sp
.ti -5
io.c	\c
The emulated I/O system.
.sp
.ti -5
misc.c	\c
Various system calls such as CHAIN,
EXIT, SETTOP, TWAIT, etc.
.sp
.ti -5
scrunch.c	\c
Not part of the emulator itself, the source for the scrunch
command mentioned above.
.sp
.ti -5
syscall.c	\c
RT-11 programmed request (system call) decoding.
Decodes the EMT and calls the appropriate routine.
.sp
.ti -5
time.c	\c
A stripped down version of the UNIX library routine "localtime".
The library version can be used, this one is simply smaller.
.sp
.ti -5
trap.c	\c
Catches various traps, and either calls user trap handlers, syscall,
or produces error messages.
.sp
.ti -5
tty.c	\c
TTYIN, TTYOUT, and PRINT.

.sp
.ti -5
utils.c	\c
Useful utilities, radix 50 conversion, getchar, putchar.
.in -10
.se "Trap Handling"
.pg
The primary function of the RT-11 emulator is to load in an RT-11
program, and then to interpret various traps which it generates.
The RT-11 system call instruction is the EMT.
The emulator arranges to catch this and other traps, and interprets
them just as the real RT-11 would.
.pg
The emulator arranges to catch traps by a call to
.it signal.
This routine is very similar to the standard UNIX library routine.
It is in "assem3.s".
The main changes to 
.it signal
involve stack switching when the trap occurs (the emulator's stack
is not the same as the user's stack area) and handling of completion
routine calling and branching to user trap routines when the emulator
returns from the caught trap.
A global variable is set so that the rest of the emulator code
can locate and manipulate the user's stack.
.pg
When a trap is taken, the emulator checks to see if the user has asked
to handle the trap (via TRPSET or SFPA).
If so, an interrupt is simulated to the user's trap routine.
Otherwise, the trap vector location is checked to see if a non-zero
program counter has been supplied.
If so, an interrupt is simulated.
Otherwise the program stops with an error message.
.pg
When an EMT trap is taken,
the emulator decodes the EMT instruction, decides the type of
system call, and calls the appropriate routine.
.pg
If the "trapcatch" feature is installed in UNIX (see below), then
the EMT trap entry also handles user-executed TRAP instructions.
The instruction op-code is examined to see if it is a TRAP, and if so
the appropriate action is taken.
.se "Core Layout"
.pg
The emulator's core area is organized much like that of RT-11.
The user loads into low core, and the emulator is located at the top
of memory.
UNIX assumes that the "I/O page" is the normal stack area
(see Fig. 1), but under the emulator the SP points to a lower area in core.
There is a small amount of accessible memory at the very top address
(where the default UNIX stack lies).
When the emulator starts it moves the SP out of the "I/O page"
to a location just below the emulator code.
However, the initial stack memory remains in the process address space.
Most references to the I/O page are caught, except references to the very
top.
(E.g. an attempt to reference the PS would not be detected.)
The user could accidentally point the stack pointer to the high (I/O) page,
which would also not be detected.
.pg
.nf
.sp
.in +8
.ne 12
.cs R 24
-----------   0177776
| stack   |
|    |    |
|    |V    |
-----------  <-- Hole in addresses in virtual memory
|    |^    |
| data,   |
| text    |
-----------   0

.in -8
.ce
Figure 1
.fi
.cs R
.pg
Figure 1 shows the normal core layout of a UNIX process.
The stack grows down from the top as required.
(It never grows smaller, even when the SP goes back down.)
The text-data is loaded at the start, and may grow larger or smaller.
There is a "hole" in virtual memory between stack and data, which are physically
contiguous.
.pg
Figure 2 shows the RT-11 emulator core layout.
The "I/O" page is the top segmentation register which is the usual location
of the normal
UNIX stack.
The emulator is at the top of accessible memory, and the program is located
in the remaining low memory.
This is very similar to the normal RT-11 layout.
The "fixed offsets" start at 0220 above the "load point" of the
emulator.
The area between the load point and the start of the fixed offsets is
used as a stack area.
In addition, another 200 bytes before the load point is used for stack.
The user program is told that this is the location of the "USR", which
is always "LOCKed".
The process image is always 56K bytes in length, to simulate the maximum
size RT-11 machine.
.sp
.nf
.lg 0
.in +8
.ne 25
.cs R 24
----------------   0177776
|     I/O      |         } Initial stack not used
|     page     |         } Not in address space
----------------   0160000
|              |
|  Emulator    |
|              |
----------------
| Fixed offsets|
---------------- -<-- Load Point + 0220 (First offset)
|   Stack      |
---------------- -<-- "Load Point" (Stored in location 054)
|   Stack      | -<-- Simulated LOCKed USR
----------------
|    Free      |
|   Memory     |
----------------
|              |
|    User      |
|   Program    |
----------------
|   Vectors    |
----------------  0

.in -8
.lg
.ce
Figure 2
.cs R
.sp
.fi
.sp
.pg
When the emulator is first loaded, it is in "scrunched" form.
In this form, the emulator has been compiled for the high addresses,
but has been moved down to the lowest address.
This saves space in the "a.out" file, and reduces the number of
disk reads required to start the emulator.
When the emulator starts, it moves itself up to the top if necessary.
.se "I/O System"
.pg
Most of the work in the I/O system is done by the routines
.it findfile,
.it openfile,
and
.it rtio.
.pg
.it Findfile
first converts a radix-50 filename
to ascii, and then checks the "device".
If the device is "LP:", it pipes, forks, and starts up a spooler
process.
If the device is "TT:", it doesn't do much of anything.
If the device is "DK:", it tries (via
.it openfile)
to locate the file in the local "dk" directory, and
then it tries the system-wide directory ("/lib/rt11/").
.pg
.it Openfile
either creates or opens the file.
If it creates it (i.e. ENTERs it) the file size for the channel
is defined by the user.
If the file is opened, the file size is the actual size.
.it Openfile
attempts to open a file for both reading and writing, but it
will open for read-only if that is dictated by UNIX file protection.
.pg
All the information about open channels is contained in the
.it chan
array.
Since there are more channels than there are UNIX file descriptors,
enough information is kept to allow files to be reopened.
Thus there does not have to be an open file for each active channel.
The routine
.it getfdes
frees up a file descriptor for use when necessary.
File descriptors associated with "LP:" are never closed, since
that would terminate the input to the spooler.
If one tried to open 10 channels, all using the line printer, this
would fail.
The standard input and output are never closed.
.pg
.it Rtio
performs the actual I/O.
Currently the various actions for different devices are all coded as part
of
.it rtio.
If more devices are implemented, this should be changed to be table
driven.
The main complications concern reading from the "TT:" device, and padding
READs out to block boundaries.
.it Rtio
arranges to call a completion routine, if necessary.
.se "Possible Upgrades"
.pg
This section discusses the implementation of some possible future upgrades.
.pg
In special tty input mode,
RT-11 provides a feature that allows an asynchronous indication that
a CNTL-C has been typed.
Under UNIX, the interrupt character is passed along just like any
other.
This is not usually a problem for TECO, but might be for BASIC, if the user
produces any infinite loops.
Unfortunately, there does not seem to be any good way around this, nor
does there seem to be any good way to implement SCCA.
.pg
BASIC may not really need to be in special input mode.
It seems to merely implement a more verbose line editing convention.
If the entry into special mode can be suppressed, BASIC may run
with no problems.
This has not been tried yet.
.pg
It may be desirable to implement the XM monitor.
To do this simply requires simulating the extended memory in a file.
Whenever the window is moved, the previous window is written out to
the file, and the new window is read in.
.se "Changes for UNIX Version 7"
.pg
Eventually, Version 7 of UNIX will be released.
The emulator compiles and runs under Version 6, and will run on either
an 11/40 or an 11/45.
Few changes will be necessary for Version 7.
Since the emulator has a number of machine dependant sections, there
may be code which has to be modified to compile under the new compiler.
(The new compiler is a bit stricter about some constructs.
We have tried to produce code which will compile under the "Version 7"
compiler, as well as under the oldest "Version 6" compilers.
It is not possible to test it under all versions of the compiler.)
.pg
Few system calls are used, and most of those will not change in V7.
There is one call to
.it seek,
one call to
.it execl,
and two calls to
.it stat.
There are also calls to
.it stty
and
.it gtty
to implement special mode tty input.
These will all be somewhat different in Version 7.
The emulator supplies its own assembly language version of
.it signal.
The emulator supplies its own
.it getchar,
.it putchar,
and
.it printf
(the latter to save space)
so there will be no problems with the new I/O library.
.se "Installing the Emulator"
.pg
NOTE:
Additional installation instructions are found in "read_me" files
in the source.
These should also be consulted.
.pg
Before installing the emulator, a few system dependant changes may be
made in the source.
If your machine has the 11/45 FPU, include "FPP" in the definition
of "STDCONFIG" in "stdaddrs.h".
If your machine is too small to run a full-sized copy of the emulator,
the symbol "MEMSIZE" in "assem0.s" may be adjusted.
If any users will require more than 280 files per "dk" directory,
the symbol DIRSEGS in "diread.c" should be adjusted.
There are 72 file slots per segment.
DIRSEGS should be as small as is practical, because the algorithm used
to simulate the directory structure is somewhat inefficient, and takes more
time if there are more files.
.pg
The emulator looks for the directory "/lib/rt11" for its error file,
and for system-wide "dk" directories.
If you wish this to be elsewhere,
modify
.it rtlib
in "io.c" and
.it efile
in "utils.c".
.pg
The emulator calls upon the line printer spooler in "rtio."
If your spooler is not installed as "/bin/opr", change the string
.it spooler.
.pg
If you are not in the Eastern time zone, the variables
.it timezone
and
.it daylight
in "time.c"
may require modifcation.
The routine in "time.c" is a stripped down version of
the standard UNIX library routine
.it localtime.
It is supplied in order to make the emulator smaller.
The standard routine would work just as well, but would take up more space.
.pg
The source directory contains a "run" shell file which does
everything necessary to compile the emulator.
The resulting "a.out" is suitable for installation in /bin/ru.
The resulting "errs" file is suitable for installation in /lib/rt11/errs.
.pg
The final step is to install some RT-11 software in /lib/rt11/dk0.
All of the standard software should be installed, e.g.
macro.sav, sysmac.sml, pip.sav, help.*, etc.
The files "*.sys" are
.ul
not
used, and need not be installed.
.pg
The directory "test" contains some programs that excercise the emulator
and various RT-11 programs.
You might like to try these out.
.pg
Once the emulator is installed, one needs a few more programs.
The source for
.it rted
should be compiled and installed as "/bin/rted".
(It can also be installed as "ed", with "rted" being a link.
It looks at its zeroth argument to decide what to do.)
.it Rted
handles translation to upper case and carriage returns on the ends of
lines, and is useful for editing RT-11 source programs.
The directory "misc" contains the source.
.pg
One usually also needs some means of reading actual RT-11 media, or
communicating with RT-11 machines.
Various programs are available in the UNIX community, including
.it rtpip.
A copy of
.it rtpip
may be found in the "misc" directory.
.su "UNIX System Modifications"
.pg
A modification to UNIX is required if you wish to run EDIT.SAV,
certain Fortran programs, or any other program which uses TRAP instructions.
The TRAP instruction is the UNIX system call instruction, and under a
standard system this instruction cannot be intercepted.
If an RT-11 program executes a TRAP, undefined random results will occur.
The "misc" directory provides the appropriate system modificatons
(less than 20 lines of code) to allow TRAP instructions to be caught
by the emulator.
The source is contained in "misc/unix".
Because there are so many different versions of UNIX in the world, one
should not simply install the source files.
Instead, examine the changes, and make the appropriate modifications
to your own system source.
All the changes are marked by comments which contain the characters "RT11".
.pg
The installation of these modifications is recommended, since it is very
difficult to debug RT-11 programs that are executing TRAPs.
If you do not install the modification, you may run the Fortran compiler,
but you should not run the compiled code, unless you are sure that the code
contains no errors of any sort.
(The Fortran run-time support executes TRAP instructions when it detects
various exceptional conditions.)
EDIT does the same kind of thing, so one should use TECO or the UNIX text
editor instead.
.pg
The "trapcatch" system call is system call number 59.
That slot is unused on a standard system.
If your system already uses that slot,
you should pick another entry, and
assem3.s should be appropriately
modified.
.pg
If you do not install "trapcatch" and system call 59 is unused, the emulator does
.ul
not
require modification.
It executes system call number 59, which will fail.
The emulator ignores the failure, and proceeds with normal execution.
