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 / DIR
• cp / COPY
• pwd
• cat / TYPE
• echo

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 settings
• PTR and PTP: Paper Tape reader and punch
• LPT: Printer output
• TTO and TTI: 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.