Files in directory /examples in any check-in
examples directory holds short example programs for your PiDP-8/I,
plus a number of subroutines you may find helpful in writing your own
|Example||What It Does|
||2 + 3 = 5 The simplest program here; used below as a meta-example|
||writes "HELLO, WORLD!" to the console; tests PRINTS subroutine|
||Project Euler Problem #1 solutions, various languages|
||prints an unsigned 12-bit decimal integer to the console|
||prints an ASCIIZ string stored as a series of 8-bit bytes to the console|
pep001.* files are a case study series in solving a simple
problem, which lets you compare the solutions along several axes. Some
are much longer than others, but some will run faster and/or take less
memory. It is interesting to compare them. There are writeups on each of
pep001.pal— PAL8 Assembly Language
pep001.bas— OS/8 BASIC
pep001-*.c— two solutions for the CC8 dialects of C
pep001.fc— U/W FOCAL
pep001-f?.ft— FORTRAN II and IV
How to Use the BASIC Examples
Here's one way to run the
pep001.ba program mentioned above:
.R BASIC NEW OR OLD--NEW FILE NAME--PEP001.BA READY 10 FOR I = 1 TO 999 10 FOR I = 1 TO 999 20 A = I / 3 \ B = I / 5 30 IF INT(A) = A GOTO 60 40 IF INT(B) = B GOTO 60 50 GOTO 70 60 T = T + I 70 NEXT I 80 PRINT "TOTAL: "; T 90 END SAVE READY RUN PEP001 BA 5A TOTAL: xxxxxxx READY BYE
While you could simply type all of that, if you're SSH'd into the
PiDP-8/I, you could instead just copy-and-paste the bulk of the text
above into OS/8 BASIC from the
examples/pep001.ba file on the host
side. This and several more useful methods are given in the companion
article Getting Text In.
Other methods given in that article let you create the
on the OS/8 disk first, allowing you to load it up within OS/8 BASIC
.R BASIC NEW OR OLD--old pep001.ba
Notice that you can give the file name with the
above, rather than wait for OS/8 BASIC to prompt you for it separately.
Also notice that our version of OS/8 BASIC has a patch applied to it by
default which allows it to tolerate lowercase input. (This patch may be
disabled by giving the
--lowercase option to the
I obscured the output in the first terminal transcript above on purpose, since I don't want this page to be a spoiler for the Project Euler site.
If you get a 2-letter code from BASIC in response to your
it means you have an error in the program. See the BASIC section of the
OS/8 Handbook for a decoding guide.
How to Use the Assembly Language Examples
For each PAL8 assembly program in
the build process produces several output files:
||the PAL8 assembly source code for the program; input to the process|
||the human-readable assembler output|
||the machine-readable assembler output (RIM format)|
||a SIMH-readable version of the assembled code|
Each of those files has a corresponding way of getting the example running in the simulator:
Transcribe the assembly program text to a file within a PDP-8 operating system and assemble it inside the simulator.
Toggle the machine code for the program in from the front panel. I can recommend this method only for very short programs.
*-pal.ptfile to the simulator and read the assembly language text in, such as via the PiDP-8/I automatic media mounting feature.
Boot SIMH with the example in core, running the program immediately.
I cover each of these options below, in the same order as the list above.
Option 1: Transcribing the Assembly Code into an OS/8 Session
Perhaps the most period-correct of the options given here is to
examples/add.pal into the OS/8 simulation on a
PiDP-8/I using the OS/8
.R EDIT *ADD.PA< #A ← append to ADD.PA *0200 CLA CLL MAIN, TAD A TAD B DCA C HLT A, 2 B, 3 C, ← hit Ctrl-L to leave text edit mode #E ← saves program text to disk .PAL ADD-LS ERRORS DETECTED: 0 LINKS GENERATED: 0 .DIR ADD.* /A ADD .PA 1 ADD .BN 1 ADD .LS 1 399 FREE BLOCKS
If you see some cryptic line from the assembler like
DE C instead
ERRORS DETECTED: 0 bit, an error has occurred. Table 3-3 in
my copy the OS/8 Handbook explains these. You will also have an
file explaining what happened.
You can instead say
EXE ADD to assemble and execute that program in a
single step, but beware that because the program halts the processor,
your OS/8 session also halts. If you take the opportunity as intended to
examine memory location
C — 0207 — pressing
Start to resume will
cause the processor to try executing the instruction at 0210, and who
knows what that will do? Even if you pass up the opportunity to examine
Start immediately after the halt will do the same,
except that we know what it will do: it will try to execute the 0002
value stored at
A as an instruction! (I believe it means
accumulator with memory location 2.)
The solution to these problems is simple:
.EDIT ADD ← don't need "R" because file exists #R ← read first page in; isn't automatic! #4D ← get rid of that pesky DCA line #5I ← insert above "A" def'n, now on line 5 JMP 7600 ← Ctrl-L again to exit edit mode #E ← save and exit .EXE ADD
As before, the processor stops, but this time because we didn't move the
result from the accumulator to memory location
C, we can see the
answer on the accumulator line on the front panel. Pressing
time continues to the next instruction which re-enters OS/8. Much nicer!
This option is the most educational, as it matches the working
experience of PDP-8 assembly language programmers back in the day. The
tools may differ — the user may prefer
MACREL over PAL8 — but the idea is the same
There are many more methods for getting program text into the
simulator than simply transcribing it into an
Option 2: Toggling Programs in Via the Front Panel
One of the automatic steps in building the PiDP-8/I software is that
each of the
src/asm/*.pal files are assembled by
palbart which writes out a human-readable listing file to
each named after the source file.
obj/add.lst as an example, in which you will find three
columns of numbers on the code-bearing lines:
10 00200 7300 11 00201 1205 12 00202 1206 13 00203 3207 14 00204 7402 16 00205 0002 17 00206 0003
The first number refers to the corresponding line number in
add.pal, the second is a PDP-8 memory address, and the third is
the value stored at that address.
To toggle the
add program in, press
Stop to halt the processor, then
twiddle the switches like so:
|Set SR Switches To...||Then Toggle...||Because...|
|000 010 000 000||
||000010000000 is binary for octal 0200, the program's start address|
|111 011 000 000||
||the first instruction, 7300 octal, is 111011000000 in binary|
|001 010 000 101||
||1205 octal in binary|
|001 010 000 110||
|011 010 000 111||
|111 100 000 010||
|000 000 000 010||
|000 000 000 011||
To run it, repeat the first step in the table above, loading the
program's starting address (0200) first into the switch register (SR)
and then into the PDP-8's program counter (PC) via
Load Add. Then
Start to run the program.
If you then toggle 000 010 000 111 into SR, press
Load Add followed by
Exam, you should see 000 000 000 101 in the fourth row of lights — the
Accumulator — that being the bit pattern for "five" at memory location
0207, the correct answer for "2 + 3", the purpose of
could load that address back up again and
Dep a different value into
that location, then start the program over again at 0200 to observe that
this memory location does, indeed, get overwritten with 0005.
We only need one
Load Add operation in the table above because all of
the memory addresses in this program are sequential; there are no jumps
in the values in the second column. Not all programs are that way, so
Beware that this program does not contain an explicit value for memory
location 0207 at the start, but it does overwrite this location with the
answer, since location
C is defined as having the address just after
the last value you entered via SR above, 0206. That is the source of the
"07" in the lower two digits of the fourth instruction, 3207.
Option 3: Loading a Program from Paper Tape
palbart assembly process described above also produces paper tape
output files in RIM format in
One way to load these assembly examples into your PiDP-8/I is to copy each such file to a USB stick, one file per stick. Then, use the automatic USB media mounting feature of the PiDP-8/I to attach it to the simulator.
The following is distilled from the How to Use the PiDP-8/I section of the PiDP-8/I documentation:
Set the IF switches (first white group) to 001, and toggle
Sing Stepto reboot the simulator into the high-speed RIM loader. If the simulator wasn't already running, restarting the simulator with IF=1 will achieve the same end as toggling
Sing Stepwhile it's running. Reset the IF switches to 0.
Insert the USB stick containing the
*-pal.ptfile you want to load into the Pi.
Set the DF switches (first brown group) to 001, then toggle
Sing Stepagain. This attaches the tape to the high-speed paper tape reader peripheral within the PDP-8 simulator. Set DF back to 0.
Set the switch register (SR) to 7756 (111 111 101 110) then press
Load Add, then
Stop, then reset SR to 0200 (000 010 000 000), that being the starting location of these example programs. Press
Load Add, then
Startto run the program.
There is an SVG template for USB stick labels in the distribution under
labels/ directory, for use if you find yourself creating
long-lived USB sticks. See
labels/README.md for more
This USB method is most convenient for often-reused binary media images.
Option 4: Booting SIMH with the Example in Core
Another step in the PiDP-8/I software build process produces a
boot/*.script file for each
obj/*.lst file produced. These files are
direct translations of the machine code from the assembler's listing
file into SIMH
deposit commands, populating the simulated PDP-8's core
memory with the program's machine code. Each script ends with a jump to
the start of the program.
You can thus load and run each example at the Linux command line with a command like this:
$ bin/pidp8i-sim boot/add.script
That runs the
examples/add.pal program's assembled binary code under
the simulator, just as if you'd loaded it there with option #3 above.
Copyright © 2016-2018 by Warren Young. This document is licensed under the terms of the SIMH license.