To:	Users
From:	Bob Supnik
Subj:	Simulator Usage, V2.10-3
Date:	15-Feb-2003


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.


   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, 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:

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:


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:


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. Note that WinPCAP DOES NOT SUPPORT dual CPU environments.

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

1.2.2 Compiling Under MinGW

MinGW (Minimum GCC for Windows) is a free C compiler available from 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,

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:

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:


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 number of formats supported is 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 number of formats supported is 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 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, start at location sub1 up to and including location sub2
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).


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:

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...}

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

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.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.

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
CPU		y	y	y	y	y
FPU		-	y	-	-	-
EIS/CIS		-	h	-	-	-
console		y	y	y	y	y
paper tape	y	y	y	h	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	-	h
fixed disk	y	-	h	-	h
floppy disk	y	y	y	-	-
drum		-	-	-	-	h
DECtape		y	y	-	h	y
mag tape	h	y	y	-	h

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

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

legend:		y = runs operating system or sample program
		d = runs diagnostics
		h = runs hand-generated test cases
		n = untested
		- = not applicable