PiDP-8/I Software

PiDP-8/I Configure Script Options
Log In

This document describes the options you can pass to the configure script when building the PiDP-8/I software from source. For a stock build, no options are needed:

$ ./configure && tools/mmake && sudo make install

The options below let you tailor the build to your hardware, preferences, and available disk space.

Quick Reference

Option Purpose
--prefix Change the installation directory (default: /opt/pidp8i)
--lowercase Control how lowercase keyboard input is handled
--no-lamp-simulator Disable the incandescent lamp simulator (ILS)
--serial-mod Enable Oscar's serial mod GPIO wiring
--alt-serial-mod Enable James L-W's alternative serial mod
--throttle Limit simulator CPU speed
--enable-savestate Persist simulator state across restarts
--disable-usb-automount Disable automatic USB drive mounting
--disable-cc8-cross Skip building the CC8 C cross-compiler
--runtime Choice of runtime boot: Default is 'ock' OS/8 Combined Kit. Alternate is V3D
--disable-os8-* Leave out default OS/8 disk image components
--enable-os8-* Add optional OS/8 disk image components
--os8-minimal Strip OS/8 disk image to bare minimum
--help Show all options

--prefix

Perhaps the most widely useful configure script option is --prefix, which lets you override the default installation directory, /opt/pidp8i. There are many good reasons to change where the software gets installed, but the default is also a good one, so unless you know for a fact that you want to change this default, leave it alone.

For example, you might prefer that the installer put the built software under your home directory. This will do that:

$ ./configure --prefix=$HOME/pidp8i && sudo make install

You might think that installing to a directory your user has complete control over would remove the need for installing via sudo, but that is not the case, since the installation script needs root privileges to mark a few of the executables as having permission to run at high priority levels, which improves the quality of the display, particularly with the incandescent lamp simulator feature enabled.

--lowercase

The American Standards Association (predecessor to ANSI) delivered the second major version of the ASCII character encoding standard the same year the first PDP-8 came out, 1965. The big new addition? Lowercase.

That bit of history means that when the PDP-8 was new, lowercase was a fancy new feature in the computing industry. That, plus the memory savings you get from storing stripped ASCII as two 6-bit characters per 12-bit PDP-8 word means that most PDP-8 software did not expect to receive lowercase ASCII text, particularly the older software.

The PDP-8 lived long enough to see lowercase ASCII input become common in the computing industry.

As a result, PDP-8 software reacts in many strange and wonderful ways when you give it lowercase input. Some software copes nicely, other software crashes, and some software just sits there dumbly waiting for you to type something!

This configuration option lets you control how you want your simulated PDP-8/I to react to lowercase input:

--no-lamp-simulator

The incandescent lamp simulator (ILS) drives the front panel LEDs in a way that mimics the glow and decay of the incandescent lamps in the original PDP-8/I. It is CPU-intensive and requires a multi-core Pi to run well. It is enabled automatically when building on multi-core hardware.

Single-core Pi models — including the Pi Zero 2 W and the Pi 3 Model A+ — cannot run the ILS without consuming all available CPU. On these boards, pass --no-lamp-simulator to use the original low-CPU-usage LED driving method instead. The configure script detects single-core hardware and sets this automatically, but you can set it explicitly if needed.

Legacy ARMv6/v7 platforms (original Pi Zero, Pi Zero W, Pi 1, Pi 2 v1.0/v1.1) are also single-core or close enough in CPU budget that NLS is strongly recommended. Note that building from source on these platforms is untested as of the current release; Raspberry Pi OS Bookworm is the recommended base if you try.

Those on a multi-core host who want the low-CPU-usage LED driving method for other reasons — such as running many background tasks, or when the CPU is heavily throttled — can also pass this option explicitly.

--serial-mod

If you have done Oscar's serial mod to your PiDP-8/I PCB and the Raspberry Pi you have connected to it, add --serial-mod to the configure command above.

If you do not give this flag at configure time with these hardware modifications in place, the front panel will not work correctly, and trying to run the software may even crash the Pi.

If you give this flag and your PCBs are not modified, most of the hardware will work correctly, but several lights and switches will not work correctly.

--alt-serial-mod

This flag is for an alternative serial mod by James L-W. It doesn't require mods to the Pi, and the mods to the PiDP-8/I board are different from Oscar's. This flag changes the GPIO code to work with these modifications to the PiDP-8/I circuit design.

See the linked mailing list thread for details.

As with --serial-mod, you should only enable this flag if you have actually done the mods as specified by James L-W.

This option is a pure alternative to --serial-mod: you can leave both off, but you cannot pass both.

--throttle

See README-throttle.md for the values this option takes. If you don't give this option, the simulator runs as fast as possible.

--enable-savestate

By default, the PiDP-8/I starts up with the core state undefined and runs the boot script you've selected either with the IF switches or by passing it on the command line to pidp8i-sim or pdp8. This brings the simulator up in a known state, with no persistence between restarts other than what was written to the simulated storage devices before the last shutdown.

On a real PDP-8 with core memory, however, the values in memory will persist for weeks without power; core memory on a PDP-8 is not zeroed on power-up, unlike RAM on a modern computer. Since the CPU doesn't start executing anything on power-up in a stock PDP-8 configuration, this means the user can toggle in a program/OS restart address with the switch register (SR), load it into the program counter (PC) with the Load Addr switch, then START the CPU to restart their program without having to reload it from tape or disk.

There were also several power fail and restart options designed and made available for the PDP-8 series throughout its lifetime. One of these — the KP8-I for the PDP-8/I — would detect a power fail condition, then in the brief time window while the power supply's reservoir capacitors kept the computer running, this option card would raise an interrupt, giving a user-written routine up to 1 millisecond to save important registers to core so they would persist through the power outage. Then on power-up, it would start executing at core location 00000, where another user routine would load those registers back from core to restart the system where it left off before the power failed.

Giving this option gives roughly the same effect for all generated boot scripts: any time the simulator is shut down gracefully, it saves all key simulator state — registers, core, device assignments, etc. — to a disk file. Then on restart, that script will reload that saved state if it finds the saved state file.

This is not identical to a KP8-I in that it doesn't require any user-written PDP-8 code to run, which is why it's optional: it's ahistoric with respect to the way the included OSes normally ran.

In absence of a hardware option like the KP8-I, a more accurate simulation would only save the core memory state to a host-side disk file and reload it on simulator re-start. You can get that behavior atop the current mechanism by adding commands like the following to each bootscript you want to affect:

EVAL HLT
DEP L 0
DEP AC 0
DEP DF 0
DEP IF 0
DEP MQ 0
DEP PC 0

That zeroes the key registers and prevents the CPU from running as it normally would after giving the RESTORE command to SIMH.

--disable-usb-automount

When you install the software on a systemd-based Linux system, we normally configure the OS to automatically mount USB drives when they are initially plugged in, which allows the SING_STEP + DF media image auto-attach feature to work smoothly. That is, if you plug in a USB memory stick holding a *.pt file containing a paper tape image, you want the simulator to be able to find it if you have the DF switches set to 1, telling the PiDP-8/I front panel code to look for something to attach to the simulator's paper tape reader.

This feature may interfere with other uses of USB, such as when booting your Pi from an external USB hard disk drive. Give this option to disable the feature.

(Alternately, you could modify our etc/udev.rules and/or bin/usb-mount scripts so that they work cooperatively with your local USB setup rather than conflicting with it.)

--disable-cc8-cross

Give this option if you do not want to build Ian Schofield's cc8 C cross-compiler on the host.

Because the cross-compiler is needed to build the CC8 native OS/8 compiler, disabling the cross-compiler also causes the native compiler to be left off the bootable OS/8 RK05 disk image, as if you'd passed the --disable-os8-cc8 configuration option.

--runtime

This option offers a choice of boot media used for the IF=0 and IF=7 cases.

Previously the default was an extended version of OS/8 V3D, as distributed by DEC, plus some patches we applied.

We now build the whole OS from source as offered in the OS/8 Combined Kit, which is the last complete release of OS/8 released by DEC. (See that link for details.)

To change back to v3d as the boot image:

$ ./configure --runtime=v3d && sudo make install

Note that the Combined Kit was also considered v3d with extensions and updates so the startup banner will say, "OS/8 V3D Combined Kit".

Whichever OS version gets booted up, it will include our extensions and third party software as described below, and configurable by you.

--disable-os8-*

Several default components of the OS/8 RK05 disk image used by boot options IF=0 and IF=7 can be left out to save space and build time:

You can later remove each of these after installation using our package manager.

--enable-os8-*

There are a few file sets not normally installed to the OS/8 RK05 disk image used by boot options IF=0 and IF=7. You can install them with the following options:

You can later add each of these after installation using our package manager.

--os8-minimal

This sets all --enable-os8-* flags to false and all --disable-os8-* flags to true. This mode overrides any --enable-os8-* flag, so if you want a minimal install plus just one or two features, it's simplest to give this flag and then use our package manager to add in the elements you want rather than pass a bunch of --disable-os8-* options.

This option may not do some things you think it should:

  1. This flag's name is aspirational, not a promise of an ideal: our current "minimal" installation could be stripped down further. For example, we currently have no way to leave out OS/8's BASIC interpreter, even though no core OS services depend on it.

  2. This option does not affect the --lowercase option because that affects only OS/8's command interpreter and OS/8's BASIC implementation, so we deem it to be orthogonal to the purpose of the --os8-minimal flag, which only affects the optional post-BUILD features. You may therefore wish to give --lowercase=none along with --os8-minimal.

  3. This option does not affect --disable-os8-src, because it only suppresses optional features in the primary bootable OS/8 media. If you want minimal OS/8 boot media without a separate source code data disk, give this option as well.

  4. Although this option disables display of the INIT.TX file on boot, the file is still generated, on purpose. First, it acts as build documentation, recording what was built and when. Second, you may wish to enable this welcome message later, and it's rather painful to go back through the build process to generate it after the fact.

--help

Run ./configure --help for more information on your options here.