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
See diagram-debug-strategy.dot for source.
2.1. Phase 1: Symptom Identification
- Boot hangs after tape bootstrap
- Ctrl-E interrupt reveals PC = 137634
- Instruction:
TSTB (R0)where R0 = 177560 (TTI status register)
2.2. Phase 2: Root Cause Analysis
- Disassemble bootstrap code
- Identify polling loops:
- 137616: TTO polling (output)
- 137634: TTI polling (input) ← BLOCKER
- 137702: TTO polling (echo)
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
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
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:
- Test Kek emulator (different polling implementation)
- Patch SimH source (add polling delay)
- 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