PiDP-8/I SoftwareAll File in examples/

Files in directory /examples in any check-in

• routines
• Makefile.in
• bit-rotate.pal
• fpptst.ft
• hello.lst
• hello.pal
• hello.pt
• pep001-f2.ft
• pep001-f4.ft
• pep001-ire0.c
• pep001-mod.c
• pep001.ba
• pep001.bas
• pep001.c
• pep001.fc
• pep001.lst
• pep001.pal
• pep001.pt
• tratbl.fc

Example Programs

What's Provided

The `examples` directory holds short example programs for your PiDP-8/I, plus a number of subroutines you may find helpful in writing your own programs:

Example What It Does
`add.pal` 2 + 3 = 5 The simplest program here; used below as a meta-example
`hello.pal` writes "HELLO, WORLD!" to the console; tests PRINTS subroutine
`pep001*` Project Euler Problem #1 solutions, various languages
`routines/decprt` prints an unsigned 12-bit decimal integer to the console
`routines/prints` prints an ASCIIZ string stored as a series of 8-bit bytes to the console

The `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 these:

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

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

RUN

PEP001  BA    5A

TOTAL:  xxxxxxx

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 `PEP001.BA` file on the OS/8 disk first, allowing you to load it up within OS/8 BASIC like so:

``````.R BASIC
NEW OR OLD--old pep001.ba
``````

Notice that you can give the file name with the `NEW` or `OLD` command 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 `configure` script.)

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 `RUN` command, 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 `src/asm/*.pal` or `examples/*.pal`, the build process produces several output files:

Extension Meaning
`*.pal` the PAL8 assembly source code for the program; input to the process
`obj/*.lst` the human-readable assembler output
`bin/*-pal.pt` the machine-readable assembler output (RIM format)
`boot/*.script` a SIMH-readable version of the assembled code

Each of those files has a corresponding way of getting the example running in the simulator:

1. Transcribe the assembly program text to a file within a PDP-8 operating system and assemble it inside the simulator.

2. Toggle the machine code for the program in from the front panel. I can recommend this method only for very short programs.

3. Attach the `*-pal.pt` file to the simulator and read the assembly language text in, such as via the PiDP-8/I automatic media mounting feature.

4. 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 transcribe `examples/add.pal` into the OS/8 simulation on a PiDP-8/I using the OS/8 `EDIT` program:

``````.R EDIT

*0200   CLA CLL
DCA C
HLT
A,      2
B,      3
C,
← hit Ctrl-L to leave text edit mode
#E                          ← saves program text to disk

ERRORS DETECTED: 0

399 FREE BLOCKS
``````

If you see some cryptic line from the assembler like `DE C` instead of the `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 `ADD.ER` 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 `C`, pressing `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 `AND` the 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

``````

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 `Start` this 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 `TECO` over `EDIT` or MACREL over PAL8 — but the idea is the same regardless.

There are many more methods for getting program text into the simulator than simply transcribing it into an `EDIT` or `TECO` session.

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 `examples/*.pal` and `src/asm/*.pal` files are assembled by `palbart` which writes out a human-readable listing file to `obj/*.lst`, each named after the source file.

Take `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 `Load Add` 000010000000 is binary for octal 0200, the program's start address
111 011 000 000 `Dep` the first instruction, 7300 octal, is 111011000000 in binary
001 010 000 101 `Dep` 1205 octal in binary
001 010 000 110 `Dep` etc, etc.
011 010 000 111 `Dep`
111 100 000 010 `Dep`
000 000 000 010 `Dep`
000 000 000 011 `Dep`

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 toggle `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 `add.pal`. You 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 pay attention!

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.

The `palbart` assembly process described above also produces paper tape output files in RIM format in `bin/*-pal.pt`.

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:

1. Set the IF switches (first white group) to 001, and toggle ```Sing Step``` to 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 Step` while it's running. Reset the IF switches to 0.

2. Insert the USB stick containing the `*-pal.pt` file you want to load into the Pi.

3. Set the DF switches (first brown group) to 001, then toggle ```Sing Step``` again. This attaches the tape to the high-speed paper tape reader peripheral within the PDP-8 simulator. Set DF back to 0.

4. Set the switch register (SR) to 7756 (111 111 101 110) then press `Load Add`, then `Start`.

5. Hit `Stop`, then reset SR to 0200 (000 010 000 000), that being the starting location of these example programs. Press `Load Add`, then `Start` to run the program.

There is an SVG template for USB stick labels in the distribution under the `labels/` directory, for use if you find yourself creating long-lived USB sticks. See `labels/README.md` for more information.

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.