To:	Users
From:	Bob Supnik
Subj:	SIM8
Date:	14-Jun-2006

                                COPYRIGHT NOTICE

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

    Original code published in 1966-1968, written by David J Waks
    Portions Copyright (C) 1997 Digital Equipment Corporation

    All Rights Reserved except as specified below.

    Permission is hereby granted to use, copy, modify, and distribute
    this software (or portions thereof) for any purpose, without fee,
    subject to these conditions:

    (1) If any part of the source code for this software is distributed,
    then this copyright and no-warranty notice must be included
    unaltered; and any additions, deletions, or changes to the original
    files must be clearly indicated in accompanying documentation.

    (2) If only executable code is distributed, then the accompanying
    documentation must state that "this software is based in part on the
    original work of David J Waks".

    (3) Permission for use of this software is granted only if the user
    accepts full responsibility for any undesirable consequences; the
    authors accept NO LIABILITY for damages of any kind.

    These conditions apply to any software derived from or based on this
    code, not just to the unmodified code.

    Permission is NOT granted for the use of any author's name or
    company name in advertising or publicity relating to this software
    or products derived from it.


1. Introduction

This package contains the source and binary for SIM8, a PDP-7 based
simulator for the PDP-8.  SIM8 was written at Applied Data Research
in 1966-68 as the foundation of its development environment for PDP-8
embedded systems.

The package contains the following items:

	sim8.7			SIM8 sources
	sim8.rim		SIM8 binary in read-in mode format
	macro7.c		assembler for SIM8

To assemble SIM8, you must first compile the assembler:

	cc macro7.c -o macro7

and then use it to assemble the sources:

	macro7 sim8.7

The binary tape image can be used directly with any PDP-7 simulator that 
has a read-in mode loader command.


2. History Of The Program

SIM8 was designed and implemented in 1966 by Dave Waks and extended by
Dave and others in 1967 and 1968.  SIM8 was part of Applied Data Research's
unique development environment for PDP-8 embedded systems.  This development
environment ran on a 16K PDP-7 under DECSYS, Digital's first mass
storage-based operating system.  It included a real PDP-8 (actually
a 338 graphics system) which was connected to the PDP-7 by Digital's
first inter-processor link.  Editing was done on the PDP-7.  Assembly
was done on the PDP-8, using an extended memory version of Macro-8,
with I/O provided by the PDP-7 across the inter-processor link.
Debugging was done under simulation on the PDP-7 again.  The environment
was later extended further by allowing another PDP-8 (the 'remote'
system) to be linked to the first PDP-8 (the 'near' system); this
allowed the actual embedded system hardware to be part of the environment.

SIM8 simulated an 8K PDP-8/I in the upper 8K bank of PDP-7 memory.  It
simulated a DF32 fixed head disk on DECtape.  It simulated the other
PDP-8 devices (teletype, reader, punch, printer) on the equivalent PDP-7
hardware devices.

In 1968, Bob Supnik did a spinoff of the program which simulated an
Interdata 4, but it does not appear that development was ever finished.
Many of the simulation and software development concepts from SIM8 were
generalized and implemented as part of the MIMIC system for the PDP-10.


3. Provenance Of The Source

In 1997, Dave Waks found two PDP-10 failsafe tapes in his basement.  
According to a directory listing, one of them contained old Applied 
Data Research software for the PDP-7 and PDP-8, including SIM8.  (The 
other had no label and has proved unreadable.)  Dave sent the tape to 
me to see if it could be salvaged.  I in turn contacted Paul Pierce, 
who was able to use his seven track magtape set up to read most of the 
tape.  Tim Litt then wrote a failsafe format interpreter which recovered 
the original ASCII files.  I modified Gary A. Messenbrink's PDP-8 cross
assembler to add features (macros, variable field definitions) and then
retargeted it to the PDP-7.  The result is the binary in this package.

The source has required significant editing for this release.  First,
the last few blocks proved unreadable and were lost.  Second, the PDP-7
assembler implicitly defined all undefined symbols as temporaries.
Because this made it difficult to find source corruptions, I added
explicit definitions for all temporary variables.  Third, the simulator
existed in a unique and non-reproducible environment.  It assumed the
existence of DECSYS, DDT, several ADR-specific utility packages, the
inter-processor links, DECtapes, a card reader, and a non-standard Potter
chain printer.  All of these dependencies needed to be commented out or
removed at the source level.  Source changes are indicated by /**.


4. User's Guide

To run SIM8, local echo must disabled on the simulated PDP-7's Teletype.
The SIM8 RIM-format tape can then be loaded with the LOAD command:

	sim> set tti fdx		(SimH V3.6-1 or later)
	sim> load sim8.rim
	sim> run

The user interface for SIM8 is modeled on various debugging packages of
the time, such as ODT and DDT.  Commands are a single word, number, or
word followed by a number, terminated by slash (/).  The commands are:

	nnn/		examine memory location nnn
	AC/		examine the AC
	L/ or LINK/	examine the Link
	PC/		examine the Instruction Field'PC
	OLDPC/		examine the PC prior to the last jump
	MAR/		examine the Memory Address register
	IBBR/		examine the Instruction Field Buffer register
	DBR/		examine the Data Field register
	BSR/		examine the Save Field register
	QINTON/		examine the interrupts enabled flag
	QANYIN/ or QANYINT/	examine the any interrupts outstanding flag
	KF/		examine the keyboard flag
	TF/		examine the teleprinter flag
	RF/		examine the reader flag
	PF/		examine the punch flag
	LF/		examine the line printer flag
	PANEL/		display the front panel registers
	FILLER/		examine the fill constant
	FILLALL/	fill simulated memory with the fill constant
	FILL/		fill selected memory locations with the fill constant
	DUMPALL/	dump simulated memory to the line printer
	DUMP/		dump selected memory locations to the line printer
	DECSYS/		invoke DECSYS (disabled)
	DDT/		invoke DDT (disabled)
	TLOAD/		load a DECSYS file into simulated memory (disabled)
	CHKPNT/		invoke DECtape checkpointing system (disabled)
	SEND/		send simulated memory to the near PDP-8 (disabled)
	RECEIVE/	fetch near PDP-8 memory to the simulator (disabled)
	SENDR/		send simulated memory to the far PDP-8 (disabled)
	RECEIVER/	fetch far PDP-8 memory to the simulator (disabled)
	INIT/		clear simulated memory, reset simulated state,
			load the binary loader and start executing it
	RIM/		reset simulated state, load the RIM loader,
			and start executing it
	LOAD/		reset simulated state and start executing the
			binary loader
	START n/	if n is specified, load it into the PC; reset
			simulated state and start executing at PC
	GO/		resume execution at the current PC
	BKPT/		set instruction breakpoints in the specified locations
	DBKPT/		set data breakpoints in the specified locations
	RESET/		clear breakpoints in the specified locations
	RESETALL/	clear all breakpoints
	TIMON/		enable cycle and IOT counting
	TIMOFF/		disable cycle and IOT counting
	TIMER/		display cycle and IOT counters
	
When registers are examined, the user can specify a new value or simply
type return to close the location:

	AC/	0000	1234
	AC/	1234
	AC/	1234

When memory is examine, the user can specify a new value or simply type
return to close the location.  Instead of return, the user can type + or
line feed to open the next location, minus to open the previous location,
or / to reopen the current location:

	100/	0000	1234+
	101/	0000	2525-
	100/	1234	0/
	100/	0000

The breakpoint commands (BKPT, DBKPT, and RESET) allow the user to specify
a single location as part of the command, or a range of locations following
the command:

	BKPT 100/
	DBKPT 140
	RESET/ 100-200

The dump and fill commands allow the user to specify a range of locations
following the command:

	DUMP/ 100-200

When running, the simulator may be interrupted by typing the WRU (^E) key.
Because this is also the default interrupt key for the PDP-7 simulator,
you should change the PDP-7 simulator's interrupt key value prior to running
SIM8:

	sim> load sim8.rim
	sim> d wru 6


5. Useful Patches

SIM8 rings the bell every time it wants input.  To disable this, patch the
loaded core image as follows:

	sim> d 4762 nop

or in binary

	4762/	740000
