Appendix C: Source Code Index¶
Canonical repository: github.com/gloveboxes/Z80ROMlessSBC. All phase applications are cumulative: each phase links the shared modules proven by earlier phases, while remaining independently buildable for hardware bring-up.
Project Build Files¶
| File | Purpose |
|---|---|
| CMakeLists.txt | Pico SDK import, Pico 2 W target, project languages, and protected firmware flash linker boundary |
| src/CMakeLists.txt | Shared firmware libraries, phase registration, and the manual Phase 9, automatic Phase 9 (z80_stage09_cpm_loader_images) and Phase 10 CP/M artifact targets |
| .gitignore | Generated build, Python cache, and assembler-output exclusions |
| package.json, package-lock.json | Repository utility commands, including generated breadboard layout |
| MkDocs configuration, requirements | Documentation navigation, theme, plugins, and pinned Python dependencies |
| documentation workflow | Strict MkDocs build and GitHub Pages deployment |
Cumulative Phase Applications¶
| Phase | Application | Target definition | Responsibility |
|---|---|---|---|
| 0 | Power checklist | Hardware-only | Empty-socket wiring, rail, resistance, and startup-state checks |
| 1 | main.c | CMakeLists.txt | Safe supervisor startup and GPIO walk |
| 2 | main.c | CMakeLists.txt | Buffered controls and variable-frequency clock |
| Exception | reset_meter.c | CMakeLists.txt | z80_reset_meter: serial-guided, reset-held static multimeter checks with CPU/SRAM fitted and interface buffers optionally absent; no execution or SRAM loading |
| 3 | main.c | CMakeLists.txt | Buffered controls, four-bit port monitor and WAIT release; historical directory name retained |
| 4 | main.c | CMakeLists.txt | CPU-assisted walking-address test, deferred until Phase 6 after passive Phase 4 wiring |
| 5 | main.c | CMakeLists.txt | 8-bit data-bus drive, sample, and isolation tests |
| 6 | main.c | CMakeLists.txt | Assisted loader and full-memory validation; historical directory name retained |
| 6 diagnostic | step_loader.c, full_memory_test.c | CMakeLists.txt | z80_stage06_step_loader: f automatic 64 KiB low/high-byte fill/read tests with concise results; b/n retain the three-byte console-stepped diagnostic |
| 6 PWM screening | pwm_memory_test.c | CMakeLists.txt | z80_stage06_pwm_memory: serial-gated 1-8 MHz PWM screening that writes/reads/compares four patterns across all SRAM, with bounded progress and at least 60 seconds per distinct rate |
| 6 exact 20 MHz | pwm_memory_test.c | CMakeLists.txt | z80_stage06_pwm_memory_20mhz: single-rate full-RAM PWM screen with an isolated 120 MHz supervisor-clock startup |
| 6 one-hour math soak | math_soak_test.c, math_soak.asm, math_soak_program.h | CMakeLists.txt | z80_stage06_math_soak_20mhz: serial-gated resident arithmetic/flags/comparisons, nested calls/stack and 56 KiB SRAM sweeps; independent reference answers, 120 MHz supervisor, first-error stop |
| 6 fourteen-hour math soak | math_soak_test.c | CMakeLists.txt | z80_stage06_math_soak_14h_20mhz: same resident workload and first-error stop as the one-hour build, minimum 50,400 seconds, complete-cycle finish, 64-bit check totals |
| 6 no-I/O scope | scope_test.c, scope_test.asm, math_workload.asm, scope_test_program.h | CMakeLists.txt | z80_stage06_scope_20mhz: isolated continuous 20 MHz CPU/stack/56 KiB SRAM workload, no Z80 I/O or reporting pauses, first failure saved in SRAM and HALT; retrieve only after stop; no live/timed PASS |
| 6 bus grants | bus_grant_test.c | CMakeLists.txt | z80_stage06_bus_grant: reset/fetch, stepping, low-rate execution and BUSREQ/BUSACK checks consolidated into Phase 6 |
| 8 | main.c | CMakeLists.txt | Virtual-ROM preload and synchronous I/O trapping |
| 9 | main.c, ansi_input.c, ansi_input.h, disk_diagnostic.asm | CMakeLists.txt | Manual diagnostics or automatic verified boot (z80_stage09_cpm_loader), 20 MHz scope-measured CP/M clock, USB terminal with Altair ANSI key mapping, read-only all-drive Z80 diagnostic and journaled disks |
| 10 | shared Phase 9 main.c | CMakeLists.txt | Tested automatic CP/M loader with core-1 networking and USB fallback |
Shared Firmware Modules¶
Phases 9 and 10 also share
usb_console.c
and its header:
core-1 USB/alarm initialization, endpoint ownership and bounded multicore
diagnostic routing. Supervisor parsing runs on core 1 in the shared application;
queued Z80 control requests execute only on core 0.
| Module | Public interface | Implementation | Responsibility |
|---|---|---|---|
| Pin map | pins.h | Header-only | Authoritative Pico GPIO assignments |
| Supervisor | supervisor.h | supervisor.c | Safe GPIO startup and fail-safe isolation defaults |
| Clock | clock.h | clock.c | PWM frequency selection, stop/resume, and single-cycle clocking |
| Buses | bus.h | bus.c | Independent data OEs, preload/isolation, byte sampling and four-bit port decode |
| SRAM | sram.h | sram.c | Injected Z80 byte access, image load/verify, RAM patterns and March test |
| CPU | cpu.h | cpu.c | Loader preparation, reset/restart, flash bus grant and fail-closed state |
| I/O trap | io_trap.h | io_trap.c | Synchronous Z80 IN/OUT interception and fault counters |
| Extended I/O | io_ports.h | io_ports.c, io_service.c, io_service_platform.c | ROMLESS-SVC/1 transport, independent timer port, worker, clock and utilities |
| Weather | weather.h | weather.c, weather_http.c, weather_network.cpp | Phase 10 cached current/forecast ABI, bounded HTTP decoding and asynchronous verified HTTPS |
| Chat | chat.h | chat.c, chat_stream.c, chat_network.cpp | Phase 10 CHATC11 ABI, core-1 streaming OpenAI/Ollama HTTP(S), bounded backpressure and cancellation |
| Persistent environment | environment.h | environment_store.c, shared ENV parser | Alternating boot-tail snapshots and host-compatible ENV commands |
| Flash disk | flash_disk.h | disk_device.c | Z80-facing command/status, drive, LBA, and 128-byte data ports |
| Flash layout | flash_layout.h | Header-only | Firmware, journal, boot-package, and disk-slot offsets |
| Flash backend | flash_backend.h | flash_backend.c | Manifest validation, SRAM boot load, journal recovery, and core-1 commits |
| Console router | terminal.h | terminal_queue.c | Bounded RX/TX rings, short critical sections, constant-time handover and exclusive USB/browser ownership |
| Network lifecycle | network_runtime.h | network_runtime.cpp, network_services.c | Independent core-1 Wi-Fi/retry, address publication, SNTP and application network-service scheduling |
| Web terminal | web_terminal.h | web_terminal.cpp, WebSocket library, transport regressions | HTTP/WebSocket session, four-frame acknowledged output, batched enqueue/flush, retained input, heartbeat, bounded receive/dispatch and callback-safe teardown |
Phase 9/10 Core Ownership¶
The shared main.c enters core0.c for startup, Z80 control, the disk self-test and Phase 10 OLED/speaker I2C. status_report.c formats the console status and help reports from a read-only snapshot. core1.c owns USB parsing and disk/service/network worker scheduling. core_coordination.h and core_coordination.c hold the shared publication words and supervisor queue.
CP/M, Disk, and Web Tooling¶
| Area | Files | Purpose |
|---|---|---|
| Flash and USB supervision | pico_flash.py, pico_supervisor.py, requirements-flash.txt, test_pico_flash.py, test_pico_disks.py | Discovered-port Phase 9 commands, graceful picocom disconnection, clean stop/flush, verified firmware or selected no-backup disk writes, journal and Drive A compatibility checks, and host safety tests |
| Native CP/M | README, z80_bios.asm, build_images.py, test_build_images.py | 64K CCP/BDOS image, native BIOS, boot package, full-flash composition, and host regression tests |
| Dynamic debug I/O | adapter README, adapter entry point, port dispatcher | Project-hosted SBC disk adapter, complete Altair host port drivers, interrupt service, and ANSI terminal-input pipeline |
| Disk geometry and images | README, geometry.py, native directory | Shared CP/M geometry and the four exact 512 KiB drive images, with upstream license |
| Browser terminal | Terminal/index.html, embed_html.py | Copied xterm.js terminal, update tool, and deterministic build-time HTML compression |
| Network configuration | lwipopts.h, network_setup.c | Core-1 polling architecture and USB provisioning through existing ENV snapshots; remote-FS address stored only |
| Status OLED | oled_display.cpp, display_i2c.cpp, display_i2c.pio, oled_display_test.cpp | Core-0 SSD1315 128x32 cached IP address, minute-only uptime and two-byte heartbeat; PIO0/DMA I2C on GP26/GP22 and assembled-PIO transport/failure regressions |
| Speaker | speaker_io.cpp, speaker_bridge_test.cpp | Core-0 port 15h ATtiny85 packet bridge, bounded request queue, deferred IN replies and clock-stretched 400 kHz reads/writes on the shared OLED bus |