PiDP-8/I Software

All Top-level Files
Log In
All Tip Tree-View Trunk

Files in the top-level directory in any check-in

Getting Started with the PiDP-8/I Software

Orientation

You will be reading this either:

The latter two are secondary outputs from the first, being the PiDP-8/I software development project’s home.

This is open source software: you are welcome to contribute to the project.

Start Here

Not sure where to begin? Pick the row that matches your situation:

My situation Where to go
Brand new arm64 Pi — easiest path Download our binary OS image → flash to SD card → OS image guide
Brand new arm64 Pi — stock Raspberry Pi OS Preparing Your Pi → Getting the Software → Build and install
Legacy Pi (ARMv6/v7) — untested Raspberry Pi OS Bookworm + build from source; see Prerequisites and --no-lamp-simulator if single-core
Existing Pi OS, adding PiDP-8/I software Getting the Software onto Your Pi
Already installed, want to update Updating the binary OS release on the project home page
Want bleeding-edge or to contribute CONTRIBUTING.md → clone Fossil repo
Just want the OS/8 disk images (for SIMH elsewhere) OS/8 RK05 Media on the project home page
Hardware LEDs/switches not working Testing Your PiDP-8/I Hardware
Something differs from Oscar's version Major Differences wiki page

Prerequisites

<!-- TODO: verify pip/venv behavior on macOS after further Trixie testing --> 
Under Homebrew, such as on macOS, say instead:

    $ brew install make perl python python-setuptools
    $ pip3 install --user pexpect pyyaml

On [other compatible OSes][othos], you may need different commands.

Preparing Your Pi

If you are using our binary OS image, skip ahead to Using the Software — your Pi is ready to go.

If you’ve just barely unpacked Raspberry Pi OS onto an SD card and are now trying to get the PiDP-8/I software distribution working on it, stop and go through the Raspberry Pi documentation first. At the absolute minimum, run raspi-config and make sure the Localization settings are correct. The defaults are for the United Kingdom, home of the Raspberry Pi Foundation, so unless you live there, the defaults are probably incorrect for your location.

Getting the Software onto Your Pi

This section is for those reading this on our project home site or via its GitHub mirror. If you are instead reading this as the README.md file within an unpacked distribution of the PiDP-8/I software, skip to the next section.

Transferring the Source Tarball to the Pi

There are many ways to get the *.tar.gz file onto your Pi:

  1. Copy the file to the SD card you're using to boot the Pi. When inserted into a Mac or Windows PC, typically only the /boot partition mounts as a drive your OS can see. (There's a much larger partition on the SD card, but most PCs cannot see it.) There should be enough free space left in this small partition to copy the tarball over. When you boot the Pi up with that SD card, you will find it in /boot.

  2. Pull the file down to the Pi over the web, directly to the Pi:

    $ wget -O pidp8i.tar.gz https://goo.gl/JowPoC

    That will get you a file called pidp8i.tar.gz in the current working directory containing the latest stable release. To get the bleeding edge tip-of-trunk version instead, say:

    $ wget -O pidp8i.tar.gz https://tangentsoft.com/pidp8i/tarball

  3. SCP the file over to a running Pi from another machine. If your Pi has OpenSSH installed and running, you can use WinSCP, Cyberduck, FileZilla or another SCP or SFTP-compatible file transfer program to copy the file to the Pi over the network.

  4. Clone the Fossil repository using the instructions in the CONTRIBUTING.md file. (Best for experts or those who wish to become experts.)

Alternatively, switch to our pre-built binary OS images based on the latest stable release (currently Debian Trixie, 64-bit ARM), with the PiDP-8/I software already downloaded, configured, and installed. See the OS images documentation for installation instructions.

Unpacking the Software on Your Pi

Having transferred the distribution file onto your Pi, unpack it with:

$ tar xf pidp8i.tar.gz

Configuring, Building and Installing

For a stock build, say:

$ cd ~/pidp8i
$ ./configure && tools/mmake && sudo make install

You may want to add options to the configure step, described below.

Subsequent software updates and rebuilds should not require that you re-run the configure step manually, but if automatic re-configuration fails, you can force it:

$ make reconfig

The “mmake” step above will take quite a while to run, especially on the slower Pi boards. The longest single step is building the OS/8 disk packs from source media. Be patient; the build process almost certainly isn’t frozen.

Only the make install step needs to be done via “sudo”. No other step requires root privileges.

After running “sudo make install” the first time, you will have to log out and back in to get the installation’s “bin” directory into your PATH.

Using the Software

For the most part, this software distribution works like the old stable 2015.12.15 distribution. Its documentation therefore describes this software too, though there are significant differences.

Quick start:

  1. To start the simulator running in the background:

    $ pidp8i start

    This will happen automatically on reboot unless you disable the service, such as in order to run one of the various forks of Deeper Thought.

  2. To attach your terminal to the running simulator, run the same script without an argument:

    $ pidp8i

  3. To detach from the simulator's terminal interface while leaving the PiDP-8/I simulator running, type Ctrl-A d. You can re-attach to it later with a pidp8i command.

  4. To shut the simulator down while attached to its terminal interface, type Ctrl-E to pause the simulator, then at the simh> prompt type quit. Type help at that prompt to get some idea of what else you can do with the simulator command language, or read the SIMH Users' Guide.

  5. To shut the simulator down from the command line:

    $ pidp8i stop

    That then lets you run something like Incandescent Thought without conflict.

You might also find our Learning More links helpful.

The Background Simulator Service

The PiDP-8/I software distribution uses systemd to run the background PDP-8 simulator as user-level service, so you needn’t give sudo on any command to interact with that service, as you did in older versions of the software.

Although you can give verbose systemctl commands like this:

$ systemctl --user start pidp8i

…we’ve provided a wrapper for such commands:

$ pidp8i start
$ pidp8i stop
$ pidp8i restart
$ pidp8i status -l

All arguments are passed to systemctl, not just the first, so you can pass any flags that systemctl accepts, as in the last example.

Configure Script Options

You can change many things about the way the software is built and installed by giving options to the configure script. The full reference for all options is in doc/configure-options.md.

A brief summary:

Option Purpose
--prefix Change the installation directory (default: /opt/pidp8i)
--lowercase Control how lowercase keyboard input is handled
--no-lamp-simulator Required for single-core Pi hardware (Pi Zero 2 W, Pi 3A+); also useful on legacy ARMv6/v7 platforms
--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
--use-ock Boot from OS/8 Combined Kit instead of 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

Runtime Configuration

The pidp8i command sources a Bourne shell script called pidp8i.rc — normally installed in /opt/pidp8i/etc — which you may edit to override certain details of the way that script runs. The intended purpose is to give you a place to define local overrides for default variables:

SCREEN_MANAGER=screen

By default, the PiDP-8/I software distribution installs and uses GNU screen(1) to allow the simulator to run in the background yet be reattached from a later terminal session, then possibly later to be backgrounded once again. Without the intermediation of something like screen, the simulator would either forever be in the background — so we’d have to export the console another way — or we’d have to give up on background startup, requiring that users fire the simulator up interactively any time they wanted to use it. Using a screen manager lets us have it both ways.

The SCREEN_MANAGER setting is for use by those that want to use one of the alternatives to GNU screen:

Note that the alternative screen managers are not installed by default. If you set SCREEN_MANAGER=tmux, you must then ensure that tmux is in fact installed before the pidp8i script goes to try and use it. From the Pi’s command line:

$ sudo apt install tmux

Switching between configured screen managers must be done while the simulator is stopped.

Simplifying Boot and Login

The setup and installation instructions above assume you will be using base the Raspberry Pi OS as a network server, offering SSH if nothing else. Thus, we do not try to bypass any Linux security mechanisms, not wanting to create an insecure island on your network.

However, if you want to run your system more as an appliance, you can cast away some of this security to get auto-login and other convenient behaviors:

The OS/8 Disk Images

For the first several years of the PiDP-8/I project, the OS/8 RK05 disk image included with the PiDP-8/I software (called os8.rk05) was based on an image of a real RK05 disk pack that someone allegedly found in a salvaged PDP-8 system. Parts of the image were corrupt, and not all of the pieces of software worked properly with the other parts. It was also a reflection of the time it was created and used out in the world, which was not always what we would wish to use today.

Starting in late 2017, several of us built a series of tools to generate OS/8 media images from pristine source files in a repeatable, testable way, culminating in Bill Cattey’s os8-run, which backs other features like the --disable-os8-* configuration options.

The resulting set of media images entirely replace the old ones and go well beyond each besides. All prior features are still available, though some features present on the old images are disabled by default, requiring either --enable-os8-* configure options or [package manager commands][os8pkg] to add features back in. Mostly, though, the new media images are more functional than the old ones.

If you wish to know the full details of how these media images are created, see the documentation for os8-run and that for class simh.

The remainder of this section describes some aspects of these media images which are not clear from the descriptions of the --*-os8-* configuration options above.

Baseline

The baseline for the bootable OS/8 media images comes from a set of DECtapes distributed by Digital Equipment Corporation which are now included with the PiDP-8/I software; see the media/os8/*.tu56 files. From these files and your configuration options, the os8-run script creates the baseline bootable v3d-dist.rk05 and ock-dist.rk05 disk images.

The default build creates a complete OS/8 V3D system including BUILD support, FORTRAN IV, MACREL v2, and more, but you can switch to an OCK build at compile time if you prefer.

Subtractions

It's pretty easy to run out of space on an OS/8 RK05 disk, not just because of its 2 × 0.8 MWord limit, but also because of an OS/8 limitation in the number of files on an OS/8 filesystem. We leave the archive of device drivers and the TD8E subsystem off the system packs to avoid hitting this second limit. You can add them later from OS/8 Binary Distribution DECtape #2, such as to create media for a TD8E based PDP-8/e.

Default Additions

The OS/8 RK05 disk image build process normally installs many software and data file sets to the disk image. See the option descriptions above: the "disable" option set effectively lists those packages that are installed by default, and the following set of "enable" option set lists those left out by default.

Console Enhancements

The default build enhances the console in a few ways:

  1. The SIMH PDP-8 simulator and a few select parts of OS/8 are adjusted to cope with lowercase input to varying degrees.

  2. Rubout/backspace handling is set to assume a video terminal rather than a teletype by default.

You can read more about this in the wiki.

Patches

The v3d-dist.rk05 disk image referenced above is considered a read-only master. A copy is made called v3d.rk05. This is the default OS/8 rk05 image assigned to the IF=0 and IF=7 boot options.

In keeping with the standards of good systm management this image incorporates all mandatory patches, as well as optional patches appropriate to proper operation of the system. For details on the available patches, the selection criteria, and information about other optional patches see the [OS/8 system patches][os8pat] document.

The OS/8 TU56 Tape Image

As with the OS/8 disk image, this distribution’s build system can create custom TU56 tape images from pristine source media. This replaces the old os8.tu56 binary image previously distributed with this software.

The build system actually creates four such tape images according to a 2×2 matrix of choices:

Overwriting the Local Simulator Setup

When you run sudo make install step on a system that already has an existing installation, it purposely does not overwrite two classes of files:

  1. The binary PDP-8 media files, such as the RK05 disk image that holds the OS/8 image the simulator boots from by default. These media image files are considered "precious" because you may have modified the OS configuration or saved personal files to the disk the OS boots from, which in turn modifies this media image file out in the host operating environment.

  2. The PDP-8 simulator configuration files, installed as $prefix/share/boot/*.script, which may similarly have local changes, and thus be precious to you.

Sometimes this "protect the precious" behavior isn't what you want. (Gollum!) One common reason this may be the case is that you've damaged your local configuration and want to start over. Another common case is that the newer software you're installing contains changes that you want to reflect into your local configuration.

You have several options here:

  1. If you just want to reflect the prior PDP-8 simulator configuration file changes into your local versions, you can hand-edit the installed simulator configuration scripts to match the changes in the newly-generated boot/*.script files under the build directory.

  2. If the change is to the binary PDP-8 media image files — including the generated OS/8 disk images — and you're unwilling to overwrite your existing ones wholesale, you'll have to mount both versions of the media image files under the PDP-8 simulator and copy the changes over by hand.

  3. If your previously installed binary OS media images — e.g. the OS/8 RK05 disk image that the simulator boots from by default — are precious but the simulator configuration scripts aren't precious, you can just copy the generated boot/*.script files from the build directory into the installation directory, $prefix/share/boot. (See the --prefix option above for the meaning of $prefix.)

  4. If neither your previously installed simulator configuration files nor the binary media images are precious, you can force the installation script to overwrite them both with a sudo make mediainstall command after sudo make install.

    Beware that this is potentially destructive! If you've made changes to your PDP-8 operating systems or have saved files to your OS system disks, this option will overwrite those changes!

Testing Your PiDP-8/I Hardware

You can test your PiDP-8/I LED and switch functions with these commands:

$ pidp8i stop
$ pidp8i-test

You may have to log out and back in before the second command will work, since the installation script modifies your normal user's PATH the first time you install onto a given system.

It is important to stop the PiDP-8/I simulator before running the test program, since both programs need exclusive access to the LEDs and switches on the front panel. After you are done testing, you can start the PiDP-8/I simulator back up with:

$ pidp8i start

See its documentation for more details.

License

Copyright © 2016-2020 by Warren Young. This document is licensed under the terms of the SIMH license.