simh_doc.txt

To:	Users
From:	Bob Supnik
Subj:	Simulator Usage, V3.1
Date:	15-Dec-2003

			COPYRIGHT NOTICE

The following copyright notice applies to both the SIMH source and binary:

   Original code published in 1993-2003, written by Robert M Supnik
   Copyright (c) 1993-2003, Robert M Supnik

   Permission is hereby granted, free of charge, to any person obtaining a
   copy of this software and associated documentation files (the "Software"),
   to deal in the Software without restriction, including without limitation
   the rights to use, copy, modify, merge, publish, distribute, sublicense,
   and/or sell copies of the Software, and to permit persons to whom the
   Software is furnished to do so, subject to the following conditions:

   The above copyright notice and this permission notice shall be included in
   all copies or substantial portions of the Software.

   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
   ROBERT M SUPNIK BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
   IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

   Except as contained in this notice, the name of Robert M Supnik shall not
   be used in advertising or otherwise to promote the sale, use or other dealings
   in this Software without prior written authorization from Robert M Supnik.

This memorandum documents SIMH simulators.  These simulators are freeware;
refer to the license terms above for conditions of use.  Support is not
available.  The best way to fix problems or add features is to read and
modify the sources yourself.  Alternately, you can send Internet mail to
bsupnik@us.inter.net, but a response is not guaranteed.

The simulators use a common command interface.  This memorandum describes
the features of the command interface.  The details of each simulator are
documented in separate, machine-specific memoranda.


1. Compiling And Running A Simulator

The simulators have been tested on VAX VMS, Alpha VMS, Alpha UNIX,
NetBSD, FreeBSD, OpenBSD, Linux, Solaris, Windows 9x/Me/NT/2000, MacOS
9 and X, and OS/2.  Porting to other environments will require changes
to the operating system dependent code in scp_tty.c, scp_sock.c, and
sim_ether.c.

The simulator sources are provided in a zip archive and are organized
hierarchically.  Source files for the simulator libraries are in the
top level directory; source files for each simulator are in individual
subdirectories.  Note that the include files in the top level directory
are referenced from the subdirectories, without path identifiers.  Your
build tool needs to search the top level directory for include files not
found in the simulator-specific directory, or you will have to copy all
files from the subdirectories into the master directory.  File manifests
for each simulator are given in that simulator's documentation.

The simulators recognize or require a few compile-time #defines:

- The 18b simulators require that the model name be defined as part
  of the compilation command line (i.e., PDP4 for the PDP-4, PDP7
  for the PDP-7, PDP9 for the PDP-9, PDP15 for the PDP-15).

- The PDP-10 simulator uses 64b integer variables, requiring that
  USE_INT64 be defined as part of the compilation command line.
  Since 64b integer declarations vary, sim_defs.h has conditional
  declarations for Windows (_int64) and Digital UNIX (long).  The
  default is GNU C (long long).  If your compiler uses a different
  convention, you will have to modify sim_defs.h.

- The PDP-10, PDP-11, and VAX simulators share common peripherals.
  To distinguish the target system, one of three variables must be
  defined on the command line: VM_PDP10 for the PDP-10; VM_PDP11
  for the PDP-11; or VM_VAX for the VAX.

- The PDP-11 and VAX simulators optionally support Ethernet.  To
  include Ethernet emulation, USE_NETWORK must be defined as part
  of the compilation command line.  At present, Ethernet support is
  available only on Windows, Linux, NetBSD, OpenBSD, and Alpha VMS.

- The PDP-11 and VAX simulators optionally support disks and serial
  devices files greater than 2GB.  To include large device support,
  both USE_INT64 and USE_ADDR64 must be defined as part of the
  compilation command line.

To start the simulator, simply type its name.  (On version of VMS
prior to 6.2, the simulators must then be defined as foreign commands
in order to be be started by name.)  The simulator recognizes one
switch, -Q; if specified, certain informational messages are suppressed.

The simulator interprets the arguments on the command line, if any,
as the file name and arguments for a DO command:

	% pdp10 {<startup file> {arg,arg,...}}(cr)

If no file is specified on the command line, the simulator looks for
an startup file consisting of the simulator name (including its path
components) plus the extension .ini.  If a startup file is specified,
either on the command line or implicitly via the .ini capability, it
ishould contain a series of non-interactive simulator command, one
per line.  These command can be used to set up standard parameters,
for example, disk sizes.

After initializing its internal structures and processing the startup
file (if any), the simulator types out its name and version and then
prompts for input with:

	sim>

1.1 Compiling Under UNIX/Linux

The sources originate on a Windows system and have cr-lf at the end of
every line.  For use on UNIX or Mac, the sources must be converted to
UNIX text conventions.  This can be done with the UNIX UNZIP utility
(unzip -a).

The supplied makefile will compile the simulators for UNIX systems
which support the POSIX TERMIOS.  The VAX and PDP-11 can be compiled
with or without Ethernet support.  To compile without Ethernet support:

	gmake {target|ALL|clean}

To compile with Ethernet support:

	gmake USE_NETWORK=1 {target|ALL|clean}

Notes for hand compilation:

- The default UNIX terminal handling model is the POSIX TERMIOS
  interface, which is supported by Linux, Mac OS/X, and Alpha UNIX.
  If your UNIX only supports the BSD terminal interface, BSDTTY
  must be defined as part of the compilation command line.

- The PDP-8, PDP-11, 18b PDP, PDP-10, and Nova simulators use the
  math library.  If your UNIX does not link the math library
  automatically, you must add -lm to the compilation command line.

Examples:

- PDP-11 under TERMIOS UNIX:

	% cc -DVM_PDP11 pdp11_*.c scp*.c sim_*.c -lm -o pdp11

- PDP-9 under TERMIOS UNIX:

	% cc -DPDP9 pdp18b_*.c scp*.c sim_*.c -lm -o pdp9

- PDP-10 under BSD terminal UNIX:

	% cc -DVM_PDP10 -DUSE_INT64 -DBSDTTY pdp10_*.c scp*.c sim_*.c -lm -o pdp10

1.2 Compiling Under Windows

1.2.1 Compiling PDP-11 and VAX with Ethernet Support

The Windows-specific Ethernet code uses the WinPCAP 3.0 package.
This package for windows simulates the libpcap package that is freely
available for Unix systems.

WinPCAP must be installed prior to building the PDP-11 and VAX
simulators with Ethernet support.

- Download V3.0 from http://winpcap.polito.it.
- Install the package as directed.
- Copy the required .h files (bittypes.h, devioctl.h, ip6_misc.h,
  packet32.h, pcap.h, pcap-stdinc.h) from the WinPCAP 3.0 developer's
  kit to the top level simulation directory.
- Get the required .lib files (packet.lib, wpcap.lib) from the WinPCAP
  3.0 developer's kit.  If you're using Borland C++, use COFF2OMF to
  convert the .lib files into a format that can be used by the compiler.
  Then move the libraries to the standard library directory.
- Add -DUSE_NETWORK to the compilation command lines for the PDP-11
  and VAX.

1.2.2 Compiling Under MinGW

MinGW (Minimum GCC for Windows) is a free C compiler available from
http://www.mingw.org.  The distribution includes a batch file
(build_mingw.bat) that will build all the simulators from source.
By default, the PDP-11 and VAX are built without Ethernet support.  To
enable Ethernet support, install WinPCAP as described in the previous
section, and then use the alternative batch file (build_mingw_ether.bat).

1.2.3 Compiling Under Visual C++

Each simulator must be organized as a separate Visual C++ project. 
Starting from an empty console application,

- Add all the files from the simulator file manifest to the project.
- Open the Project->Settings dialog box.
- On the C/C++ tab, Category: General, add any required preprocessor
  definitions (for example, USE_INT64).
- On the C/C++ tab, Category: Preprocessor, add the top level
  simulation directory to the Additional Include Directories.  For
  the VAX and PDP-10, you must also add the PDP-11 directory.
- On the Link tab, add wsock32.lib at the end of the list of
  Object/Module Libraries.
- If you are building the PDP-11 and VAX with Ethernet support, you
  must also add the WinPCAP libraries (packet.lib, wpcap.lib) to the
  list of Object/Module libraries.

If you are using Visual C++ .NET, you must turn off /Wp (warn about
potential 64b incompatibilities); otherwise, the compilations will
generate a lot of spurious conversion warnings.

1.2.4 Compiling Under Borland C++

The Borland C++ compiler generates lots of spurious warnings about
missing function prototypes and conversions.  All of these warnings
can be safely ignored.

1.3 Compiling Under OpenVMS

Compiling on OpenVMS requires DEC C.  The simulators that require
64b (PDP-10 and VAX) will not compile on OpenVMS/VAX.  The SIMH
distribution includes an MMS command file descrip.mms that will
build all the simulators from source.  An example of hand compilation:

- PDP-8 under VMS:

	$ cc scp*.c,sim_*.c,[.pdp8]pdp8*.c
	$ link/exec=pdp8 scp*.obj,sim_*.obj,[.pdp8]pdp8*.obj

1.4 Compiling Under MacOS

The simulators have been tested on both MacOS 9 (with Codewarrior)
and MacOS/X (with Apple's tools).

1.5 Compiling Under OS/2

Socket support requires the EMX compiler.

2. Simulator Conventions

A simulator consists of a series of devices, the first of which is
always the CPU.  A device consists of named registers and one or more
numbered units.  Registers correspond to device state, units to device
address spaces.  Thus, the CPU device might have registers like PC,
ION, etc, and a unit corresponding to main memory; a disk device might
have registers like BUSY, DONE, etc, and units corresponding to individual
disk drives.  Except for main memory, device address spaces are simulated
as unstructured binary disk files in the host file system.  The SHOW
CONFIG command displays the simulator configuration.

A simulator keeps time in terms of arbitrary units, usually one time unit
per instruction executed.  Simulated events (such as completion of I/O)
are scheduled at some number of time units in the future.  The simulator
executes synchronously, invoking event processors when simulated events
are scheduled to occur.  Even asynchronous events, like keyboard input,
are handled by polling at synchronous intervals.  The SHOW QUEUE command
displays the simulator event queue.

3. Commands

Simulator commands consist of a command verb, optional switches, and
optional arguments.  Switches take the form:

	-<letter>{<letter>...}

Multiple switches may be specified separately or together: -abcd or
-a -b -c -d are treated identically.  Verbs, switches, and other
input (except for file names) are case insensitive.

Any command beginning with semicolon (;) is considered a comment and
ignored.

3.1 Loading and Saving Programs

The LOAD command (abbreviation LO) loads a file in binary paper-tape
loader format:

	sim> load <filename> {implementation options}(cr)

The types of formats supported are implementation specific.  Options
(such as load within range) are also implementation specific.

The DUMP command (abbreviation DU) dumps memory in binary paper-
tape loader format:

	sim> dump <filename> {implementation options}(cr)

The types of formats supported are implementation specific.  Options
(such as dump within range) are also implementation specific.

3.2 Saving and Restoring State

The SAVE command (abbreviation SA) save the complete state of the
simulator to a file.  This includes the contents of main memory and
all registers, and the I/O connections of devices:

	sim> save <filename>(cr)

The RESTORE command (abbreviation REST, alternately GET) restores a
previously saved simulator state:

	sim> restore <filename>(cr)

Note: SAVE file format compresses zeroes to minimize file size.

3.3 Resetting Devices

The RESET command (abbreviation RE) resets a device or the entire
simulator to a predefined condition:

	sim> RESET(cr)			-- reset all devices
	sim> RESET ALL(cr)		-- reset all devices
	sim> RESET <device>(cr)		-- reset specified device

Typically, RESET stops any in-progress I/O operation, clears any
interrupt request, and returns the device to a quiescent state.  It
does not clear main memory or affect I/O connections.

3.4 Connecting and Disconnecting Devices

Except for main memory, simulated unit address spaces are simulated
as unstructured binary disk files in the host file system.  Before
using a simulated unit, the user must specify the file to be accessed
by that unit.  The ATTACH (abbreviation AT) command associates a unit
and a file:

	sim> ATTACH <unit> <filename>(cr)

If the file does not exist, and the -e switch was not specified, a
new file is created, and an appropriate message is printed.  If the
-e switch was specified, a new file is not created, and an error
message is printed.

If the -r switch is specified, or the file is write protected, ATTACH
tries to open the file read only.  If the file does not exist, or the
unit does not support read only operation, an error occurs.  Input-
only devices, such as paper-tape readers, and devices with write lock
switches, such as disks and tapes, support read only operation; other
devices do not.  If a file is ATTACHed read only, its contents can be
examined but not modified. 

For simulated magnetic tapes, the ATTACH command can specify the
format of the attached tape image file:

	sim> ATTACH -f <tape_unit> <format> <filename>(cr)

The currently supported tape image file formats are:

	SIMH		SIMH simulator format
	E11		E11 simulator format
	TPC		TPC format

The tape format can also be set with the SET command prior to ATTACH:

	sim> SET <tape_unit> FORMAT=<format>(cr)
	sim> ATT <tape_unit> <filename>(cr)

The format of an attached file can be displayed with the SHOW command:

	sim> SHOW <tape_unit> FORMAT(cr)

For Telnet-based terminal emulators, the ATTACH command associates the
master unit with a TCP/IP port:

	sim> ATTACH <unit> <port>(cr)

The port is a decimal number between 1 and 65535 and should not used
by standard TCP/IP protocols.

The DETACH (abbreviation DET) command breaks the association between
a unit and a file, or between a unit and a port:

	sim> DETACH ALL(cr)		-- detach all units
	sim> DETACH <unit>(cr)		-- detach specified unit

The EXIT command performs an automatic DETACH ALL.

3.5 Examining and Changing State

There are four commands to examine and change state:

	EXAMINE (abbreviated E) examines state
	DEPOSIT (abbreviated D) changes state
	IEXAMINE (interactive examine, abbreviated IE) examines state
		and allows the user to interactively change it
	IDEPOSIT (interactive deposit, abbreviated ID) allows the user
		to interactively change state

All four commands take the form

	command {modifiers} <state list>

Deposit must also include a deposit value at the end of the command.

There are four kinds of modifiers: switches, device/unit name, search
specifiers, and for EXAMINE, output file.  Switches have been described
previously.  A device/unit name identifies the device and unit whose
address space is to be examined or modified.  If no device is specified,
the CPU (main memory)is selected; if a device but no unit is specified,
unit 0 of the device is selected.

Search specifiers provide criteria for testing addresses or registers
to see if they should be processed.  A specifier consists of a logical
operator, a relational operator, or both, optionally separated by spaces.

	{<logical op> <value>} <relational op> <value>

where the logical operator is & (and), | (or), or ^ (xor), and the
relational operator is = or == (equal), ! or != (not equal), >=
(greater than or equal), > (greater than), <= (less than or equal), or
< (less than).  If a logical operator is specified without a relational
operator, it is ignored.  If a relational operator is specified without
a logical operator, no logical operation is performed.  All comparisons
are unsigned.

The output file modifier redirects command output to a file instead of
the console.  An output file modifier consists of @ followed by a
valid file name.

Modifiers may be specified in any order.  If multiple modifiers of the
same time are specified, later modifiers override earlier modifiers.
Note that if the device/unit name comes after the search specifier,
the values will interpreted in the radix of the CPU, rather than of the
device/unit.

The "state list" consists of one or more of the following, separated
by commas:

	register		the specified register
	register[sub1-sub2]	the specified register array locations,
				starting at location sub1 up to and
				including location sub2
	register[sub1/length]	the specified register array locations,
				starting at location sub1 up to but
				not including sub1+length
	register[ALL]		all locations in the specified register
				array
	register1-register2	all the registers starting at register1
				up to and including register2
	address			the specified location
	address1-address2	all locations starting at address1 up to
				and including address2
	address/length		all location starting at address up to
				but not including address+length
	STATE			all registers in the device
	ALL			all locations in the unit

Switches can be used to control the format of display information:

	-a			display as ASCII
	-c			display as character string
	-m			display as instruction mnemonics
	-o			display as octal
	-d			display as decimal
	-h			display as hexidecimal

The simulators typically accept symbolic input (see documentation with
each simulator).

Examples:

	sim> ex 1000-1100	-- examine 1100:1100
	sim> de PC 1040		-- set PC to 1040
	sim> ie 40-50		-- interactively examine 40:50
	sim> ie >1000 40-50	-- interactively examine the subset
				   of locations 40:50 that are >1000
	sim> ex rx0 50060	-- examine 50060, RX unit 0
	sim> ex rx sbuf[3-6]	-- examine SBUF[3] to SBUF[6] in RX
	sim> de all 0		-- set main memory to 0
	sim> de &77>0 0		-- set all addresses whose low order
				   bits are non-zero to 0
	sim> ex -m @memdump.txt 0-7777	-- dump memory to file

Note: to terminate an interactive command, simply type a bad value (eg,
XYZ) when input is requested.

3.6 Running Programs

The RUN command (abbreviated RU) resets all devices, deposits its argument
(if given) in the PC, and starts execution.  If no argument is given,
execution starts at the current PC.

The GO command does NOT reset devices, deposits its argument (if given)
in the PC, and starts execution.  If no argument is given, execution
starts at the current PC.

The CONT command (abbreviated CO) does NOT reset devices and resumes
execution at the current PC.

The STEP command (abbreviated S) resumes execution at the current PC
for the number of instructions given by its argument.  If no argument
is supplied, one instruction is executed.

The BOOT command (abbreviated BO) bootstraps the device and unit given
by its argument.  If no unit is supplied, unit 0 is bootstrapped.  The
specified unit must be attached to a file.

3.7 Stopping Programs

Programs run until the simulator detects an error or stop condition, or
until the user forces a stop condition.

3.7.1 Simulator Detected Stop Conditions

These simulator-detected conditions stop simulation:

	- HALT instruction.  If a HALT instruction is decoded,
	  simulation stops.

	- Breakpoint.  The simulator may support breakpoints (see
	  below).

	- I/O error.  If an I/O error occurs during simulation of an
	  I/O operation, and the device stop-on-I/O-error flag is set,
	  simulation usually stops.

	- Processor condition.  Certain processor conditions can stop
	  simulation; these are described with the individual simulators.

3.7.2 User Specified Stop Conditions

Typing the interrupt character stops simulation.  The interrupt character
is defined by the WRU (where are you) register and is initially set to
005 (^E).

3.7.3 Breakpoints

A simulator may offer breakpoint capability.  A simulator may define
breakpoints of different types, identified by letter (for example, E
for execution, R for read, W for write, etc).  At the moment, most
simulators support only E (execution) breakpoints.

Associated with a breakpoint is a count and, optionally, one or more
actions.  Each time the breakpoint is sprung, the associated count is
decremented.  If the count is less than or equal to 0, the breakpoint
occurs; otherwise, it is deferred.  When the breakpoint occurs, the
optional actions are automatically executed.

A breakpoint is set by the BREAK command:

	sim> BREAK {-types} <addr range>{[count]},{addr range...}
	     {;action;action...}

If no type is specified, the simulator-specific default breakpoint
type (usually E for execution) is used.  As with EXAMINE and DEPOSIT,
an address range may be a single address, a range of addresses low-high,
or a relative range of address/length.  Examples of BREAK:

	sim> break -e 200		-- set E break at 200
	sim> break 2000/2[2]		-- set E breaks at 2000,2001
					   with count = 2
	sim> break 100;ex ac;d mq 0	-- set E break at 100 with
					   actions EX AC and D MQ 0
	sim> break 100;			-- delete action on break at 100

Currently set breakpoints can be displayed with the SHOW BREAK command:

	sim> SHOW {-types} BREAK {ALL|<addr range>{,<addr range>...}}

Locations with breakpoints of the specified type are displayed.

Finally, breakpoints can be cleared by the NOBREAK command.

3.8 Setting Device Parameters

The SET command (abbreviated SE) changes the status of a device parameter:

	sim> SET <device> <parameter>{=<value}

or a unit parameter:

	sim> SET <unit> <parameter>{=<value>}

Most parameters are simulator and device specific.  Disk drives, for
example, can usually be set WRITEENABLED or write LOCKED; if a device
supports multiple drive types, the SET command can be used to specify
the drive type.

All devices recognize the following parameters:

	OCT		sets the data radix = 8
	DEC		sets the data radix = 10
	HEX		sets the data radix = 16

3.9 Displaying Parameters and Status

The SHOW CONFIGURATION command shows the simulator configuration and
the status of all simulated devices and units.

The SHOW DEVICES command shows the configuration of all simulated
devices.

The SHOW MODIFIERS command shows the modifiers available on all
simulated devices.

The SHOW QUEUE command shows the state of the simulator event queue.
Times are in "simulation units", typically one unit per instruction
execution, relative to the current simulation time.

The SHOW TIME command shows the number of time units elapsed since
the last RUN command.

The SHOW <device> command shows the status of the named simulated
device. SHOW <device> <parameter> shows the value of the named
parameter, if it can display a value.

The SHOW <unit> command shows the status of the named simulated unit.
SHOW <unit> <parameter> shows the value of the named parameter, if
it can display a value.

3.10 Altering The Simulated Configuration

In most simulators, the SET <device> DISABLED command removes the
specified device from the configuration.  A DISABLED device is
invisible to running programs.  The device can still be RESET but
it cannot be ATTAChed, DETACHed, or BOOTed.  SET <device> ENABLED
restores a disabled device to a configuration.

Most multi-unit devices allow units to be placed online or offline:

	sim> SET <unit> ONLINE
	sim> SET <unit> OFFLINE

When a unit is offline, it will not be displayed by SHOW DEVICE.

The console terminal normally runs in the controlling window.
Optionally,  the console terminal can be connected to a Telnet port.
This allows systems to emulate a VT100 using the built-in terminal
emulation of the Telnet client.

	sim> SET TELNET <port>		-- listen for console
					   Telnet connection on port
	sim> SET NOTELNET		-- disable console Telnet
	sim> SHOW TELNET		-- show console Telnet status

The standard device names can be supplemented with logical names.
Logical names must be unique within a simulator (that is, they cannot
be the same as an existing device name).  To assign a logical name
to a device:

	sim> ASSIGN device log-name	-- assign log-name to device

To remove a logical name:

	sim> DEASSIGN device		-- remove logical name

To show all logical names:

	sim> SHOW NAMES

3.11 Logging Console Output

Output to the console can be logged simultaneously to a file.  Logging
is enabled by the LOG command:

	sim> SET LOG <filename>		-- log console output to file

Logging is disabled by the NOLOG command:

	sim> SET NOLOG			-- disable logging

SHOW LOG displays whether logging is enabled or disabled.

3.12 Executing Command Files

The simulator can execute command files with the DO command:

	sim> DO <filename> {arguments...}	-- execute commands in file

The DO command allows command files to contain substitutable arguments.
The string %n is recognized as meaning argument n from the DO command
line. The character \ has the usual UNIX meaning of an escape character;
the next character is interpreted literally, even if it is % or \.
Arguments with spaces can be enclosed in matching single or double
quotation marks.

If the switch -V is specified, the commands in the file are echoed
before they are executed.

3.13 Executing System Commands

The simulator can execute operating system commands with the ! (spawn)
command:

	sim> ! <host operating system command>

If no operating system command is provided, the simulator attempts to
launch the host operating system's command shell.

3.14 Getting Help

The HELP command prints out information about a command or about all
commands:

	sim> HELP			-- print all HELP messages
	sim> HELP <command>		-- print HELP for command

3.15 Exiting The Simulator

EXIT (synonyms QUIT and BYE) returns control to the operating system.

Appendix 1: File Representations

All file representations are little endian.  On big endian hosts, the
simulator automatically performs any required byte swapping.

1. Hard Disks

Hard disks are represented as unstructured binary files of 16b data
items for the 12b and 16b simulators, of 32b data items for the 18b,
24b, and 32b simulators, and 64b for the 36b simulators.

2. Floppy Disks

PDP-8 and PDP-11 floppy disks are represented as unstructured binary
files of 8b data items.  They are nearly identical to the floppy disk
images for Doug Jones' PDP-8 simulator but lack the initial 256 byte
header.  A utility for converting between the two formats is easily
written.

3. Magnetic Tapes

Magnetic tapes are represented as unstructured binary files of 8b data
items.  Each record consists of a 32b record header, in little endian
format.  If the record header is not a special header, it is followed
by n 8b bytes of data, followed by a repeat of the 32b record header.
A 1 in the high order bit of the record header indicates an error in
the record. If the byte count is odd, the record is padded to even
length; the pad byte is undefined.

Special record headers occur only once and have no data.  The currently
defined special headers are:

	0x00000000		file mark (not repeated)
	0xFFFFFFFF		end of medium (not repeated)

Magnetic tapes are endian independent and consistent across simulator
families.  A magtape produced by the Nova simulator will appear to
have its 16b words byte swapped if read by the PDP-11 simulator.

SIMH can read and write E11-format magtape images.  E11 format differs
from SIMH format only for odd-length records; the data portion of E11
records is not padded with an extra byte.

SIMH can read TPC-format magtape images.  TPC format uses a 16b record
header, with 0x0000 denoting file mark.  The record header is not
repeated at the end of the record.  Odd-length records are padded with
an extra byte.

4. Line Printers

Line printer output is represented by an ASCII file of lines separated
by the newline character.  Overprinting is represented by a line ending
in return rather than newline.

5. DECtapes

DECtapes are structured as fixed length blocks.  PDP-1/4/7/9/15 DECtapes
use 578 blocks of 256 32b words.  Each 32b word contains 18b (6 lines)
of data.  PDP-11 DECtapes use 578 blocks of 256 16b words.  Each 16b word
contains 6 lines of data, with 2b omitted.  This is compatible with native
PDP-11 DECtape dump facilities, and with John Wilson's PUTR Program.  PDP-8
DECtapes use 1474 blocks of 129 16b words.  Each 16b word contains 12b
(4 lines) of data.  PDP-8 OS/8 does not use the 129th word of each block,
and OS/8 DECtape dumps contain only 128 words per block.  A utility,
DTOS8CVT.C, is provided to convert OS/8 DECtape dumps to simulator format.

A known problem in DECtape format is that when a block is recorded in
one direction and read in the other, the bits in a word are scrambled
(to the complement obverse).  The PDP-11 deals with this problem by
performing an automatic complement obverse on reverse writes and reads.
The other systems leave this problem to software.

The simulator represents this difference as follows.  On the PDP-11, all
data is represented in normal form.  Data reads and writes are not direction
sensitive;  read all and write all are direction sensitive.  Real DECtapes
that are read forward will generate images with the correct representation
of the data.

On the other systems, forward write creates data in normal form, while
reverse write creates data in complement obverse form.  Forward read (and
read all) performs no transformations, while reverse read (and read all)
changes data to the complement obverse.  Real DECtapes that are read forward
will generate data in normal form for blocks written forward, and complement
obverse data for blocks written in reverse, corresponding to the simulator
format.

Appendix 2: Debug Status

The debug status of each simulated CPU and device is as follows:

	system	PDP-8	PDP-11	Nova	PDP-1	18b PDP
device
CPU		y	y	y	y	y
FPU		-	y	-	-	h
EIS/CIS		-	h	-	-	-
console		y	y	y	y	y
paper tape	y	y	y	y	y
card reader	-	-	-	-	-
line printer	y	y	y	h	y
clock		y	y	y	-	y
extra terminal	y	y	y	-	y
hard disk	y	y	y	-	y
fixed disk	y	-	h	-	y
floppy disk	y	y	y	-	-
drum		-	-	-	h	h
DECtape		y	y	-	h	y
mag tape	y	y	y	-	h

	system	1401	2100	PDP-10	H316	VAX
device
CPU		y	y	y	h	y
FPU		-	y	y	-	y
EIS/CIS		-	y	y	-	-
console		h	y	y	h	y
paper tape	-	y	h	h	y
card reader	y	-	-	-	-
line printer	y	y	y	h	y
clock		-	y	y	h	y
extra terminal	-	y	y	-	y
hard disk	h	y	y	-	y
fixed disk	-	n	-	h	-
floppy disk	-	-	h	-	-
drum		-	n	-	-	-
DECtape		-	-	-	-	-
mag tape	y	y	y	h	y

	system	GRI-909	1620	i16	i32	SDS940
device
CPU		h	h	d	y	d
FPU		-	-	d	y	-
CIS		-	-	-	-	-
console		h	h	d	y	h
paper tape	h	h	d	y	h
card reader	-	h	-	-	-
line printer	-	h	d	y	h
clock		h	-	d	y	n
extra terminal	-	-	h	y	h
hard disk	-	h	d	y	h
fixed disk	-	-	-	-	h
floppy disk	-	-	d	d	-
drum		-	-	-	-	h
DECtape		-	-	-	-	-
mag tape	-	-	d	y	h

legend:		y = runs operating system or sample program
		d = runs diagnostics
		h = runs hand-generated test cases
		n = untested
		- = not applicable

Revision History (covering Rev 2.0 to present)

Starting with Rev 2.7, detailed revision histories can be found
in file sim_rev.c.

Rev 3.1, Dec, 03
	Added Alpha/VMS, FreeBSD, Mac OS/X Ethernet library support
	Added Eclipse floating point and interval timer support
	 (from Charles Owen)
	Added PDP-1 parallel drum support
	Added PDP-8 TSC8-75 and TD8E support
	Added H316/516 DMA/DMC, magtape, fixed head disk support
	Added PDP-8, PDP-15, 32b Interdata instruction history support

Rev 3.0, May, 03
	Added logical name support
	Added instruction history support
	Added multiple tape format support
	Added 64b address support
	Added PDP-4 EAE support
	Added PDP-15 FP15 and XVM support

Rev 2.10, Nov, 02
	Added Telnet console capability, removed VT emulation
	Added DO with substitutable arguments (from Brian Knittel)
	Added .ini initialization file (from Hans Pufal)
	Added quiet mode (from Brian Knittel)
	Added ! command (from Mark Pizzolato)
	Added Telnet BREAK support (from Mark Pizzolato)
	Added device enable/disable support
	Added optional simulator hooks for input, output, commands
	Added breakpoint actions
	Added magtape simulation library
	Added PDP-11 KW11P programmable clock
	Added PDP-11 RK611/RK06/RK07 disk
	Added PDP-11/VAX TMSCP tape
	Added PDP-11/VAX DELQA Ethernet support (from David Hittner)
	Added PDP-11/PDP-10 RX211/RX02 floppy disk
	Added PDP-11/VAX autoconfiguration support
	Added PDP-10/PDP-11/VAX variable vector support
	Added PDP-1 DECtape
	Added PDP-1, PDP-4 Type 24 serial drum support
	Added PDP-8 RX28 support
	Added PDP-9 RB09 fixed head disk, LP09 line printer
	Added HP2100 12845A line printer
	Added HP2100 13183 magtape support
	Added HP2100 boot ROM support
	Added HP2100 interprocessor link support
	Added IBM 1620
	Added SDS 940
	Added Interdata 16b and 32b systems
	Added 16b DECtape file format support
	Added support for statically buffered devices
	Added magtape end of medium support
	Added 50/60Hz support to line frequency clocks
	Added 7B/8B support to terminals and multiplexors
	Added BREAK support to terminals and multiplexors

Rev 2.9, Jan, 02
	Added circular register arrays
	Replaced ENABLE/DISABLE with SET ENABLED/DISABLED
	Replaced LOG/NOLOG with SET LOG/NOLOG
	Generalized the timer calibration package
	Added additional routines to the multiplexor library
	Added SET DISCONNECT, SHOW STATISTICS commands to multiplexors
	Reimplemented PDP-8 TTX as a unified multiplexor
	Implemented a PC queue in most simulators
	Added VAX simulator
	Added GRI-909 simulator
	Added Peter Schorn's MITS 8080/Z80 simulator
	Added Brian Knittel's IBM 1130 simulator
	Added HP2100 DQ, DR, MS, MUX devices
	Added SET VT/NOVT commands

Rev 2.8, Dec, 01
	Added DO command
	Added general breakpoint facility
	Added extended SET/SHOW capability
	Replaced ADD/REMOVE with SET ONLINE/OFFLINE
	Added global register name recognition
	Added unit-based register arrays
	Added Charles Owen's System 3 simulator
	Added PDP-11 I/O bus map
	Added PDP-11/VAX RQDX3
	Added PDP-8 RL8A
	Revised 18b PDP interrupt structure
	Revised directory and documentation structure
	Added support for MINGW environment

Rev 2.7, Sep, 01
	Added DZ11 (from Thord Nilson and Art Krewat) to PDP-11,
	 PDP-10
	Added additional terminals to PDP-8
	Added TSS/8 packed character format to PDP-8
	Added sim_sock and sim_tmxr libraries
	Added sim_qcount and simulator exit detach all facilities
	Added Macintosh sim_sock support (from Peter Schorn)
	Added simulator revision level, SHOW version
	Changed int64/uint64 to t_int64/t_uint64 for Windoze
	Fixed bug in PDP-11 interrupt acknowledge
	Fixed bugs in PDP-11 TS NXM check, boot code, error status;
	 added extended characteristics and status
	Fixed bug in PDP-11 TC stop, stop all functions
	Fixed receive interrupt while disconnected bug in DZ11
	Fixed multi-unit operation bugs, interrupt bugs in PDP-11
	 RP, PDP-10 RP, PDP-10 TU
	Fixed carrier detect bug in PDP-11, PDP-10 DZ
	Fixed bug in PDP-8 reset routine
	Fixed conditional in PDP-18b CPU
	Fixed SC = 0 bug in PDP-18b EAE
	Fixed bug in PDP-7 LPT
	Upgraded Nova second terminal to use sim_tmxr
	Upgraded PDP-18b second terminal to use sim_tmxr
	Upgraded PDP-11 LTC to full KW11-L
	Removed hack multiple console support

Rev 2.6b, Aug, 01
	Added H316/516 simulator
	Added Macintosh support from Louis Chrétien, Peter Schorn,
	 and Ben Supnik
	Added bad block table option to PDP-11 RL, RP
	Removed register in declarations
	Fixed bugs found by Peter Schorn
	-- endian error in PDP-10, PDP-11 RP
	-- space reverse error in PDP-11 TS
	-- symbolic input in 1401
	Fixed bug in PDP-1 RIM loader found by Derek Peschel
	Fixed bug in Nova fixed head disk

Rev 2.6a, Jun, 01
	Added PDP-9, PDP-15 API option
	Added PDP-9, PDP-15 second terminal
	Added PDP-10 option for TOPS-20 V4.1 bug fix
	Added PDP-10 FE CTRL-C option for Windoze
	Added console logging
	Added multiple console support
	Added comment recognition
	Increased size of string buffers for long path names
	Fixed bug in big-endian I/O found by Dave Conroy
	Fixed DECtape reset in PDP-8, PDP-11, PDP-9/15
	Fixed RIM loader PC handling in PDP-9/15
	Fixed indirect pointers in PDP-10 paging
	Fixed SSC handling in PDP-10 TM02/TU45
	Fixed JMS to non-existent memory in PDP-8
	Fixed error handling on command file

Rev 2.6, May, 01
	Added ENABLE/DISABLE devices
	Added SHOW DEVICES
	Added examination/modification of register arrays
	Added PDP-10 simulator
	Added clock autocalibration to SCP, Nova, PDP-8, PDP-11,
	 PDP-18b
	Added PDP-8, PDP-11, PDP-9/15 DECtape
	Added PDP-8 DF32
	Added 4k Disk Monitor boot to PDP-8 RF08 and DF32
	Added PDP-4/7 funny format loader support
	Added extension handling to the PDP-8 and -9/15 loaders
	Added PDP-11 TS11/TSV05
	Added integer interval timer to SCP
	Added filename argument to LOAD/DUMP
	Revised magtape and DECtape bootstraps to rewind before
	 first instruction
	Fixed 3 cycle data break sequence in PDP-8 RF
	Fixed 3 cycle data break sequence in 18b PDP LP, MT, RF
	Fixed CS1.TRE write, CS2.MXF,UPE write, and CS2.UAI in
	 PDP-11 RP
	Fixed 4M memory size definition in PDP-11
	Fixed attach bug in RESTORE
	Fixed detach bug for buffered devices
	Updated copyright notices, fixed comments

Rev 2.5a, Dec, 00
	Added CMD flop to HP paper tape and line printer
	Added status input for HP paper tape punch and TTY
	Added Charles Owen's 1401 mag tape boot routine
	Added Bruce Ray's Nova plotter and second terminal modules
	Added Charles Owen's Eclipse CPU support
	Added PDP-9/PDP-15 RIM/BIN loader support
	Added PDP-9/PDP-15 extend/bank initial state registers
	Added PDP-9/PDP-15 half/full duplex support
	Moved software documentation to a separate file
	Fixed SCP handling of devices without units
	Fixed FLG, FBF initialization in many HP peripherals
	Fixed 1401 bugs found by Charles Owen
	-- 4, 7 char NOPs are legal
	-- 1 char B is chained BCE
	-- MCE moves whole character, not digit, after first
	Fixed Nova bugs found by Bruce Ray
	-- traps implemented on Nova 3 as well as Nova 4
	-- DIV and DIVS 0/0 set carry
	-- RETN sets SP from FP at outset
	-- IORST does not clear carry
	-- Nova 4 implements two undocumented instructions
	Fixed bugs in 18b PDP's
	-- XCT indirect address calculation
	-- missing index instructions in PDP-15
	-- bank mode handling in PDP-15

Rev 2.5, Nov, 00
	Removed Digital and Compaq from copyrights, as authorized
	 by Compaq Sr VP Bill Strecker
	Revised save/restore format for 64b simulators
	Added examine to file
	Added unsigned integer data types to sim_defs
	Added Nova 3 and Nova 4 instructions to Nova CPU
	Added HP2100
	Fixed indirect loop through autoinc/dec in Nova CPU
	Fixed MDV enabled test in Nova CPU

Rev 2.4, Jan, 99
	Placed all sources under X11-like open source license
	Added DUMP command, revised sim_load interface
	Added SHOW MODIFIERS command
	Revised magtape format to include record error flag   
	Fixed 64b problems in SCP
	Fixed big endian problem in PDP-11 bad block routine 
	Fixed interrupt on error bug in PDP-11 RP/RM disks
	Fixed ROL/ROR inversion in PDP-11 symbolic routines

Rev 2.3d, Sep, 98
	Added BeOS support
	Added radix commands and switches
	Added PDP-11 CIS support
	Added RT11 V5.3 to distribution kits
	Fixed "shift 32" bugs in SCP, PDP-11 floating point
	Fixed bug in PDP-11 paper tape reader
	Fixed bug in ^D handling

Rev 2.3c, May, 98
	Fixed bug in PDP-11 DIV overflow check
	Fixed bugs in PDP-11 magtape bootstrap
	Fixed bug in PDP-11 magtape unit select
	Replaced UNIX V7 disk images

Rev 2.3b, May, 98
	Added switch recognition to all simulator commands
	Added RIM loader to PDP-8 paper tape reader and loader
	Added second block bootstrap to PDP-11 magtape
	Fixed bug in PDP-8 RF bootstrap
	Fixed bug in PDP-11 symbolic display
	Fixed bugs in PDP-11 floating point (LDEXP, STEXP,
	 MODf, STCfi, overflow handling)

Rev 2.3a, Nov, 97
	Added search capability
	Added bad block table command to PDP-11 disks
	Added bootstrap to PDP-11 magtape
	Added additional Nova moving head disks
	Added RT-11 sample software
	Fixed bugs in PDP-11 RM/RP disks
	Fixed bugs in Nova moving head disks
	Fixed endian dependence in 18b PDP RIM loader

Rev 2.3, Mar, 97
	Added PDP-11 RP
	Added PDP-1
	Changed UNIX terminal I/O to TERMIOS
	Changed magtape format to double ended
	Changed PDP-8 current page mnemonic from T to C
	Added endian independent I/O routines
	Added precise integer data types 
	Fixed bug in sim_poll_kbd
	Fixed bug in PDP-8 binary loader
	Fixed bugs in TM11 magtape
	Fixed bug in RX11 bootstrap
	Fixed bug in 18b PDP ADD
	Fixed bug in 18b PDP paper tape reader
	Fixed bug in PDP-4 console
	Fixed bug in PDP-4,7 line printer

Rev 2.2d, Dec, 96
	Added ADD/REMOVE commands
	Added unit enable/disable support to device simulators
	Added features for IBM 1401 project
	Added switch recognition for symbolic input
	Fixed bug in variable length IEXAMINE
	Fixed LCD bug in RX8E
	Initial changes for Win32
	Added IBM 1401

Rev 2.2b, Apr, 96
	Added PDP-11 dynamic memory size support

Rev 2.2a, Feb, 96
	New endian independent magtape format

Rev 2.2 Jan, 96
	Added register buffers for save/restore
	Added 18b PDP's
	Guaranteed TTI, CLK times are non-zero
	Fixed breakpoint/RUN interaction bug
	Fixed magnetic tape backspace to EOF bug
	Fixed ISZ/DCA inversion in PDP-8 symbol table
	Fixed sixbit conversion in PDP-8 examine/deposit
	Fixed origin increment bug in PDP-11 binary loader
	Fixed GCC longjmp optimization bug in PDP-11 CPU
	Fixed unit number calculation bug in SCP and in Nova,
	 Nova, PDP-11, 18b PDP moving head disks

Rev 2.1 Dec, 95
	Fixed PTR bug (setting done on EOF) in PDP-8, Nova
	Fixed RX bug (setting error on INIT if drive 1 is
	 not attached) in PDP-8, PDP-11
	Fixed RF treatment of photocell flag in PDP-8
	Fixed autosize bug (always chose smallest disk if new
	 file) in PDP-11, Nova
	Fixed not attached bug (reported as not attachable) in
	 most mass storage devices
	Fixed Nova boot ROMs
	Fixed bug in RESTORE (didn't requeue if delay = 0)
	Fixed bug in RESTORE (clobbered device position)
	Declared static constant arrays as static const
	Added PDP-8, Nova magnetic tape simulators
	Added Dasher mode to Nova terminal simulator
	Added LINUX support

Rev 2.0	May, 95
	Added symbolic assembly/disassembly

Acknowledgements

SIMH would not have been possible without help from around the world.  I
would like to acknowledge the help of the following people, all of whom
donated their time and talent to this "computer archaeology" project:

Bill Ackerman		PDP-1 consulting
Alan Bawden		ITS consulting
Winfried Bergmann	Linux port testing
Phil Budne		Solaris port testing
Max Burnet		PDP information, documentation, and software
Robert Alan Byer	VMS socket support and testing
James Carpenter		LINUX port testing
Chip Charlot		PDP-11 RT-11, RSTS/E, RSX-11M legal permissions
Louis Chrétien		Macintosh porting
Dave Conroy		HP 21xx documentation, PDP-10, PDP-18b debugging
L Peter Deutsch		PDP-1 LISP software
Ethan Dicks		PDP-11 2.9 BSD debugging
John Dundas		PDP-11 CPU debugging, programmable clock simulator
Jonathan Engdahl	PDP-11 device debugging
Carl Friend		Nova and Interdata documentation, and RDOS software
Megan Gentry		PDP-11 integer debugging
Dave Gesswein		PDP-8 and PDP-9.15 documentation, PDP-8 DECtape, disk,
			 and paper tape images, PDP-9/15 DECtape images
Dick Greeley		PDP-8 OS/8 and PDP-10 TOPS-10/20 legal permissions
Gordon Greene		PDP-1 LISP machine readable source
Lynne Grettum		PDP-11 RT-11, RSTS/E, RSX-11M legal permissions
Franc Grootjen		PDP-11 2.11 BSD debugging
Doug Gwyn		Portability debugging
Kevin Handy		TS11/TSV05 documentation, make file
Ken Harrenstein		KLH PDP-10 simulator
Bill Haygood		PDP-8 information, simulator, and software
Wolfgang Helbig		DZ11 implementation
Mark Hittinger		PDP-10 debugging
Dave Hittner		SCP debugging, DEQNA emulator and Ethernet library
Sellam Ismail		GRI-909 documentation
Jay Jaeger		IBM 1401 consulting
Doug Jones		PDP-8 information, simulator, and software
Brian Knittel		IBM 1130 simulator, SCP extensions for GUI support
Al Kossow		HP 21xx, Varian 620, TI 990, Interdata, DEC
			 documentation and software
Arthur Krewat		DZ11 changes for the PDP-10
Mirian Crzig Lennox	ITS and DZ11 debugging
Don Lewine		Nova documentation and legal permissions
Tim Litt		PDP-10 hardware documentation and schematics,
			 tape images, and software sources
Tim Markson		DZ11 debugging
Bill McDermith		HP 2100 debugging, 12565A simulator
Scott McGregor		PDP-11 UNIX legal permissions
Jeff Moffatt		HP 2100 information, documentation, and software
Alec Muffett		Solaris port testing
Terry Newton		HP 21MX debugging
Thord Nilson		DZ11 implementation
Charles Owen		Nova moving head disk debugging, Altair simulator,
			 Eclipse simulator, IBM System 3 simulator,
			 IBM 1401 diagnostics, debugging, and magtape boot
Sergio Pedraja		MINGW environment debugging
Derek Peschel		PDP-10 debugging
Paul Pierce		IBM 1401 diagnostics, media recovery
Mark Pizzolato		SCP, Ethernet, and VAX simulator improvements
Hans Pufal		PDP-10 debugging, PDP-15 bootstrap, DOS-15 recovery,
			DOS-15 documentation, PDP-9 restoration
Bruce Ray		Software, documentation, bug fixes, and new devices
			 for the Nova, OS/2 porting
Craig St Clair		DEC documentation
Richard Schedler	Public repository maintenance
Peter Schorn		Macintosh porting
Stephen Schultz		PDP-11 2.11 BSD debugging
Olaf Seibert		NetBSD port testing
Brian & Barry Silverman	PDP-1 simulator and software
Tim Shoppa		Nova documentation, RDOS software, PDP-10 and PDP-11
			 software archive, hosting for SIMH site
Van Snyder		IBM 1401 zero footprint bootstraps
Michael Somos		PDP-1 debugging
Hans-Michael Stahl	OS/2 port testing, TERMIOS implementation
Tim Stark		TS10 PDP-10 simulator
Larry Stewart		Initial suggestion for the project
Bill Strecker		Permission to revert copyrights
Chris Suddick		PDP-11 floating point debugging
Ben Supnik		Macintosh timing routine
Bob Supnik		SIMH simulators
Ben Thomas		VMS character-by-character I/O routines
Warren Toomey		PDP-11 UNIX software
Deb Toivonen		DEC documentation
Mike Umbricht		DEC documentation, H316 documentation and schematics
Leendert Van Doorn	PDP-11 UNIX V6 debugging, TERMIOS implementation
Fred Van Kempen		Ethernet code, RK611 emulator, PDP-11 debugging,
			VAX/Ultrix debugging
Holger Veit		OS/2 socket support
David Waks		PDP-8 ESI-X and PDP-7 SIM8 software
Tom West		Nova documentation
Adrian Wise		H316 simulator, documentation, and software
John Wilson		PDP-11 simulator and software
Joe Young		RP debugging on Ultrix-11 and BSD

In addition, the following companies have graciously licensed their
software at no cost for hobbyist use:

Data General Corporation
Digital Equipment Corporation
Compaq Computer Corporation
Mentec Corporation
The Santa Cruz Operation
Caldera Corporation
Hewlett-Packard Corporation