Unix V4 Emulation: Q3 2026 Experience Report

Table of Contents

1. Executive Summary

This report documents the debugging journey to boot Unix V4 (November 1973) on FreeBSD 14.3 using PDP-11 emulators. After extensive experimentation, we identified a fundamental incompatibility between SimH's console polling mechanism and FreeBSD's terminal handling.

1.1. Status: BLOCKED

Component Status Details
Tape Image OK ec0a5437… (verified)
Disk Image OK root.rk turnkey from squoze.net
SimH 3.9.0 FAIL TTI polling hang at PC 137634
Open-SimH 4.1.0 FAIL Same TTI polling hang
Kek Emulator UNTESTED Built, installed to /opt/kek

1.2. Root Cause

SimH's sim_os_poll_kbd() uses non-blocking reads (VMIN=0, VTIME=0) that create a race condition with automated input on FreeBSD ptys.

2. Debugging Strategy

Debugging flow diagram

See diagram-debug-strategy.dot for source.

2.1. Phase 1: Symptom Identification

  1. Boot hangs after tape bootstrap
  2. Ctrl-E interrupt reveals PC = 137634
  3. Instruction: TSTB (R0) where R0 = 177560 (TTI status register)

2.2. Phase 2: Root Cause Analysis

  1. Disassemble bootstrap code
  2. Identify polling loops:
    • 137616: TTO polling (output)
    • 137634: TTI polling (input) ← BLOCKER
    • 137702: TTO polling (echo)
  3. Source code analysis (sim_console.c):

       // Lines 1164-1165: Terminal init
       runtty.c_cc[VMIN] = 0;   // instant return
       runtty.c_cc[VTIME] = 0;  // no timeout
    
       // Lines 1209-1218: Keyboard poll
       t_stat sim_os_poll_kbd (void) {
           status = read(0, buf, 1);
           if (status != 1) return SCPE_OK;  // no char
           return (buf[0] | SCPE_KFLAG);
       }
    

2.3. Phase 3: Attempted Fixes

Approach Result Why Failed
Breakpoint + deposit Infinite loop Hardware controls TTI status
SEND commands Input not seen Timing race
Expect automation Same race Characters arrive between polls
tmux send-keys Race condition Same timing issue
simh 3.9.0 Same hang Same polling code

3. Research Path

Research path diagram

See diagram-research-path.dot for source.

3.1. Sources Consulted

3.1.1. Primary Archives

  • squoze.net/UNIX/v4/ - Tape images, documentation
  • archive.org/details/utah_unix_v4_raw - Original tape
  • tuhs.org - Unix Heritage Society

3.1.2. Working Examples

3.1.3. Emulator Documentation

  • SimH GitHub: sim_console.c source
  • Kek GitHub: Alternative POSIX emulator
  • PDP-11 Processor Handbook (register maps)

3.2. Key Finding

All documented successful boots are on Linux, not FreeBSD. The difference may be in terminal/pty handling or SimH build configuration.

4. Experiments Flow: Week of 2026-06-08

Experiments flow for next week

See diagram-experiments-flow.dot for source.

4.1. Day 1-2: Archive & Version Check

# Check for updates
curl -sI http://squoze.net/UNIX/v4/
pkg search simh
freebsd-version

4.2. Day 3: Kek Emulator Testing

# Test with RK05 disk
/opt/kek/kek -r root.rk -R rk05 -b rk05 -d

# Test with tape
/opt/kek/kek -T unix_v4.tap -b tm11 -d

4.3. Day 4: SimH Source Patching

Proposed patch to sim_console.c:

// Option 1: Use blocking read with timeout
runtty.c_cc[VMIN] = 1;
runtty.c_cc[VTIME] = 1;  // 0.1s timeout

// Option 2: Add delay in poll
t_stat sim_os_poll_kbd (void) {
    usleep(1000);  // 1ms delay
    status = read(0, buf, 1);
    ...
}

4.4. Day 5: Linux Comparison

# On Arch Linux VM
pacman -S simh
pdp11 boot.ini
# Compare behavior

4.5. Day 6-7: Document Results

  • Update REBUILD-PLAN.md
  • File SimH issue if patch works
  • Update this experience report

5. Technical Reference

5.1. PDP-11 Console Registers

Address Name Purpose
177560 RCSR TTI status (bit 7 = ready)
177562 RBUF TTI data buffer
177564 XCSR TTO status (bit 7 = ready)
177566 XBUF TTO data buffer

5.2. Polling Loop Addresses

Address Instruction Purpose
137616 TSTB (R1) TTO output ready
137634 TSTB (R0) TTI input ready
137636 BGE 137634 Loop back if not ready
137702 TSTB 177564 TTO echo ready

5.3. SimH CSR Defines

#define CSR_DONE  0200   // bit 7 - device ready
#define CSR_IE    0100   // bit 6 - interrupt enable

6. Artifacts

6.2. Documentation

File Description
experiments/notes/session-2026-06-01.md Full session log
experiments/notes/failed-experiments-freebsd-14.3.md 12 experiments
REBUILD-PLAN.md Rebuild checklist
GOAL.md Project objectives
DEBUGGING.md Console analysis

6.3. Diagrams (this directory)

File Description
diagram-debug-strategy.dot Debugging flow
diagram-research-path.dot Research sources
diagram-experiments-flow.dot Next week plan

7. Conclusion

Unix V4 emulation on FreeBSD 14.3 is blocked by a timing race in SimH's console polling. The next steps are:

  1. Test Kek emulator (different polling implementation)
  2. Patch SimH source (add polling delay)
  3. Compare with working Linux setup

The 1973 operating system is tantalizingly close to running–we can see the tape bootstrap prompt and send commands–but the emulated TTI device doesn't signal "ready" in time for the polling loop.

"The gap between what we know and what we can make the computer do is the story of programming." – adapted for debugging

Report generated 2026-06-02 on FreeBSD 14.3-RELEASE-p7