README file for PDP-8/e emulator
--------------------------------

The files in this directory make up the documentation for my emulator:

report.txt	This emulator was a project for a course at Cambridge
		University. This file is a text version of the end of course
		report.
report.doc	This is the same document formatted for Microsoft Word for
		Windows version 2.0
pdp8e.ps	This is the colour image referred to in the report in
		Postscript form
expected.errors A list of the expected warning messages when compiling
figures1.ps )	The other figures from the report in Postscript form
figures2.ps )


Total disc space needed: about 3 Mb


Program Structure
-----------------

The program consists of two separately linked libraries, and the executable
program itself.

The libraries are:

pdp8lib: a general utilities and basic objects library


buslib: library holding all the system bus modules and the code on which they
        depend

        

Compilation Instructions
------------------------

To compile this emulator you need Modula-3 installed on your system, plus
a copy of X. My version was compiled on a Sun SPARCstation running SunOS 5.3,
using Modula-3 version 3.3 and X version 11 release 5.

During each compilation stage a large number of warning messages will be shown.
Those expected are listed in the file expected.errors

The Modula-3 system builds executables in the SOLsun directory off the
directory from which the m3build command is issued.


To compile the pdp8lib library

Change directory so that the current directory is pdp8e/pdp8lib
Compile using the command: m3build


To compile the buslib library

Change directory so that the current directory is pdp8e/buslib
(The object and library files will be placed in pdp8e/buslib/SOLsun.)
Compile using the command: m3build


To compile the BINtoCore program

Ensure that the pdp8lib library has been compiled.
Make pdp8e/BINtoCore the current directory.
Compile using the command: m3build


To compile the MemMake program

Ensure that the pdp8lib library has been compiled.
Make pdp8e/MemMake the current directory.
Compile using the command: m3build


To compile the MemDisp program

Ensure that the pdp8lib library has been compiled.
Make pdp8e/MemDisp the current directory.
Compile using the command: m3build


To compile the emulator program

Make pdp8e/Emulator the current directory.
Compile using: m3build


Running the emulator

Before running the emulator, ensure that the environment variable
LD_LIBARY_PATH had been set to point to the two libraries. For example, my
system sets:

LD_LIBRARY_PATH=/home/sgp13/toJones/m3/pdp8lib/SOLsun:/home/sgp13/toJones/m3/buslib/SOLsun


To run the basic emulator use the command:

pdp8e

After a few seconds the message

PDP8/e keyboard interface : waiting for input

should appear. At this point type HE to get a list of commands.


I have included some programs in the pdp8e/software directory. Any .bin file
is in BIN format (see PDP-8/e documentation) and may be converted into a
memory image for my emulator using the BINtoCore program.

For example, to convert u8-388.bin into a memory image, use the following
command while the current directory is pdp8e/software:

BINtoCore u8-388.bin u8-388.image

For each program I have included an appropriate initialisation file, so to
run the emulator with the u8-388 program preloaded, use the command

pdp8e -i u8-388.init


To run FOCAL it is necessary to construct the memory image from a memory dump
file as the BIN file was not available. To do this, use

MemMake focal.dump focal.image

and run the emulator using

pdp8e -i focal.init


Running a program:

To choose which user interface to use, set the 'UserInterface=' in the
[AutoExec] section of the initialisation file to 'Keyboard' or 'Graphical'.
It is also possible to run without a user interface, by using the other
parameters in this section. The emulator program will then exit when a halt
instruction is encountered.


Keyboard user interface:

The following will certainly work for u8-388 (which expects a year (e.g. 1995)
as its input. I should work for the other programs except FOCAL.

It will be necessary to specify input and output files to emulate the teletype
keyboard and printer. This is done by altering the names specified on the lines
starting 'Keyboard=' and 'Teletype=' in the [IOFiles] section of the
initialisation file. All programs start at location 0200 (octal), so having
started the emulator, type

SR 0200
AL
GO

The best way to monitor progress is to start another process and look at the
contents of the file named as the 'Teletype' file.


Graphical user interface:

Set the switch register to 0200 (octal) by clicking the mouse on the switch
marked 4. Make this the current address by clicking on the ADDR LOAD button.
Start the emulator by clicking on the CONT button.


The programs:

u8-388: prints a calendar
test1 ) DEC's diagnostic tests : see separate documentation test.info.1
test2 ) and test.info.2 in the software directory.
test3 ) My emulator has been tested on the first two of these.
test4 )
focal   an interpreted language supplied by DEC.


FOCAL

When starting FOCAL it asks whether to retain the maths functions. If you don't
then there's more program space. You must type 'YES' or 'NO' in full.

FOCAL is very like BASIC. For an example, try the program:

1.1 TYPE "HELLO WORLD!"!
1.2 GOTO 1.1

Note the trailing '!' on line 1.1

Then type

GO


Note this should all be typed in while the cursor is over the window which
makes up the lower portion of the display.
(To put it out of its misery type Ctrl-C a couple of times if using the
graphical UI.)


Cross-assembler

If you want to write in assembler then there's a cross-assembler which was
originally written by Doug Jones of the University of Iowa. This is in C and
is in the pdp8e/c/cross-assembler directory. It produces output in BIN format,
which can then be converted as described above.


Diagnostic messages

If you want to delve into the source of my emulator you may want to use my
diagnostic message system. In the current version all diagnostic messages have
been commented out. To reinstate them compile the uncomment program (there
is a parallel comment program to remove them again) as described in the
README file in pdp8e/c/commenter

This takes a file list as its parameter, so you can specify the source files
which you want to produce comments. To enable commenting you'll also need to
tinker with the initialisation file ... see Appendix 3 of my report for
details. The message type to specify in the file is the string found in the
varname array in Diag.i3. By default the Error type starts enabled.
Some examples of what needs doing have been left in the supplied initialisation
files ... just remove the #, which is a comment character, to reinstate them.

