What It Is
This repository is the current official PiDP-8/I software development nexus. Here we continue development of the software from the last stable software version published on the kit information site. This software differs in several major ways and dozens of minor ways from that old software.
You can download the latest release — cut on 2021.02.14 — as a tarball. (About 17 MB.)
If you want the bleeding edge version, you can either check it out from the Fossil source code repository powering this web site by following the instructions in the contribution guide or you can simply download the tip of trunk as a tarball.
README.md file for more information on how to install this into your existing Raspberry Pi OS.
Those with plenty of Internet bandwidth and a micro SD card they don't mind overwriting (8 GB minimum) may prefer to download the software hosted here in binary OS image form. There are two versions, each based on Raspberry Pi OS Lite (Buster, 2021.01.11 release) and each roughly 850 MB:
It takes about one and a half of the four available CPU cores on a Pi 3B while running about 23× faster than a real PDP-8/I. (Slower on a Pi 2, faster on a Pi 4.)
Single-core version, v2021.02.14 — For those running on Raspberry Pi Model A+ and B+ boards or the Pi Zero, this alternative download disables the ILS feature. It also slows the simulator down so it uses only about half the available CPU power to leave some host CPU power for background tasks. This allows it to run PDP-8 software roughly 3× as fast as a real PDP-8/I, depending on the speed of the Pi you run it on.
This image will also run on a multi-core Pi. It will run PDP-8 software slower than the ILS version, since it will also be affected by the intentional 50% CPU usage limit, but because each one of those cores are faster than a single-core Pi and the other cores can take the load of background tasks, it still manages to run PDP-8 software roughly 10× faster than a real PDP-8/I.
See the installation instructions for more information.
The binary OS releases are not always updated when the source code releases are cut, since it's about a full day's work to create those binary releases. Addressing that is the topic of the next section.
As shipped, the binary OS images above also contain the PiDP-8/I software source code and Fossil, the tool that lets you download updated source code as it becomes available. Updating the software is therefore much simpler than downloading the whole OS all over again and overwriting your perfectly good SD card. If you are updating your existing release to a newer release version, this works:
$ cd ~/pidp8i $ fossil update $ make reconfig $ tools/mmake && sudo make install $ sudo systemctl daemon-reload $ pidp8i restart $ pidp8i
If you need to switch from the release branch to the bleeding-edge "trunk" version — such as because you want to try a change that has not yet been released — simply modify the second command like so:
$ fossil update trunk
You only need the branch argument to the
fossil update command when switching branches. Once you've switched from the release branch to the trunk, you don't need to keep specifying "trunk" because Fossil keeps your checkout directory on a given branch once you've switched to it. Thus, you'd only need to give a branch name when switching back to the release branch:
$ fossil update release
The above commands assume typical situations and default options. For more advanced cases, see the
One of the most time consuming steps in building our PiDP-8/I software is building the OS/8 RK05 disk images from pristine, tested, curated sources. If you simply want the resulting disk images, we provide them here for you to download:
||OS/8 V3D in its as-distributed state: no patches, no add-ons|
||non-bootable disk containing the contents of all ten OS/8 V3D source tapes|
||OS/8 Combined Kit (OCK) version of the
||OS/8 Combined Kit (OCK) version of the
||OS/8 Combined Kit (OCK) version of the
These disk images were last updated on 2021.02.14 in conjunction with the release made at the same time and so are considered stable.
These disk images should work under SIMH on any platform, and could potentially even be written back to real RK05 disk packs and run on actual PDP-8 hardware! Let us know how you're using these files on the PiDP-8/I mailing list; we're curious how far these spread.
If you want a version of the
bin disk image with any of the optional
--enable-os8-* options set or with some of the default-enabled features stripped out, you will have to download this software, configure it as suits your needs, and build it yourself. The software currently builds on several different platforms, not just the Raspberry Pi.
The current PiDP-8/I software has many more features and many fewer bugs than Oscar's version, but in the end, both do more or less the same thing, so Oscar's documentation still applies fairly well. The primary source of discrepancies between his documentation and our software stem from file name changes.
You're welcome to discuss this version of the PiDP-8/I software on the PiDP-8/I mailing list, hosted by Google Groups. Those active in its development participate there and usually react to posts about this software quickly.
This software project has its own documentation and tutorials, which I've collected here for convenience:
The top-level README file tells how to configure, build, and start using the PiDP-8/I software.
Configuration of the simulator's throttle is complicated enough to deserve its own document.
The binary OS image guide explains how to install it to an SD card and get started.
While building your PiDP-8/I, you may run into some trouble which can be diagnosed by the
pidp8i-testprogram shipped with the software distribution and documented here.
The project wiki contains several tutorials, design documents, etc.
The project ships several example programs for those who want to learn to program the PDP-8. This is not meant to be a comprehensive tutorial, but more to help you bridge the gap in material meant for a real PDP-8, which won't talk about the superior methods we have for program input now: SIMH boot scripts, copy-paste via SSH, etc.
We ship a Python class called
simhfor controlling SIMH and OS/8 running under SIMH from the host system. See its tutorial.
There is a tutorial for the DCP disassembler installed on the OS/8 disk packs by default.
The default OS/8 boot disk in the distribution has many patches applied, which are described in the linked document, along with information about the DEC patches we have chosen not to apply.
There are several documents about the U/W FOCAL V4E distribution included on the standard OS/8 boot disk, which you can find by starting with our U/W FOCAL manual supplement.
If you want to know what has changed in the software since Oscar Vermeulen's last release on 2015.12.15, see the ChangeLog.
If you would like to help contribute to the development of the PiDP-8/I software project, see "the contribution guide".
The KiCad PiDP-8/I front panel schematic was converted to PDF by Tony Hill. (400 kB)
Are you wondering who brought all of this software, hardware, and documentation to you? That is summarized in the project's authors file. Those pieces are included with the project under a variety of licenses.
The PiDP-8/I software project is based on the actively-developed official version of SIMH. (As opposed to Bob Supnik's personal 3.x branch which still comes up high in search results.) The SIMH project has its own documentation, but for convenience I've provided PDF versions of the relevant subset here:
SIMH Main Manual — If you're going to read or modify
boot/*.script, or you want to give commands at the
sim>prompt you get by pressing Ctrl-E from within the PiDP-8/I simulator, you need to read this manual.
PDP-8 Simulator Manual — This addendum to the main SIMH manual covers the details specific to the PDP-8 simulator. (The main manual covers functionality common to all of the simulators bundled with SIMH.)
SIMH FAQ — Frequently-asked questions about SIMH. (With answers!)
While most of the information about the PDP-8 is widely available on the Internet and may thus be easily found by Googling, we have a small number of documents here that are not so easy to come by, plus some links that don't seem to come up as high in Google searches as they ought to:
DEC's 1969 edition System User's Guide for the PDP-8 family computers, the pinnacle of which was the PDP-8/I at that time. DEC published many editions of this guide, and the newer versions come up far more frequently in web searches, but they're often not OCR'd (whereas this version is) and they tend to focus on the newer PDP-8 models which don't apply entirely to the PDP-8/I.
DEC's 1973 Small Computer Handbook, because when dealing with SIMH, you actually want documentation of the newer models of PDP-8, since SIMH simulates a fairly tricked-out late-model PDP-8; there is no easy way to restrict SIMH to support only the features that existed at the time of the PDP-8/I. For example, SIMH's PDP-8 simulator will process mode B EAE instructions introduced in the PDP-8/e, well after the PDP-8/I came out with its less functional EAE option.
You may want to split the difference between these two documents and try to find a 1968 edition of the Small Computer Handbook. The closest I'm aware of online is the 1967 edition which mentions the PDP-8/I inside, but shows the original PDP-8 "Straight Eight" and a PDP-8/S on the cover. I assume it was written while the PDP-8/I design was being finalized, so it may be fairly accurate, and it may be full of bugs; I couldn't say. I happen to have here a paper copy of the 1968 edition, which you can tell from the 1967 edition by the yellow-green themed cover (JPEG, 473 kB) showing the standard rack-mounted and rare console version of the PDP-8/I.
The documentation produced by the Raspberry Pi Foundation can be quite useful to one running the PiDP-8/I software. Third parties have also produced useful Raspberry Pi guides. We recommend that you start with these resources: