SimH
simH is a computer system simulation platform similar to how MAME works. It can be used to run older software or gain more familiarity with the simulated systems. simH is not one executable though, instead of multiple libraries being included by one executable it is designed to be compiled into individual executables for each simulated system type.
Compiling - Linux
While some package managers may have simH included, for niche projects like this I will always recommend building directly from the source.
The official directions to compile the software are fairly good. These are the commands I used from the root of the project for compiling on my Ubuntu system:
sh .travis/deps.sh linux
cmake/cmake-builder.sh --flavor unix
Before doing this I had installed cmake and the libvdeplug-dev and libpcre3-dev packages, but I believe the deps script would have handled that had I not.
Usage
Host Level
simH starts as an interactive shell before starting the computer simulation. You can see all available commands with help and exit the shell with the q or quit command. The shell supports tab completion for host filenames and unique shorthands for commands (example, CAT can be run with CA). There are commands for working at the host level available in this shell that mimic the respective UNIX/Linux and DOS/Windows commands. Here are just some of them to give you an idea:
ls/DIRcp/COPYpwdcat/TYPEecho
Any command not available in simH's shell natively can be directly run on the host using the ! command prefix. For example ! vim config.simh would open the vim editor with the specified file in the simH shell. Quiting vim returns to the simH shell.
Scripting
There are more advanced logic commands such as IF statements available as well that can be used with a launch script with simH. For built in help with commands like these you can run help if to see more information. You can end the help menu with exit.
To run a script from within the simH shell you can use the DO command followed by the script name, ensure you are in the correct directory on the host to access it.
Here is an example script:
help-dir.simh
help
echo The above are all available commands. The following is your current host path.
pwd
This would be run with do help-dir.simh and will print the built in help, some text, and your current path.
The scripting interface can also be programmed to respond to outputs from the simulated machine. Here is an example that automatically respond to a specif prompt:
expect 'Type C to continue' send -t after=10m,'C'; continue
If the simulated machine ever prints "Type C to continue" the expect command will trip and run the send command. The send command will input a "C" to the machine and followed by continue is run to resume execution. The after parameter is used to set a wait time before sending the data to the machine. Responses like this should be setup before the machine is booted.
Scripting is most useful for setting up the configuration for your simulated system. Scripts can be run on startup with simH by simply passing the filename as a parameter. This makes configuring and maintaining simulated systems much easier. As you continue with the configuration commands, keep in mind that you can put them in a script to automate them.
Simulation Configuration
The simulated machine will have a number of virtual devices available to it. The command SHOW FEATURES will output all of the devices for the simulated machine. The SET and ATTACH commands are used to configure the devices before starting the machine. Each emulated system has different emulated devices and what you want to configure may be different between them. You can use the HELP {dev} command to see information about how a device can be set up within simH itself.
Device Setup Example
Here is an example of setting up a Data General Nova simulation. We will start by using the rdos_d31.dsk disk image available in the Nova Software Kit. To begin, start the nova simulator in the same directory as the disk image file.
To start, run the SHOW FEATUREScommand and you will get the following:
sim> show feature
NOVA simulator configuration
CPU
PTR
PTP
TTI
TTO
TTI1
TTO1
RTC 60Hz
PLT
LPT
DSK
DKP 4 units
MTA 8 units
QTY disabled
ALM lines=64
Note: The Nova simulator is one of the less developed packages in simH. Many of the more popular machines will print more helpful configuration information here.
Some devices here will be shared with other machines, and some will be unique to the machine you are working with. Here are some of the common ones:
CPU: Main machine settingsPTRandPTP: Paper Tape reader and punchLPT: Printer outputTTOandTTI: Terminal output and input
For any of these devices listed you can run the HELP {dev} command, this will tell you which command parameters you can use with SET and SHOW to configure a device. Here is a truncated example:
sim> help cpu
CPU help
CPU device SET commands:
set CPU NOVA3
set CPU NOVA4
set CPU 4K
set CPU 8K
set CPU 32K
set CPU HISTORY
CPU device SHOW commands:
show CPU HISTORY{=arg}
The CPU device implements these registers:
Name Size Purpose
---------------------------
PC 15
AC0 16
AC1 16
AC2 16
AC3 16
CPU WRU 8
The default breakpoint type is: -E
From that printout we see that we can use the SET command on CPU to configure the machine with 32K of memory with this command SET CPU 32K
To set up our disk image now we need to find the drive interface and configuration it can be used with. The nova simulator showed us DSK and DKP which are both disk options. In this case DKP is the one we want which we can see by the drive type listing when we run HELP on it:
sim> help dkp
DKP help
DKP device SET commands:
set DKP ENABLE Enables device DKP
set DKP DISABLE Disables device DKP
set DKPn ENABLE Enables unit DKPn
set DKPn DISABLE Disables unit DKPn
set DKPn WRITEENABLED Write enable drive
set DKPn LOCKED Write lock drive
set DKPn AUTOSIZE
set DKPn FLOPPY
set DKPn 6030
set DKPn DSDDFLOPPY
set DKPn 6097
set DKPn D31
set DKPn 4047
set DKPn D44
set DKPn 4234
set DKPn 6045
set DKPn C111
set DKPn 4048
set DKPn C114
set DKPn 2314
set DKPn 4057
set DKPn 6225
set DKPn 6227
set DKPn 6099
set DKPn 6103
set DKPn 6070
set DKPn 4231
set DKPn 3330
DKP device SHOW commands:
show DKPn WRITEENABLED Write enable drive
The DKP device implements these registers:
Name Size Purpose
-------------------------
FCCY 16
USSC 16
STA 16
DKP MA 16
DKP INT 1
DKP BUSY 1
DKP DONE 1
DKP DISABLE 1
DIAG 1
TRACE 32
MAP 2
STIME 24
DKP RTIME 24
The "n" at the end of DKP is an indicator for a device ID. You can start at DKP0 for your first device.
Ideally at this point you would know what drive the image you are attempting to mount is for, there are many options listed here for the Nova that could make this confusing. Thankfully the AUTOSIZE option is the default and will change the DKP device to the correct config based on the size of the file. So we can just run ATTACH DKP0 rdos_d31.dsk. We can follow this up with SHOW DKP0 to see what drive type AUTOSIZE set.
sim> SHOW DKP0
DKP0 1247KW, attached to rdos_d31.dsk, write enabled
4047 (Diablo 31)
It used the 4047 device type.
You can use these principals to explore and configure other device features to set up your system. Once you know how you want to setup your machine you can put all of the configuration commands in a text file that you can run as a script as covered earlier.
Running Simulation
There are two main ways you will likely start the simulation, either BOOT or RUN. RUN is meant for starting code already loaded into memory using EXAMINE and DEPOSIT or after loading it in the simulation. BOOT allows you to specify a device to load software from. In the example configuration above you could run BOOT DKP0 to start software on the disk image we attached. Once the simulation is running you can stop it with Ctrl+E which will pause the simulation and take you back to the simH shell. From here you can change the configuration such as switching images mounted to drives or modifying memory. To resume the simulation use the CONTINUE command.
When you are done you can press Ctrl+Eand run the command QUIT.