From b42ecaed412be2e30b9e780eb7c9e46e1535f26f Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 26 Aug 2026 13:28:33 -0300 Subject: Make the toolchain a package another build can drive, and move the editor's glue to the editor --- README.md | 18 +- build.zig | 727 ++++++++++++++++++++++++++++---------------- build.zig.zon | 46 +++ examples/selftest.zig | 321 ------------------- examples/uartperf.zig | 2 +- src/pardes/app.zig | 483 ----------------------------- src/pardes/input_rescue.zig | 248 --------------- src/pardes/uart.zig | 153 ---------- tools/bench_main.zig | 3 +- 9 files changed, 531 insertions(+), 1470 deletions(-) create mode 100644 build.zig.zon delete mode 100644 examples/selftest.zig delete mode 100644 src/pardes/app.zig delete mode 100644 src/pardes/input_rescue.zig delete mode 100644 src/pardes/uart.zig diff --git a/README.md b/README.md index 33fc3f5..669e893 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ zig-out/bin/p4-console --port /dev/ttyUSB1 --baud 115200 | build, warm | ~1 s | 0.07 s | **0.088 s** (cache hit, no work) | | build, one file edited | ~1 s | 0.07 s | **0.121 s** | | flash + verify + run | ~2 s (esptool + stub) | ~2 s | **0.277 s** | -| host dependencies | ESP-IDF 663 MB + toolchain 3.4 GB + Python | Zig + system LLD + esptool | **Zig** | +| host dependencies | ESP-IDF 663 MB + toolchain 3.4 GB + Python | Zig + system LLD + esptool | **Zig** (the two pardes steps also want the sibling editor checkout — see Requirements) | | artefacts per build | ~1,100 files | 2 | **1** | The 66 KB → 1 KB step is the interesting one. `esptool` refuses to put two flash-mapped segments @@ -62,7 +62,17 @@ ESP32-P4 rev v1.3 silicon. ## Requirements -* Zig 0.16.0. That is the whole list. +* Zig 0.16.0, plus a network fetch on the first build. `build.zig.zon` now pins exactly one package, + `cloud9` — the base 9P2000 implementation — and only the GPIO 9P application reaches for it + (`zig build -Dapp=../02-pardes-code/src/esp32p4_9p.zig`). Zig fetches it into `zig-pkg/`, it has + no dependencies of its own, and nothing else here compiles it: `zig build`, everything under + `examples/`, the host tests and the harnesses want nothing beyond Zig and this checkout. +* Two steps are the exception, because they build somebody else's program: `zig build -Dpardes` + and `zig build selftest` read source across a sibling-relative path from the pardes editor's + checkout at `../02-pardes-code/` (the application root and `input_rescue.zig` for the former, the + on-die suite for the latter), and `-Dpardes` also links `-Dpardes-obj`, which that checkout's own + `zig build -Dplatform=esp32p4` emits into its `zig-out/`. Still not a package dependency — the + seam is files on disk — but without that checkout beside this one those two steps cannot run. * Membership of whatever group owns the serial port (`uucp` on Arch, `dialout` on Debian). * An ESP-IDF second-stage bootloader and partition table already in flash at `0x2000` and `0x8000`. This toolchain builds and flashes *applications*; the bootloader is still Espressif's. See @@ -89,7 +99,7 @@ Everything is a `b.option`, so `zig build -h` lists them all. | `-Dseconds=` | `5` | how long `monitor` listens | | `-Dconsole-baud=` | `b115200` | the interactive console's rate: what the bootloader leaves UART0 at. Distinct from `-Dbaud`, which the ROM loader auto-detects | | `-Dpardes=` | `false` | build the pardes editor as the application. Needs the object below | -| `-Dpardes-obj=` | `../02-pardes-code/zig-out/pardes-p4.o` | the editor, compiled freestanding by its own build and linked here | +| `-Dpardes-obj=` | `../02-pardes-code/zig-out/pardes-esp32p4.o` | the editor, compiled freestanding by its own build and linked here | ### Driving the editor over the wire @@ -179,7 +189,7 @@ tools/console.zig the interactive bridge: raw stdin <-> UART, and the windo src/soc.zig comptime register model: GPIO, IOMUX, mask-ROM entry points, cycle counter src/appdesc.zig esp_app_desc_t, linked as its own object so it cannot be optimised away src/main.zig demo: prints what it can prove, then blinks -src/pardes/ the pardes editor as firmware: entry, heap, UART, and the C ABI it links to +-Dpardes app root ../02-pardes-code/src/esp32p4/ — entry, heap, UART, input rescue, on-die suite examples/minimal.zig the floor: 432 B, blinks and nothing else examples/echo.zig UART0 duplex echo: the proof that receive works on the die examples/memprobe.zig what RAM this board actually has, measured rather than assumed diff --git a/build.zig b/build.zig index 6b62524..fef6fd4 100644 --- a/build.zig +++ b/build.zig @@ -10,13 +10,41 @@ //! the link, and the image builder and flasher are ordinary Zig code (tools/) imported straight //! into this file, so they produce no artefacts of their own. What lands in zig-out is the ELF and //! the image, and nothing else. +//! +//! ## As a dependency +//! +//! Everything above is also callable from another package's build.zig: `pub fn chipTarget`, +//! `pub fn firmware`, `pub fn hostTools` and the `pub` step types below are the whole surface, and +//! this file's own `build()` drives them, so there is one implementation of each and no second copy +//! to drift. A dependent obtains them with `@import("zig_p4")` and passes THIS package's builder - +//! `b.dependency("zig_p4", .{}).builder` - to every one of them, because they resolve source paths +//! and cache inputs relative to this root. const std = @import("std"); -const image = @import("tools/image.zig"); -const serial = @import("tools/serial.zig"); -const rom = @import("tools/rom.zig"); +// `pub` because a dependent needs these types to talk to the steps below: `image.Options` is the +// argument of every image, flash and size step, `serial.Baud` of every port step, and `rom.Loader` +// is the flasher itself. Re-exported here rather than made reachable some other way because +// build.zig is the one file a dependent can `@import`. +pub const image = @import("tools/image.zig"); +pub const serial = @import("tools/serial.zig"); +pub const rom = @import("tools/rom.zig"); pub fn build(b: *std.Build) void { + // Consumed as a dependency, this `build()` has nothing to offer and must not run. + // + // Zig runs a dependency's `build()` eagerly, at configure time, on every build of the + // dependent - whatever its target. Everything below the register module is firmware, and + // building the register module means reading ESP-IDF's headers from disk, which `idfRegisters` + // exits the process over when the checkout is absent. So without this line, merely DECLARING + // this package would make an ESP-IDF checkout a hard requirement of every build of every + // dependent, including the ones that never mention this chip. That is the same failure mode - + // in the same direction, from the other side - as the nesting recorded under `-Dpardes` below. + // + // `pkg_hash` is `""` in the root package and the package hash otherwise (std/Build.zig:93-94), + // which is exactly the question being asked. A dependent calls the `pub fn`s directly with its + // own options, so there is nothing here it loses. + if (b.pkg_hash.len != 0) return; + // ---------------------------------------------------------------- board and target knobs const port_path = b.option([]const u8, "port", "serial port (default /dev/ttyUSB0)") orelse "/dev/ttyUSB0"; const baud = b.option(serial.Baud, "baud", "flashing baud rate (default 921600, measured reliable on this board; 2000000 is not)") orelse .b921600; @@ -34,8 +62,8 @@ pub fn build(b: *std.Build) void { const max_rev = b.option(u16, "max-rev", "maximum silicon revision (default 199)") orelse 199; const descriptor = b.option(DescriptorKind, "descriptor", "app descriptor: minimal (184 B) or full (256 B)") orelse .minimal; // `-Dpardes` swaps in the editor as the application. It is a distinct option rather than just - // `-Dapp=src/pardes/app.zig` because it also resolves the lazy `pardes` dependency and raises - // the default stack: the core recurses through layout and 8 KiB is not enough for it. + // `-Dapp=../02-pardes-code/src/esp32p4/app.zig` because it also resolves the lazy `pardes` dependency + // and raises the default stack: the core recurses through layout and 8 KiB is not enough for it. const pardes_app = b.option(bool, "pardes", "build the pardes editor as the application (needs ../02-pardes-code)") orelse false; const stack_size = b.option(u32, "stack", "stack size in bytes (default 8192, or 32768 under -Dpardes)") orelse @as(u32, if (pardes_app) 32768 else 8192); @@ -44,16 +72,7 @@ pub fn build(b: *std.Build) void { // linked into a 500-byte image. const optimize = b.option(std.builtin.OptimizeMode, "optimize", "optimize mode (default ReleaseSmall)") orelse .ReleaseSmall; - const target = b.resolveTargetQuery(.{ - .cpu_arch = .riscv32, - .os_tag = .freestanding, - .abi = .none, - // rv32imafc with the CSR/fence extensions the ESP32-P4 implements. Espressif's own GCC - // adds the vendor extensions xesploop and xespv2p1 on top; upstream LLVM has neither, and - // ordinary code never emits them, so this matches the base ISA exactly. - .cpu_model = .{ .explicit = &std.Target.riscv.cpu.generic_rv32 }, - .cpu_features_add = featureSet(&.{ .m, .a, .f, .c, .zicsr, .zifencei }), - }); + const target = chipTarget(b); // ---------------------------------------------------------------- the chip's registers // Every peripheral register of the P4, taken from ESP-IDF's own `*_reg.h` headers by @@ -65,13 +84,18 @@ pub fn build(b: *std.Build) void { // `*_struct.h` is deliberately not used: translate-c demotes every one of those register // structs to `opaque {}` ("has bitfield"), so the C bitfields buy nothing. src/mmio.zig builds // the typed layer on top of the flat constants instead. - const registers = idfRegisters(b, target, optimize); - const regs_mod = registers.mod; + // + // The two knobs are declared here, where the module used to be built, so `zig build --help` + // still lists them in this position; `firmware` below does the building, because a dependent + // needs the same module set built for a target it chooses. + const idf_opt = b.option([]const u8, "idf", "ESP-IDF checkout, for the register headers (default $IDF_PATH or ~/esp/esp-idf)"); + const idf_hw_ver = b.option(u8, "idf-hw-ver", "register header set: 1 for pre-v3 silicon (default), 3 for v3+") orelse 1; + // ---------------------------------------------------------------- generated linker script // The layout is a build input, not a checked-in file: change -Dstack or the descriptor size // and the script follows. Both flash-mapped sections sit in one 64 KiB MMU window, which is - // what keeps the image ~1 KB instead of ~66 KB (see tools/image.zig). - const ld = b.addWriteFiles(); + // what keeps the image ~1 KB instead of ~66 KB (see tools/image.zig). `firmware` writes it. + // // The oracle links ESP-IDF's own LL functions in beside ours as the differential reference. // Off by default: it is a test rig, it needs an IDF checkout with the C headers, and it has no // business in a shipping image. @@ -93,20 +117,12 @@ pub fn build(b: *std.Build) void { // A file is the better route: the passphrase never appears in a command line, so it stays out of // the shell history and out of the process table where `ps` can see it. const psk_file = b.option([]const u8, "psk-file", "read the passphrase from this file instead of -Dpsk"); - const ld_script = ld.add("app.ld", linkerScript( - b, - stack_size, - if (oracle) readPeripheralsLd(b, registers.idf_path) else null, - )); // ---------------------------------------------------------------- the application - const options = b.addOptions(); - options.addOption(u8, "led_pin", led_pin); - options.addOption(u32, "stack_size", stack_size); - // On-board attribution: time `pardes_p4_input` and `pardes_p4_render` separately and print the + // On-board attribution: time `pardes_esp32p4_input` and `pardes_esp32p4_render` separately and print the // cycle counts. Off by default because it puts a line on the wire per frame, which is the very // resource being measured - it answers "where did the 34 ms go", not "how fast is it". - options.addOption(bool, "prof", b.option(bool, "prof", "print per-phase cycle counts (pardes)") orelse false); + const prof = b.option(bool, "prof", "print per-phase cycle counts (pardes)") orelse false; // The CPU clock, in MHz. The bootloader leaves 90; the CPLL is already at 360, so 180 and 360 // are a divider change away and nothing else (see hal/clkrst.zig:setCpuFreq). Opt-in rather // than default because it is the one setting here that changes how every other timing in the @@ -114,63 +130,43 @@ pub fn build(b: *std.Build) void { const cpu_mhz = b.option(u16, "cpu-mhz", "HP CPU clock: 90 (bootloader default), 180 or 360") orelse 90; if (cpu_mhz != 90 and cpu_mhz != 180 and cpu_mhz != 360) std.debug.panic("-Dcpu-mhz must be 90, 180 or 360; the P4's CPLL divides 360 by 4, 2 or 1", .{}); - options.addOption(u16, "cpu_mhz", cpu_mhz); - options.addOption([]const u8, "wifi_ssid", wifi_ssid); - options.addOption([]const u8, "wifi_psk", if (psk_file) |path| blk: { - const raw = std.Io.Dir.cwd().readFileAlloc(b.graph.io, path, b.allocator, .limited(256)) catch - @panic("cannot read the file named by -Dpsk-file"); - break :blk std.mem.trim(u8, raw, " \t\r\n"); - } else wifi_psk_opt); - options.addOption(bool, "full_descriptor", descriptor == .full); - options.addOption(u16, "min_rev_full", min_rev); - options.addOption(u16, "max_rev_full", max_rev); - const config_mod = options.createModule(); - // The board-support modules are real modules, so an app can live anywhere and still - // `@import("soc")`. src/ holds one copy of each; examples/ holds none. - const soc_mod = b.createModule(.{ - .root_source_file = b.path("src/soc.zig"), + // The board-support modules, the descriptor object and the linker script, in one call - the + // same call a dependent makes. + const fw = firmware(b, .{ .target = target, .optimize = optimize, - }); - // The whole chip's registers, and the typed layer over them. `hal` is what applications and - // drivers use; `regs` is the raw translate-c output, exposed so a driver can reach a register - // the HAL does not model yet without waiting for one to be written. - const mmio_mod = b.createModule(.{ - .root_source_file = b.path("src/mmio.zig"), - .target = target, - .optimize = optimize, - .imports = &.{.{ .name = "regs", .module = regs_mod }}, - }); - const hal_mod = b.createModule(.{ - .root_source_file = b.path("src/hal.zig"), - .target = target, - .optimize = optimize, - .imports = &.{ - .{ .name = "regs", .module = regs_mod }, - .{ .name = "mmio", .module = mmio_mod }, - }, - }); - soc_mod.addImport("hal", hal_mod); - // The app descriptor is its own translation unit, linked in unconditionally. An application - // that merely `@import`s it would not do: under ReleaseSmall the import is analysed lazily, - // nothing forces the constant to be emitted, `.flash.rodata` disappears, and the image ends up - // with a single mapped segment at the wrong offset. As a separate object with an exported - // symbol it always exists, and no application has to remember anything. - const appdesc_obj = b.addObject(.{ - .name = "appdesc", - .root_module = b.createModule(.{ - .root_source_file = b.path("src/appdesc.zig"), - .target = target, - .optimize = optimize, - .imports = &.{.{ .name = "config", .module = config_mod }}, - }), + .idf = idf_opt, + .idf_hw_ver = idf_hw_ver, + .led_pin = led_pin, + .stack_size = stack_size, + .prof = prof, + .cpu_mhz = cpu_mhz, + .wifi_ssid = wifi_ssid, + .wifi_psk = if (psk_file) |path| blk: { + const raw = std.Io.Dir.cwd().readFileAlloc(b.graph.io, path, b.allocator, .limited(256)) catch + @panic("cannot read the file named by -Dpsk-file"); + break :blk std.mem.trim(u8, raw, " \t\r\n"); + } else wifi_psk_opt, + .full_descriptor = descriptor == .full, + .min_rev_full = min_rev, + .max_rev_full = max_rev, + // ESP-IDF's 111 peripheral instance addresses, spliced into the script as text, and only + // when the oracle is what needs them. See `linkerScript` for why it is text and not an + // INCLUDE of a path. + .peripherals_ld = if (oracle) readPeripheralsLd(b, resolveIdf(b, idf_opt)) else null, }); // The app root still comes from `-Dapp`, so pointing that at a different shell over the same - // module stays possible. - const app_source = b.option([]const u8, "app", "root source file (default src/main.zig, or src/pardes/app.zig under -Dpardes)") orelse - if (pardes_app) "src/pardes/app.zig" else "src/main.zig"; + // module stays possible. Under `-Dpardes` that root now lives in the EDITOR's checkout, reached + // the same sibling-relative way `-Dpardes-obj` below reaches its object. It belongs there: every + // line of it is a statement about that one program - the heap span that decides the grid, the + // input chunk sized against what one keystroke costs, the loop's read-tick-render shape - so the + // repository that owns the program owns the file, and this one reads it. Overridable exactly as + // before, and the absolute/relative branch just below already resolves a path that leaves this + // build root, which is what makes the `../` default work with no further plumbing. + const app_source = b.option([]const u8, "app", "root source file (default src/main.zig, or ../02-pardes-code/src/esp32p4/app.zig under -Dpardes)") orelse + if (pardes_app) "../02-pardes-code/src/esp32p4/app.zig" else "src/main.zig"; const app = b.addExecutable(.{ .name = "app", .root_module = b.createModule(.{ @@ -186,11 +182,11 @@ pub fn build(b: *std.Build) void { .omit_frame_pointer = true, .error_tracing = false, .imports = &.{ - .{ .name = "config", .module = config_mod }, - .{ .name = "soc", .module = soc_mod }, - .{ .name = "hal", .module = hal_mod }, - .{ .name = "mmio", .module = mmio_mod }, - .{ .name = "regs", .module = regs_mod }, + .{ .name = "config", .module = fw.config }, + .{ .name = "soc", .module = fw.soc }, + .{ .name = "hal", .module = fw.hal }, + .{ .name = "mmio", .module = fw.mmio }, + .{ .name = "regs", .module = fw.regs }, // The wire protocol `examples/uartperf.zig` answers, imported rather than copied so // the firmware and the host tool cannot disagree about a frame. It is deliberately // free of any OS dependency for exactly this reason: one file, two targets. @@ -199,15 +195,17 @@ pub fn build(b: *std.Build) void { .target = target, .optimize = optimize, }) }, + // `std.Io` for this chip, and the general-purpose allocator. Imported + // unconditionally: an application that never names one costs nothing, because an + // unreferenced module emits no code. + .{ .name = "io", .module = fw.io }, + .{ .name = "heap", .module = fw.heap }, }, }), }); - // The census is a gate, not a side effect: nothing may compile against the register module - // without it having been counted. - app.step.dependOn(registers.census); if (oracle) { // IDF's LL compiled into this very image, as the reference half of the differential. - idfReference(b, app.root_module, registers.idf_path, registers.hw_ver); + idfReference(b, app.root_module, fw.idf_path, fw.hw_ver); // The suites: one module listing every peripheral registered with the harness, so the // harness itself does not grow as peripherals are added. const oracle_mod = b.createModule(.{ @@ -215,65 +213,50 @@ pub fn build(b: *std.Build) void { .target = target, .optimize = optimize, .imports = &.{ - .{ .name = "hal", .module = hal_mod }, - .{ .name = "regs", .module = regs_mod }, - .{ .name = "mmio", .module = mmio_mod }, + .{ .name = "hal", .module = fw.hal }, + .{ .name = "regs", .module = fw.regs }, + .{ .name = "mmio", .module = fw.mmio }, }, }); app.root_module.addImport("oracle", oracle_mod); } - // `std.Io` implemented for this chip: a cooperative scheduler, timers off the systimer, and - // futexes. Its own module rather than a file inside `net`, because Zig confines a module's - // imports to its root directory - src/net/ cannot reach ../io/ - and because it is useful - // without the radio: any application wanting tasks and timeouts can import it alone. - const io_mod = b.createModule(.{ - .root_source_file = b.path("src/io/p4.zig"), - .target = target, - .optimize = optimize, - .single_threaded = true, - .imports = &.{ - .{ .name = "soc", .module = soc_mod }, - .{ .name = "hal", .module = hal_mod }, - .{ .name = "mmio", .module = mmio_mod }, - .{ .name = "regs", .module = regs_mod }, - }, - }); - app.root_module.addImport("io", io_mod); - - // The general-purpose allocator, its own module for exactly the reason given above for `io`: a - // module's imports cannot escape its root directory, so neither src/pardes/ nor examples/ can - // reach src/net/heap.zig as a file. Pointed at the existing file rather than copied - `Heap` is - // a coalescing free-list over one caller-supplied span and has nothing to do with the radio; it - // lives under src/net/ only because ESP-Hosted needed it first. The file has zero `export`s, so - // compiling it into two modules cannot collide. - // - // Added unconditionally, like `io`: an application that never imports it costs nothing, because - // an unreferenced module emits no code. - const heap_mod = b.createModule(.{ - .root_source_file = b.path("src/net/heap.zig"), - .target = target, - .optimize = optimize, - .single_threaded = true, - }); - app.root_module.addImport("heap", heap_mod); - - // The input-rescue policy as a module, so `examples/selftest.zig` can run its checks ON THE DIE - // and not only on the host. Same file the firmware's UART uses. Added unconditionally, like - // `heap` above: an application that never imports it costs nothing, because an unreferenced - // module emits no code. - app.root_module.addImport("input_rescue", b.createModule(.{ - .root_source_file = b.path("src/pardes/input_rescue.zig"), - .target = target, - .optimize = optimize, - .single_threaded = true, - })); + + // The input-rescue policy, `src/esp32p4/input_rescue.zig` in the editor's checkout, is + // deliberately NOT registered on this application root, though it used to be. Nothing that + // `-Dapp` can name imports it as a module: the editor's application root reads the policy + // through its own `uart.zig`, as a sibling FILE beside it, and the GPIO 9P image does not read + // it at all. Zig hashes every registered module's root source on every compile, so registering + // it made EVERY application here fail to build wherever the editor was not beside this checkout + // - `zig build`, every `examples/` root, and a fresh clone of this repository, with + // `failed to check cache: ../02-pardes-code/src/esp32p4/input_rescue.zig file_hash FileNotFound`. + // `zig build selftest` is the one root that imports it by module name, and wires it itself. + + // Pardes's GPIO filesystem uses the shared freestanding 9P protocol, which lives in the + // published cloud9 package pinned in build.zig.zon. The module is built HERE, over that + // package's root source, rather than taken from its own `addModule`: `single_threaded` is a + // property of the module, no consumer can re-flag a module the dependency created, and this + // target is a chip with no threads to synchronise. The pin makes the source a fetched package; + // it changes nothing about how this module compiles. + if (std.mem.endsWith(u8, app_source, "esp32p4_9p.zig")) { + app.root_module.addImport("cloud9", b.createModule(.{ + .root_source_file = b.dependency("cloud9", .{ + .target = target, + .optimize = optimize, + }).path("src/root.zig"), + .target = target, + .optimize = optimize, + .single_threaded = true, + })); + } if (pardes_app) { // The editor arrives as a linked OBJECT, not as a package dependency, and that is a // measurement rather than a preference. // // The obvious design was `build.zig.zon` with a path dependency on ../02-pardes-code, and - // `dep.module("pardes_p4")`. It was written, and it broke EVERY build in this repo - + // `dep.module("pardes_p4")` (the platform tag was spelled `p4` then; it is `esp32p4` now, + // and no module of either name exists, because this is the design that was abandoned). It + // was written, and it broke EVERY build in this repo - // `zig build`, every example, the oracle - because merely DECLARING it nests pardes's // ~30-package graph under this one. Two failures, both from just the declaration: // @@ -288,10 +271,10 @@ pub fn build(b: *std.Build) void { // Neither is fixable from this side, and both would come back the next time the editor // gained a dependency. So the seam is a file instead: pardes's own build emits one // freestanding object exporting a small C ABI, and this links it. The consequences are all - // improvements - this repo keeps having no manifest and no dependencies, the editor's + // improvements - this repo's graph gains no editor packages, the editor's // renderer stays next to the vaxis it needs, and the boundary is bytes in / bytes out. - const obj = b.option([]const u8, "pardes-obj", "path to pardes's p4 object (default ../02-pardes-code/zig-out/pardes-p4.o)") orelse - "../02-pardes-code/zig-out/pardes-p4.o"; + const obj = b.option([]const u8, "pardes-obj", "path to pardes's p4 object (default ../02-pardes-code/zig-out/pardes-esp32p4.o)") orelse + "../02-pardes-code/zig-out/pardes-esp32p4.o"; // THE GRID, set from here, because the object is where it is baked and the object is built // by the other repository. Without this, changing the geometry is two commands in two @@ -308,10 +291,10 @@ pub fn build(b: *std.Build) void { const theme_anim = b.option(bool, "theme-animation", "fade chrome colors across a theme change; rebuilds pardes's object (default off on this transport)"); if ((cols != null or rows != null or theme_anim != null) and b.user_input_options.get("pardes-obj") == null) { const editor_dir = std.fs.path.dirname(std.fs.path.dirname(obj) orelse ".") orelse ".."; - const build_editor = b.addSystemCommand(&.{ b.graph.zig_exe, "build", "-Dplatform=p4" }); + const build_editor = b.addSystemCommand(&.{ b.graph.zig_exe, "build", "-Dplatform=esp32p4" }); build_editor.setCwd(.{ .cwd_relative = editor_dir }); - if (cols) |c| build_editor.addArg(b.fmt("-Dp4-cols={d}", .{c})); - if (rows) |v| build_editor.addArg(b.fmt("-Dp4-rows={d}", .{v})); + if (cols) |c| build_editor.addArg(b.fmt("-Desp32p4-cols={d}", .{c})); + if (rows) |v| build_editor.addArg(b.fmt("-Desp32p4-rows={d}", .{v})); if (theme_anim) |a| build_editor.addArg(b.fmt("-Dtheme-animation={}", .{a})); // Its output is a file this build then links, and the linker has no idea it is generated, // so the ordering has to be said out loud. @@ -344,28 +327,25 @@ pub fn build(b: *std.Build) void { .optimize = optimize, .single_threaded = true, .imports = &.{ - .{ .name = "config", .module = config_mod }, - .{ .name = "soc", .module = soc_mod }, - .{ .name = "hal", .module = hal_mod }, - .{ .name = "mmio", .module = mmio_mod }, - .{ .name = "regs", .module = regs_mod }, - .{ .name = "io", .module = io_mod }, + .{ .name = "config", .module = fw.config }, + .{ .name = "soc", .module = fw.soc }, + .{ .name = "hal", .module = fw.hal }, + .{ .name = "mmio", .module = fw.mmio }, + .{ .name = "regs", .module = fw.regs }, + .{ .name = "io", .module = fw.io }, }, }); app.root_module.addImport("net", net_mod); // The C half, compiled against this project's Kconfig surface. It attaches to the // executable's own module rather than net's, because the C is linked, not imported. - hostedC(b, app.root_module, registers.idf_path); + hostedC(b, app.root_module, fw.idf_path); } - app.setLinkerScript(ld_script); - app.entry = .{ .symbol_name = "_start" }; - // The app descriptor must survive --gc-sections even though no code reads it: the bootloader - // does, at image offset 0x20. Asking the linker for the symbol is what keeps the module alive, - // regardless of whether the application source happens to mention it. - app.root_module.addObject(appdesc_obj); + // The linker script, ENTRY(_start), the descriptor object and the register census: the one + // arrangement every firmware here - and every dependent's - has to get right, in one call. + fw.attach(app); + // --gc-sections is the caller's, not `attach`'s: the selftest image below is linked without it, + // and switching that on would change bytes this file has no business changing. app.link_gc_sections = true; - app.link_function_sections = true; - app.link_data_sections = true; // One install step for the ELF, reachable two ways: `zig build elf` on its own (handy when // debugging the image builder) and `-Delf` to get it alongside the image. @@ -414,77 +394,47 @@ pub fn build(b: *std.Build) void { "interactive console baud (default 115200, the rate the bootloader leaves UART0 at)", ) orelse .b115200; - // A real host binary, and not an in-process step like every other tool here, for two reasons. - // It runs with no build runner at all when the board is already flashed; and as a child process - // under `Step.Run` with inherited stdio it gets std's stderr lock held for its whole lifetime - // (std/Build/Step/Run.zig:1588-1592), which is what stops `std.Progress` repainting the step - // tree over an interactive session. The in-process step this replaced never took that lock, and - // shredded the editor's screen with fragments of `[11/13] steps`. - const con_exe = b.addExecutable(.{ - .name = "p4-console", - .root_module = b.createModule(.{ - .root_source_file = b.path("tools/console_main.zig"), - .target = b.graph.host, - .optimize = .ReleaseSafe, - }), - }); - // Installed by the console steps, and deliberately NOT by `install`: the default build still - // lands exactly one file in zig-out, the flashable image. Anyone who has attached once has - // zig-out/bin/p4-console afterwards, which is the copy to run when the board is already - // flashed and no build is wanted. - const con_install = b.addInstallArtifact(con_exe, .{}); + // The two host binaries, and why they are binaries rather than in-process steps, are at + // `hostTools`. + const tools = hostTools(b); const con_args: []const []const u8 = &.{ "--port", port_path, "--baud", b.fmt("{d}", .{console_baud.rate()}) }; - const con = b.addRunArtifact(con_exe); + const con = b.addRunArtifact(tools.console); con.addArgs(con_args); // Inherited stdio is the whole point: the board's bytes and the user's keystrokes pass through // untouched, and the terminal the child sees is the real one, so its ioctls answer. con.stdio = .inherit; - con.step.dependOn(&con_install.step); + con.step.dependOn(&tools.console_install.step); b.step("console", "attach a terminal to the application already on the board").dependOn(&con.step); // Ordered, for the same reason `run` is: an unordered `flash console` lets the console reset // the board out from under the writer. - const run_con = b.addRunArtifact(con_exe); + const run_con = b.addRunArtifact(tools.console); run_con.addArgs(con_args); run_con.stdio = .inherit; - run_con.step.dependOn(&con_install.step); + run_con.step.dependOn(&tools.console_install.step); run_con.step.dependOn(&flash.step); b.step("interact", "flash the image, then attach a terminal").dependOn(&run_con.step); - // The measuring instrument. Its own binary for the same reason the console is: it drives the - // port for tens of seconds and must not have the build runner repainting a progress tree into - // the middle of a timed transfer. It shares `tools/perfproto.zig` with the firmware responder, - // so a frame the host writes and a frame the board parses cannot drift apart. - const bench_proto = b.createModule(.{ - .root_source_file = b.path("tools/perfproto.zig"), - .target = b.graph.host, - .optimize = .ReleaseSafe, - }); - const bench_exe = b.addExecutable(.{ - .name = "p4-bench", - .root_module = b.createModule(.{ - .root_source_file = b.path("tools/bench_main.zig"), - .target = b.graph.host, - .optimize = .ReleaseSafe, - .imports = &.{.{ .name = "perfproto", .module = bench_proto }}, - }), - }); - const bench_install = b.addInstallArtifact(bench_exe, .{}); - const bench = b.addRunArtifact(bench_exe); + const bench = b.addRunArtifact(tools.bench); bench.addArgs(&.{ "--port", port_path }); bench.stdio = .inherit; - bench.step.dependOn(&bench_install.step); + bench.step.dependOn(&tools.bench_install.step); // `zig build selftest` - its OWN application, image and flash chain, so it is one command with no // flags to remember. Sharing the `-Dapp` pipeline would have meant `zig build selftest - // -Dapp=examples/selftest.zig`, which is the kind of incantation that turns a suite into - // something nobody runs. The modules are the ones its checks need and no more. + // -Dapp=../02-pardes-code/src/esp32p4/selftest.zig`, which is the kind of incantation that turns a + // suite into something nobody runs. The modules are the ones its checks need and no more. + // + // The suite lives in the editor's checkout, with the code it makes claims about: byte-at-a-time + // `std.mem.eql` on this target, the lone-ESC decode on a 115200 line, the transmit-FIFO + // backpressure, the heap span the grid is cut from. Read from here across the same + // sibling-relative seam as `-Dapp` and `-Dpardes-obj`, so this step is unchanged in behaviour. const selftest_exe = b.addExecutable(.{ .name = "selftest", .root_module = b.createModule(.{ - .root_source_file = b.path("examples/selftest.zig"), + .root_source_file = b.path("../02-pardes-code/src/esp32p4/selftest.zig"), .target = target, .optimize = optimize, .strip = true, @@ -493,14 +443,14 @@ pub fn build(b: *std.Build) void { .omit_frame_pointer = true, .error_tracing = false, .imports = &.{ - .{ .name = "config", .module = config_mod }, - .{ .name = "soc", .module = soc_mod }, - .{ .name = "hal", .module = hal_mod }, - .{ .name = "mmio", .module = mmio_mod }, - .{ .name = "regs", .module = regs_mod }, - .{ .name = "heap", .module = heap_mod }, + .{ .name = "config", .module = fw.config }, + .{ .name = "soc", .module = fw.soc }, + .{ .name = "hal", .module = fw.hal }, + .{ .name = "mmio", .module = fw.mmio }, + .{ .name = "regs", .module = fw.regs }, + .{ .name = "heap", .module = fw.heap }, .{ .name = "input_rescue", .module = b.createModule(.{ - .root_source_file = b.path("src/pardes/input_rescue.zig"), + .root_source_file = b.path("../02-pardes-code/src/esp32p4/input_rescue.zig"), .target = target, .optimize = optimize, .single_threaded = true, @@ -508,15 +458,7 @@ pub fn build(b: *std.Build) void { }, }), }); - selftest_exe.setLinkerScript(app.linker_script.?); - selftest_exe.link_function_sections = true; - selftest_exe.link_data_sections = true; - selftest_exe.entry = .{ .symbol_name = "_start" }; - // The app descriptor, without which the image has nothing at offset 0x20 for the bootloader to - // read and the board boots into silence - which is exactly how the first run of this step failed, - // and it looks identical to a suite that hung. - selftest_exe.root_module.addObject(appdesc_obj); - selftest_exe.step.dependOn(registers.census); + fw.attach(selftest_exe); const selftest_img = ImageStep.create(b, selftest_exe, img.opts); const selftest_flash = FlashStep.create(b, selftest_img, .{ .port = flash.port, @@ -593,20 +535,6 @@ pub fn build(b: *std.Build) void { }); test_step.dependOn(&b.addRunArtifact(console_tests).step); - // The input-rescue policy: drain the receiver while spinning on a full transmitter. This is a - // decision rather than a register access, and it was a measured bug - a 200-byte burst typed - // into a long frame lost 88 bytes on the die - so it is worth a test that fails without the - // fix. `pump` takes its port as `anytype` precisely so the same code can run against a fake - // with a two-byte FIFO here and against UART0 on the board. - const rescue_tests = b.addTest(.{ - .root_module = b.createModule(.{ - .root_source_file = b.path("src/pardes/input_rescue.zig"), - .target = b.graph.host, - .optimize = .Debug, - }), - }); - test_step.dependOn(&b.addRunArtifact(rescue_tests).step); - // The measurement protocol. These are the tests that keep a throughput number honest: that a // frame round-trips, that a short read is "incomplete" rather than "invalid", that a lost byte // mid-stream changes the CRC, and that the pattern generator does not repeat on a 256-byte @@ -634,14 +562,14 @@ pub fn build(b: *std.Build) void { .root_source_file = b.path("src/mmio.zig"), .target = b.graph.host, .optimize = .Debug, - .imports = &.{.{ .name = "regs", .module = regs_mod }}, + .imports = &.{.{ .name = "regs", .module = fw.regs }}, }); const host_hal = b.createModule(.{ .root_source_file = b.path("src/hal.zig"), .target = b.graph.host, .optimize = .Debug, .imports = &.{ - .{ .name = "regs", .module = regs_mod }, + .{ .name = "regs", .module = fw.regs }, .{ .name = "mmio", .module = host_mmio }, }, }); @@ -671,7 +599,7 @@ pub fn build(b: *std.Build) void { .{ .name = "soc", .module = host_soc }, .{ .name = "hal", .module = host_hal }, .{ .name = "mmio", .module = host_mmio }, - .{ .name = "regs", .module = regs_mod }, + .{ .name = "regs", .module = fw.regs }, }, }), }); @@ -679,6 +607,283 @@ pub fn build(b: *std.Build) void { } } +// ---------------------------------------------------------------------------- public build API +// +// What another package drives this toolchain through, and the only thing `build()` above is: a +// caller of these. Every one of them takes THIS package's `*std.Build` - a dependent passes +// `b.dependency("zig_p4", .{}).builder` - because they resolve source paths, and the image step's +// cache inputs, relative to this build root. There is no second implementation anywhere: what a +// dependent compiles is what `zig build` here compiles. + +/// The chip, as a target. +/// +/// Deliberately not a `standardTargetOption`: there is one processor here, and offering to build +/// this firmware for anything else would be offering a build that cannot run. +pub fn chipTarget(b: *std.Build) std.Build.ResolvedTarget { + return b.resolveTargetQuery(.{ + .cpu_arch = .riscv32, + .os_tag = .freestanding, + .abi = .none, + // rv32imafc with the CSR/fence extensions the ESP32-P4 implements. Espressif's own GCC + // adds the vendor extensions xesploop and xespv2p1 on top; upstream LLVM has neither, and + // ordinary code never emits them, so this matches the base ISA exactly. + .cpu_model = .{ .explicit = &std.Target.riscv.cpu.generic_rv32 }, + .cpu_features_add = featureSet(&.{ .m, .a, .f, .c, .zicsr, .zifencei }), + }); +} + +/// What `firmware` has to be told. Only the target and the optimize mode have no default, because a +/// caller has already had to decide both by the time it creates its own root module - and passing +/// the same pair to both is what keeps the application and the board support one link. +pub const FirmwareOptions = struct { + target: std.Build.ResolvedTarget, + optimize: std.builtin.OptimizeMode, + /// The ESP-IDF checkout the register headers are read from. `null` resolves $IDF_PATH, then + /// ~/esp/esp-idf, which is what `-Didf` does when it is not given. + idf: ?[]const u8 = null, + /// Which register header set: 1 for pre-v3 silicon, 3 for v3+. Load-bearing rather than + /// cosmetic - 61 macros keep their name and change their value between the two - so hal.zig + /// comptime-asserts the value this bakes in. + idf_hw_ver: u8 = 1, + led_pin: u8 = 20, + /// Bytes of `.stack` in the generated script. 8192 is enough for everything in examples/; the + /// editor recurses through layout and needs 32768. + stack_size: u32 = 8192, + prof: bool = false, + cpu_mhz: u16 = 90, + wifi_ssid: []const u8 = "", + wifi_psk: []const u8 = "", + full_descriptor: bool = false, + min_rev_full: u16 = 100, + max_rev_full: u16 = 199, + /// ESP-IDF's peripherals.ld as TEXT, spliced into the linker script - only the differential + /// oracle needs it, and `linkerScript` records why it is text and not an INCLUDE of a path. + peripherals_ld: ?[]const u8 = null, +}; + +/// Everything a firmware executable links against: the board-support modules, the app descriptor +/// object, the generated linker script, and the register census that gates all of it. +pub const Firmware = struct { + /// `-Dled`, `-Dstack`, `-Dprof`, `-Dcpu-mhz`, the Wi-Fi credentials and the descriptor's + /// revision window, as `@import("config")`. + config: *std.Build.Module, + soc: *std.Build.Module, + /// What applications and drivers use. `regs` beside it is the raw translate-c output, exposed + /// so a driver can reach a register the HAL does not model yet without waiting for one to be + /// written. + hal: *std.Build.Module, + mmio: *std.Build.Module, + regs: *std.Build.Module, + /// `std.Io` implemented for this chip: a cooperative scheduler, timers off the systimer, and + /// futexes. Its own module rather than a file inside `net`, because Zig confines a module's + /// imports to its root directory - src/net/ cannot reach ../io/ - and because it is useful + /// without the radio: any application wanting tasks and timeouts can import it alone. + io: *std.Build.Module, + /// The general-purpose allocator, its own module for the same reason as `io`: a module's + /// imports cannot escape its root directory, so no application outside src/net/ can reach + /// src/net/heap.zig as a file. `Heap` is a coalescing free-list over one caller-supplied span + /// and has nothing to do with the radio; it lives under src/net/ only because ESP-Hosted + /// needed it first. The file has zero `export`s, so compiling it into two modules cannot + /// collide. + heap: *std.Build.Module, + /// The app descriptor, as an OBJECT rather than something to import. An application that + /// merely `@import`ed it would not do: under ReleaseSmall the import is analysed lazily, + /// nothing forces the constant to be emitted, `.flash.rodata` disappears, and the image ends + /// up with a single mapped segment at the wrong offset. `attach` links it. + appdesc: *std.Build.Step.Compile, + linker_script: std.Build.LazyPath, + /// The poison census. A gate, not a side effect: nothing may compile against the register + /// module without it having been counted. `attach` wires it. + census: *std.Build.Step, + /// Where the headers came from, for a caller that needs the same checkout for something else - + /// `hostedC` and `idfReference` here both do. + idf_path: []const u8, + hw_ver: u8, + + /// Put a firmware executable on this chip: the script that places it, the entry symbol the + /// bootloader jumps to, the descriptor the bootloader reads, and the census. + /// + /// One call because every one of the four is a way to boot into silence when forgotten, and + /// three of them were, in this order: + /// + /// * no descriptor object, so nothing sits at image offset 0x20 - which is how the first run + /// of `zig build selftest` failed, and it looks exactly like a suite that hung; + /// * the descriptor linked but garbage-collected, because no code reads it and only the + /// bootloader does. Linking it as an object keeps it regardless of whether the application + /// source happens to mention it; + /// * no `ENTRY(_start)`, which LLD resolves to an address that is not the reset vector. + /// + /// `--gc-sections` is deliberately NOT set here: `zig build selftest` links without it, and + /// which sections an image keeps is a decision that belongs to the image, not to this. + pub fn attach(self: Firmware, exe: *std.Build.Step.Compile) void { + exe.setLinkerScript(self.linker_script); + exe.entry = .{ .symbol_name = "_start" }; + exe.root_module.addObject(self.appdesc); + exe.step.dependOn(self.census); + exe.link_function_sections = true; + exe.link_data_sections = true; + } +}; + +/// The board support, built for the caller's target and optimize mode. +/// +/// The modules are real modules, so an application can live anywhere - another directory, another +/// package - and still `@import("soc")`. src/ holds one copy of each; examples/ holds none. +/// +/// Calling this twice in one build graph is safe and nearly free: the second call creates a second +/// set of module objects over the same files, and the translate-c run behind `regs` is keyed on its +/// input, so the register work happens once. +pub fn firmware(b: *std.Build, opts: FirmwareOptions) Firmware { + const target = opts.target; + const optimize = opts.optimize; + + const registers = idfRegisters(b, target, optimize, opts.idf, opts.idf_hw_ver); + + const options = b.addOptions(); + options.addOption(u8, "led_pin", opts.led_pin); + options.addOption(u32, "stack_size", opts.stack_size); + options.addOption(bool, "prof", opts.prof); + options.addOption(u16, "cpu_mhz", opts.cpu_mhz); + options.addOption([]const u8, "wifi_ssid", opts.wifi_ssid); + options.addOption([]const u8, "wifi_psk", opts.wifi_psk); + options.addOption(bool, "full_descriptor", opts.full_descriptor); + options.addOption(u16, "min_rev_full", opts.min_rev_full); + options.addOption(u16, "max_rev_full", opts.max_rev_full); + const config_mod = options.createModule(); + + const soc_mod = b.createModule(.{ + .root_source_file = b.path("src/soc.zig"), + .target = target, + .optimize = optimize, + }); + const mmio_mod = b.createModule(.{ + .root_source_file = b.path("src/mmio.zig"), + .target = target, + .optimize = optimize, + .imports = &.{.{ .name = "regs", .module = registers.mod }}, + }); + const hal_mod = b.createModule(.{ + .root_source_file = b.path("src/hal.zig"), + .target = target, + .optimize = optimize, + .imports = &.{ + .{ .name = "regs", .module = registers.mod }, + .{ .name = "mmio", .module = mmio_mod }, + }, + }); + soc_mod.addImport("hal", hal_mod); + + return .{ + .config = config_mod, + .soc = soc_mod, + .hal = hal_mod, + .mmio = mmio_mod, + .regs = registers.mod, + .io = b.createModule(.{ + .root_source_file = b.path("src/io/p4.zig"), + .target = target, + .optimize = optimize, + .single_threaded = true, + .imports = &.{ + .{ .name = "soc", .module = soc_mod }, + .{ .name = "hal", .module = hal_mod }, + .{ .name = "mmio", .module = mmio_mod }, + .{ .name = "regs", .module = registers.mod }, + }, + }), + .heap = b.createModule(.{ + .root_source_file = b.path("src/net/heap.zig"), + .target = target, + .optimize = optimize, + .single_threaded = true, + }), + .appdesc = b.addObject(.{ + .name = "appdesc", + .root_module = b.createModule(.{ + .root_source_file = b.path("src/appdesc.zig"), + .target = target, + .optimize = optimize, + .imports = &.{.{ .name = "config", .module = config_mod }}, + }), + }), + // A WriteFiles directory rather than a checked-in file, so `-Dstack` and the descriptor + // size are build inputs the script follows. + .linker_script = b.addWriteFiles().add("app.ld", linkerScript(b, opts.stack_size, opts.peripherals_ld)), + .census = registers.census, + .idf_path = registers.idf_path, + .hw_ver = registers.hw_ver, + }; +} + +/// The two host-side binaries: the interactive console and the link benchmark. +/// +/// Real host binaries, and not in-process steps like every other tool here, for two reasons. They +/// run with no build runner at all when the board is already flashed; and as a child process under +/// `Step.Run` with inherited stdio they get std's stderr lock held for their whole lifetime +/// (std/Build/Step/Run.zig:1588-1592), which is what stops `std.Progress` repainting the step tree +/// over an interactive session or into the middle of a timed transfer. The in-process step this +/// replaced never took that lock, and shredded the editor's screen with fragments of +/// `[11/13] steps`. +pub const HostTools = struct { + /// `p4-console`: keystrokes in, screen out, against whatever is already on the board. + console: *std.Build.Step.Compile, + /// Wired by the console steps, and deliberately NOT by `install`: the default build still + /// lands exactly one file in zig-out, the flashable image. Anyone who has attached once has + /// zig-out/bin/p4-console afterwards, which is the copy to run when the board is already + /// flashed and no build is wanted. Depend on this from the run step, never install it twice: + /// two install steps for one artifact race to write the same path. + /// Owned by this package's builder, so a dependent depending on it installs into this + /// package's own prefix (measured: `.zig-cache/i//bin/p4-console`). A dependent that + /// wants the binary in its own zig-out calls `b.addInstallArtifact(tools.console, .{})` with + /// its own builder instead, and depends on that. + console_install: *std.Build.Step.InstallArtifact, + /// `p4-bench`: verified throughput each way, and latency. Shares `tools/perfproto.zig` with + /// the firmware responder, so a frame the host writes and a frame the board parses cannot + /// drift apart. + bench: *std.Build.Step.Compile, + bench_install: *std.Build.Step.InstallArtifact, +}; + +pub fn hostTools(b: *std.Build) HostTools { + const con_exe = b.addExecutable(.{ + .name = "p4-console", + .root_module = b.createModule(.{ + .root_source_file = b.path("tools/console_main.zig"), + .target = b.graph.host, + .optimize = .ReleaseSafe, + }), + }); + const bench_exe = b.addExecutable(.{ + .name = "p4-bench", + .root_module = b.createModule(.{ + .root_source_file = b.path("tools/bench_main.zig"), + .target = b.graph.host, + .optimize = .ReleaseSafe, + .imports = &.{.{ .name = "perfproto", .module = b.createModule(.{ + .root_source_file = b.path("tools/perfproto.zig"), + .target = b.graph.host, + .optimize = .ReleaseSafe, + }) }}, + }), + }); + return .{ + .console = con_exe, + .console_install = b.addInstallArtifact(con_exe, .{}), + .bench = bench_exe, + .bench_install = b.addInstallArtifact(bench_exe, .{}), + }; +} + +/// Where ESP-IDF is. A function because two callers must reach the same answer: the register +/// module, and - under `-Doracle` - the peripheral symbols spliced into the linker script. Those +/// two disagreeing would link one header set's register addresses against another's instance +/// addresses, which is a wrong-register bug with no error anywhere. +fn resolveIdf(b: *std.Build, opt: ?[]const u8) []const u8 { + return opt orelse + b.graph.environ_map.get("IDF_PATH") orelse + b.pathJoin(&.{ b.graph.environ_map.get("HOME") orelse "", "esp", "esp-idf" }); +} + /// The ESP32-P4's entire register map as a Zig module, via `zig translate-c` over ESP-IDF's own /// register headers. /// @@ -694,11 +899,10 @@ fn idfRegisters( b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, + idf_opt: ?[]const u8, + hw_ver: u8, ) struct { mod: *std.Build.Module, census: *std.Build.Step, idf_path: []const u8, hw_ver: u8 } { - const idf = b.option([]const u8, "idf", "ESP-IDF checkout, for the register headers (default $IDF_PATH or ~/esp/esp-idf)") orelse - b.graph.environ_map.get("IDF_PATH") orelse - b.pathJoin(&.{ b.graph.environ_map.get("HOME") orelse "", "esp", "esp-idf" }); - const hw_ver = b.option(u8, "idf-hw-ver", "register header set: 1 for pre-v3 silicon (default), 3 for v3+") orelse 1; + const idf = resolveIdf(b, idf_opt); const reg_dir = b.pathJoin(&.{ idf, "components", "soc", "esp32p4", "register", b.fmt("hw_ver{d}", .{hw_ver}), "soc" }); @@ -1467,20 +1671,25 @@ fn linkerScript(b: *std.Build, stack_size: u32, peripherals_ld: ?[]const u8) []c // hash the inputs into a cache manifest, skip the work on a hit, publish the result as a LazyPath. // Nothing is passed between steps through private fields, so `zig build flash` works whether or not // the image step ran in this process. +// +// All `pub`, so a dependent gets these steps rather than a second implementation of them. Their `b` +// is this package's builder, like every other function here: `ImageStep` names tools/image.zig and +// build.zig as cache inputs by root-relative path, so a builder rooted anywhere else would hash the +// wrong files - or none. /// The serial port is one device but `flash` and `monitor` are unordered top-level steps, and the /// build runner executes independent steps concurrently. Serializing them here turns /// `zig build flash monitor` from a race into a sequence. var port_lock: std.Io.Mutex = .init; -const ImageStep = struct { +pub const ImageStep = struct { step: std.Build.Step, elf: std.Build.LazyPath, opts: image.Options, basename: []const u8, generated: std.Build.GeneratedFile, - fn create(b: *std.Build, app: *std.Build.Step.Compile, opts: image.Options) *ImageStep { + pub fn create(b: *std.Build, app: *std.Build.Step.Compile, opts: image.Options) *ImageStep { const self = b.allocator.create(ImageStep) catch @panic("OOM"); self.* = .{ .step = std.Build.Step.init(.{ @@ -1499,7 +1708,7 @@ const ImageStep = struct { return self; } - fn getOutput(self: *ImageStep) std.Build.LazyPath { + pub fn getOutput(self: *ImageStep) std.Build.LazyPath { return .{ .generated = .{ .file = &self.generated } }; } @@ -1615,12 +1824,12 @@ fn describeLayout(w: *std.Io.Writer, l: image.Layout, opts: image.Options) !void /// the moment you actually need the table is when it did not. This one starts from the ELF and /// reports the loader verdict as text instead of as a failed build, so an image the bootloader would /// refuse can still be inspected. -const LayoutStep = struct { +pub const LayoutStep = struct { step: std.Build.Step, elf: std.Build.LazyPath, opts: image.Options, - fn create(b: *std.Build, app: *std.Build.Step.Compile, opts: image.Options) *LayoutStep { + pub fn create(b: *std.Build, app: *std.Build.Step.Compile, opts: image.Options) *LayoutStep { const self = b.allocator.create(LayoutStep) catch @panic("OOM"); self.* = .{ .step = std.Build.Step.init(.{ .id = .custom, .name = "layout", .owner = b, .makeFn = make }), @@ -1686,7 +1895,7 @@ fn failPort(step: *std.Build.Step, port: []const u8, err: anyerror) anyerror { return step.fail("cannot open {s}: AccessDenied\n\n" ++ serial.access_denied_help, .{port}); } -const FlashStep = struct { +pub const FlashStep = struct { step: std.Build.Step, bin: std.Build.LazyPath, opts: image.Options, @@ -1694,14 +1903,14 @@ const FlashStep = struct { baud: serial.Baud, verify: bool, - const Args = struct { + pub const Args = struct { port: []const u8, baud: serial.Baud, verify: bool, opts: image.Options, }; - fn create(b: *std.Build, img: *ImageStep, args: Args) *FlashStep { + pub fn create(b: *std.Build, img: *ImageStep, args: Args) *FlashStep { const self = b.allocator.create(FlashStep) catch @panic("OOM"); self.* = .{ .step = std.Build.Step.init(.{ .id = .custom, .name = "flash", .owner = b, .makeFn = make }), @@ -1778,12 +1987,12 @@ const FlashStep = struct { } }; -const MonitorStep = struct { +pub const MonitorStep = struct { step: std.Build.Step, port: []const u8, seconds: u32, - fn create(b: *std.Build, port: []const u8, seconds: u32) *MonitorStep { + pub fn create(b: *std.Build, port: []const u8, seconds: u32) *MonitorStep { const self = b.allocator.create(MonitorStep) catch @panic("OOM"); self.* = .{ .step = std.Build.Step.init(.{ .id = .custom, .name = "monitor", .owner = b, .makeFn = make }), @@ -1821,11 +2030,11 @@ const MonitorStep = struct { /// Pulse the reset line and leave. One ioctl pair, but it is the difference between "did my app /// hang or did I forget to reset it" during development. -const ResetStep = struct { +pub const ResetStep = struct { step: std.Build.Step, port: []const u8, - fn create(b: *std.Build, port: []const u8) *ResetStep { + pub fn create(b: *std.Build, port: []const u8) *ResetStep { const self = b.allocator.create(ResetStep) catch @panic("OOM"); self.* = .{ .step = std.Build.Step.init(.{ .id = .custom, .name = "reset", .owner = b, .makeFn = make }), @@ -1856,12 +2065,12 @@ const ResetStep = struct { /// Reads until `MARK SELFTEST DONE pass=N fail=M`, echoing as it goes so a failing check is visible /// in place rather than only as a count. Absent marker within the window is itself a failure: it /// means the board never got there, which is worse than a failed check and must not read as a pass. -const SelftestStep = struct { +pub const SelftestStep = struct { step: std.Build.Step, port: []const u8, seconds: u32, - fn create(b: *std.Build, port: []const u8, seconds: u32) *SelftestStep { + pub fn create(b: *std.Build, port: []const u8, seconds: u32) *SelftestStep { const self = b.allocator.create(SelftestStep) catch @panic("OOM"); self.* = .{ .step = std.Build.Step.init(.{ .id = .custom, .name = "selftest", .owner = b, .makeFn = make }), @@ -1923,12 +2132,12 @@ const SelftestStep = struct { } }; -const SizeStep = struct { +pub const SizeStep = struct { step: std.Build.Step, bin: std.Build.LazyPath, opts: image.Options, - fn create(b: *std.Build, img: *ImageStep) *SizeStep { + pub fn create(b: *std.Build, img: *ImageStep) *SizeStep { const self = b.allocator.create(SizeStep) catch @panic("OOM"); self.* = .{ .step = std.Build.Step.init(.{ .id = .custom, .name = "size", .owner = b, .makeFn = make }), diff --git a/build.zig.zon b/build.zig.zon new file mode 100644 index 0000000..ae03fb0 --- /dev/null +++ b/build.zig.zon @@ -0,0 +1,46 @@ +// This repository went without a manifest on purpose for as long as it had no reason to have one, +// and the reason it now has one runs in the opposite direction to the failure recorded in build.zig +// (see the comment under `-Dpardes`). +// +// What broke, and stays broken, is depending on pardes FROM here: declaring the editor as a path +// dependency nested its ~30-package graph under this repo and killed every build in it - the +// comptime backwards-branch quota in std/Build.zig:2091 over the enlarged dependency table, and +// seven cached tree_sitter versions whose build.zig files no longer compile on Zig 0.16. That is +// still true, which is why the editor is NOT declared here: it arrives as a linked object over a C +// ABI, and the seam between the two repositories stays a file. +// +// The reverse direction has none of that cost. This package has exactly one dependency - cloud9, +// pinned below, whose own manifest declares none - so nesting this package under another one adds +// two entries to that one's table, not the thirty whose comptime `mem.eql` walk blew the quota +// above. There is no stale cache entry for either to reach, and both compile on 0.16 by +// construction. A manifest is what makes this addressable as a dependency at all, and build.zig's +// `pub` API is what a dependent drives; `build()` itself early-returns when it is not the root +// package, so declaring this dependency costs a dependent nothing and does not drag an ESP-IDF +// checkout into its builds. +.{ + .name = .zig_p4, + .version = "0.1.0", + // The one dependency, and only the GPIO 9P application uses it: that image is a 9P server over + // base 9P2000, and the protocol implementation is shared with the editor rather than copied. + // Pinned here like every other package in this account, so the image builds from this file + // alone - the sibling `../cloud9` checkout it used to reach across is gone. Push with + // `git@git.sr.ht:~gbrls/cloud9`; zig has no `git+ssh` support, so the manifest carries the + // read-only HTTPS URL. Re-pin with + // `zig fetch --save=cloud9 git+https://git.sr.ht/~gbrls/cloud9#`. + .dependencies = .{ + .cloud9 = .{ + .url = "git+https://git.sr.ht/~gbrls/cloud9#ae310a207534b33b7321dd2b9f423a73b1969159", + .hash = "cloud9-0.1.0-yt86qsv9AwAy7XqxowpkCFum_p_xfl4S74L8KIeVz4j9", + }, + }, + // `pub fn build`'s API is written against 0.16's std.Build: `b.graph.io`, `std.Io.Dir`, + // `addWriteFiles`, and `Compile.root_module`. None of it compiles on 0.15 and this project + // tracks the release rather than master. + .minimum_zig_version = "0.16.0", + // Exactly what a dependent compiles: this file, the build graph, the board-support and driver + // sources under src/, and the host-side toolchain under tools/. Deliberately not examples/ - + // those are applications with their own `_start`, built by `zig build` HERE and never by a + // dependent - nor experiments/ (measurement data) nor README.md. + .paths = .{ "build.zig", "build.zig.zon", "src", "tools" }, + .fingerprint = 0x40c3b14caca7670f, +} diff --git a/examples/selftest.zig b/examples/selftest.zig deleted file mode 100644 index e1bd19a..0000000 --- a/examples/selftest.zig +++ /dev/null @@ -1,321 +0,0 @@ -//! The test suite that runs ON THE DIE. -//! -//! WHY THIS EXISTS. Every serious bug this port has produced was invisible to a host test, and two -//! of them were invisible for months. `std.mem.eql` compares a byte at a time on this target and -//! several times faster on the host, so the firmware's largest read was three times slower than it -//! needed to be and nothing on a laptop could tell. A lone ESC resolves to the Escape key, which is -//! right when a kernel hands over a whole escape sequence and wrong when a 115200 line hands over -//! one byte every 87 microseconds. A full transmit FIFO stopped anything draining the receiver, and -//! the FIFO depth is a hardware number. None of those is a logic error you can reason your way to -//! from a host: they are properties of THIS chip, THIS clock and THIS wire. -//! -//! So the checks below are chosen by one rule: a check belongs here only if the die can answer it -//! and a host cannot. Anything that is pure logic - the ring's wrap-around, the mouse coalescer's -//! ordering - already has a deterministic host test in `zig build test`, which is faster, needs no -//! hardware, and is where such a thing belongs. Duplicating those here would make this suite longer -//! and no stronger. -//! -//! Not a `zig test` binary, deliberately. Zig's test runner wants an OS, and `std.testing.allocator` -//! is a debug allocator over the page allocator, which on freestanding is either a compile error or -//! a lie. A hand-rolled harness is thirty lines and answers to nobody. -//! -//! Run with: zig build selftest -//! or: zig build -Dapp=examples/selftest.zig run - -const std = @import("std"); -const soc = @import("soc"); -const hal = @import("hal"); -const config = @import("config"); -const heapmod = @import("heap"); -const input_rescue = @import("input_rescue"); - -/// Reset entry. Identical in shape to `src/main.zig`'s and for the same reasons: the bootloader hands -/// over with an unspecified stack pointer and the FPU off, so set `mstatus.FS`, establish a stack, -/// clear `.bss`, and jump. -/// -/// Leaving this out is what made the first draft of this file unbuildable, and the failure said -/// nothing useful: `-fentry=_start` found no such symbol, `--gc-sections` then discarded every -/// function as unreachable, and the image builder reported `NotTwoMappedSegments` because -/// `.flash.text` had nothing left in it. `zig build layout` now prints `entry 0x0` for exactly that, -/// which is the same diagnosis in one line. -export fn _start() linksection(".text.entry") callconv(.naked) noreturn { - asm volatile ( - \\ li t0, 1 << 13 - \\ csrs mstatus, t0 - \\ la sp, __stack_top - \\ mv fp, sp - \\ la t0, __bss_start - \\ la t1, __bss_end - \\ bgeu t0, t1, 2f - \\1: - \\ sw zero, 0(t0) - \\ addi t0, t0, 4 - \\ bltu t0, t1, 1b - \\2: - \\ j zig_main - ); -} - -pub const panic = std.debug.FullPanic(struct { - fn call(msg: []const u8, first_trace_addr: ?usize) noreturn { - // `msg` is a slice and carries no terminator - std's own panics are formatted into a buffer - - // so it goes out with a length rather than through a `%s` that would read past the end of it. - soc.rom.print("\r\nMARK SELFTEST_PANIC at 0x%08x: ", .{@as(u32, @truncate(first_trace_addr orelse 0))}); - hal.uart.Uart.init(0).write(msg); - // A panic is a FAILED RUN, and the host is watching for the summary line. Without this the - // run looks like a board that never answered, which is a different diagnosis entirely. - soc.rom.print("\r\nMARK SELFTEST DONE pass=%u fail=%u\r\n", .{ passed, failed + 1 }); - while (true) {} - } -}.call); - -var passed: u32 = 0; -var failed: u32 = 0; - -/// One claim about the silicon. Printed either way: a suite that only speaks up when it fails gives -/// no way to tell "all good" from "never ran", and on a board that difference matters. -fn check(name: [*:0]const u8, ok: bool) void { - if (ok) { - passed += 1; - soc.rom.print("MARK SELFTEST ok %s\r\n", .{name}); - } else { - failed += 1; - soc.rom.print("MARK SELFTEST FAIL %s\r\n", .{name}); - } -} - -/// Word-at-a-time equality, the same shape the editor's frame diff uses. -fn sameBytesWordwise(a: []const u8, b: []const u8) bool { - if (a.len != b.len) return false; - if ((@intFromPtr(a.ptr) | @intFromPtr(b.ptr)) & 3 == 0) { - const n = a.len / 4; - const wa: [*]align(4) const u32 = @ptrCast(@alignCast(a.ptr)); - const wb: [*]align(4) const u32 = @ptrCast(@alignCast(b.ptr)); - for (wa[0..n], wb[0..n]) |x, y| { - if (x != y) return false; - } - return std.mem.eql(u8, a[n * 4 ..], b[n * 4 ..]); - } - return std.mem.eql(u8, a, b); -} - -/// A UART with a receive FIFO that loses whatever arrives into a full one, as the hardware does. -/// `pub` on the methods because `input_rescue` is a separate module here and reaches them by duck -/// typing across it. -const FakePort = struct { - tx_cap: u32, - tx_used: u32 = 0, - ticks: u32 = 0, - sent: u32 = 0, - incoming: []const u8, - delivered: usize = 0, - rx: [8]u8 = undefined, - rx_head: usize = 0, - rx_len: usize = 0, - lost: u32 = 0, - - fn tick(p: *FakePort) void { - p.ticks += 1; - if (p.ticks % 4 == 0 and p.tx_used > 0) p.tx_used -= 1; - if (p.delivered < p.incoming.len) { - const byte = p.incoming[p.delivered]; - p.delivered += 1; - if (p.rx_len == p.rx.len) { - p.lost += 1; - } else { - p.rx[(p.rx_head + p.rx_len) % p.rx.len] = byte; - p.rx_len += 1; - } - } - } - pub fn txFree(p: *FakePort) u32 { - p.tick(); - return p.tx_cap - p.tx_used; - } - pub fn pushByte(p: *FakePort, _: u8) void { - p.sent += 1; - p.tx_used += 1; - } - pub fn rxCount(p: *FakePort) u32 { - return @intCast(p.rx_len); - } - pub fn popByte(p: *FakePort) u8 { - const byte = p.rx[p.rx_head]; - p.rx_head = (p.rx_head + 1) % p.rx.len; - p.rx_len -= 1; - return byte; - } -}; - -/// Backing store for the heap checks. Static, because the point is to exercise the allocator on real -/// L2MEM rather than to find out where a stack array happens to land. -var heap_area: [64 * 1024]u8 align(16) = undefined; - -export fn zig_main() noreturn { - // THE CLOCK RAISE, performed here rather than assumed, which is what turns the frequency check - // at the end into a test of `setCpuFreq` instead of a tautology. The first version of this file - // read `config.cpu_mhz` and compared the die against it without ever setting it, so - // `-Dcpu-mhz=360` failed with `khz=90001 want=360000` - the check was right and the expectation - // was wrong. Same call, and the same order, as `src/pardes/app.zig`. - if (config.cpu_mhz != 90) hal.clkrst.setCpuFreq(switch (config.cpu_mhz) { - 360 => .mhz360, - else => .mhz90, - }); - hal.systimer.init(); - - soc.rom.print("\r\nMARK SELFTEST_START cpu_mhz=%u\r\n", .{@as(u32, config.cpu_mhz)}); - - // ------------------------------------------------ 1. the memory model the memory words assume - // - // `Peek`, `Poke` and `Hexdump` reach the bus through `*allowzero volatile` pointers and refuse an - // unaligned word. Both halves are claims about this core, and neither is checkable on a host. - { - const cell: *volatile u32 = @ptrCast(@alignCast(&heap_area[0])); - cell.* = 0xdeadbeef; - check("an aligned word round-trips through a volatile pointer", cell.* == 0xdeadbeef); - - // Every byte offset in a word, readable and writable: this is what `Hexdump` does, and it is - // why `Hexdump` needs no alignment while `Peek` does. - var all_offsets_ok = true; - for (0..4) |i| { - const at: *volatile u8 = @ptrCast(&heap_area[16 + i]); - at.* = @intCast(0xa0 + i); - if (at.* != 0xa0 + @as(u8, @intCast(i))) all_offsets_ok = false; - } - check("a byte at every offset in a word round-trips", all_offsets_ok); - - // THE VOLATILE PROMISE. Two reads of a running counter must be two reads. Were the optimiser - // allowed to fold them, `Peek` would print one value twice for a register that had changed, - // which is the one thing a memory word must never do. - const first = hal.systimer.micros(.unit0) orelse 0; - var spin: u32 = 0; - while (spin < 4000) : (spin += 1) asm volatile ("" ::: .{ .memory = true }); - const second = hal.systimer.micros(.unit0) orelse 0; - check("two reads of a live counter are two reads", second != first); - check("and that counter runs forwards", second > first); - } - - // --------------------------------------- 2. word-wise equality, on THIS instruction set - // - // The editor's frame diff compares rows a `u32` at a time because `std.mem.eql` compares a byte - // at a time here: 223 us against 66 for the same answer. "The same answer" is the part that has - // to hold on the target rather than on the host, so it is checked against `std.mem.eql` itself, - // at every difference position, at both alignments, and at lengths that are not multiples of 4. - { - var a: [64]u8 align(4) = undefined; - var b: [64]u8 align(4) = undefined; - for (&a, 0..) |*slot, i| slot.* = @intCast(i); - @memcpy(&b, &a); - - var agree = true; - for (0..a.len) |len| { - if (sameBytesWordwise(a[0..len], b[0..len]) != std.mem.eql(u8, a[0..len], b[0..len])) agree = false; - } - check("aligned equality agrees with std.mem.eql at every length", agree); - - agree = true; - for (0..a.len) |i| { - b[i] ^= 0xff; - if (sameBytesWordwise(&a, &b) != std.mem.eql(u8, &a, &b)) agree = false; - if (sameBytesWordwise(a[0..33], b[0..33]) != std.mem.eql(u8, a[0..33], b[0..33])) agree = false; - b[i] ^= 0xff; - } - check("a difference at any position is found, as std.mem.eql finds it", agree); - - agree = true; - // UNALIGNED, which is why `sameBytes` tests alignment at RUNTIME: `Cell` is all u8 fields, so - // whether a row starts on a word boundary belongs to the allocator and not to the type. - for (1..4) |off| { - const ua = a[off..]; - const ub = b[off..]; - if (sameBytesWordwise(ua, ub) != std.mem.eql(u8, ua, ub)) agree = false; - b[off + 5] ^= 0xff; - if (sameBytesWordwise(ua, ub) != std.mem.eql(u8, ua, ub)) agree = false; - b[off + 5] ^= 0xff; - } - check("unaligned spans fall back and still agree", agree); - } - - // ------------------------------------------------- 3. the rescue, on the real codegen - // - // The logic has a host test. What that cannot say is whether it behaves the same compiled for - // this core at this optimisation level, which is a question only a board answers. - { - const typed = "the quick brown fox jumps over the lazy dog, and then some more besides"; - var port: FakePort = .{ .tx_cap = 2, .incoming = typed }; - var ring: input_rescue.Ring = .{}; - const frame = "\x1b[1;1H" ++ "x" ** 300; - const abandoned = input_rescue.pump(&port, &ring, frame, 1_000_000); - - check("the frame went out whole", abandoned == 0 and port.sent == frame.len); - check("the receive FIFO never overflowed", port.lost == 0); - check("the ring dropped nothing", ring.dropped == 0); - - var got: [128]u8 = undefined; - var n = ring.pop(&got); - while (port.rxCount() > 0 and n < got.len) : (n += 1) got[n] = port.popByte(); - check("every rescued byte, in order", n == typed.len and std.mem.eql(u8, got[0..n], typed)); - } - - // --------------------------------------------------- 4. the allocator on real L2MEM - // - // The editor's whole geometry ceiling is an allocator question, and this is the allocator, on the - // memory it actually runs in rather than on a host's malloc. - { - var h = heapmod.Heap.init(heap_area[0..]); - const gpa = h.allocator(); - - const one = gpa.alloc(u32, 256) catch null; - check("a modest allocation succeeds", one != null); - if (one) |slice| { - check("and is aligned for its element", @intFromPtr(slice.ptr) % @alignOf(u32) == 0); - for (slice, 0..) |*slot, i| slot.* = @intCast(i * 7); - var intact = true; - for (slice, 0..) |slot, i| { - if (slot != i * 7) intact = false; - } - check("and holds what was written to it", intact); - gpa.free(slice); - } - - // FREE THEN REUSE. A heap that cannot hand the same bytes back is a heap that runs out, which - // on this board is the difference between a 40x12 grid and an 80x24 one. - var churn_ok = true; - for (0..64) |_| { - const block = gpa.alloc(u8, 1024) catch { - churn_ok = false; - break; - }; - gpa.free(block); - } - check("a kilobyte can be taken and returned repeatedly", churn_ok); - - // AND IT REFUSES CLEANLY. An allocator that returns garbage instead of an error when it is - // out is the failure mode that cost an afternoon during bring-up. - const absurd = gpa.alloc(u8, heap_area.len * 4); - check("an impossible allocation returns an error", absurd == error.OutOfMemory); - } - - // ------------------------------------------ 5. the clock, which everything divides by - // - // Every cycle count this firmware reports is divided by the configured frequency somewhere, and - // the systimer is clocked from the crystal rather than from the CPU - which is exactly what makes - // it a reference the CPU cannot flatter. The 90-to-360 MHz raise rested on this comparison. - { - const t0 = hal.systimer.micros(.unit0) orelse 0; - const c0 = soc.cycles(); - while ((hal.systimer.micros(.unit0) orelse 0) -% t0 < 20_000) {} - const us = (hal.systimer.micros(.unit0) orelse 0) -% t0; - const cy = soc.cycles() - c0; - const khz: u32 = if (us > 0) @intCast(cy * 1000 / us) else 0; - const want: u32 = @as(u32, config.cpu_mhz) * 1000; - // Two percent: far wider than either clock's error, far narrower than the 4x a wrong divider - // would produce. - const slack = want / 50; - soc.rom.print("MARK SELFTEST_CLOCK khz=%u want=%u\r\n", .{ khz, want }); - check("the cycle counter and the systimer agree on the CPU frequency", khz > want - slack and khz < want + slack); - } - - soc.rom.print("MARK SELFTEST DONE pass=%u fail=%u\r\n", .{ passed, failed }); - while (true) {} -} diff --git a/examples/uartperf.zig b/examples/uartperf.zig index 339f642..4a1c0c5 100644 --- a/examples/uartperf.zig +++ b/examples/uartperf.zig @@ -10,7 +10,7 @@ //! //! * **No `soc.rom.print`.** The mask ROM's `ets_printf` formats and then pushes one byte at a //! time, spinning on the FIFO for each - the exact cost this is trying to measure around. Every -//! byte here goes through the same batched FIFO path `src/pardes/uart.zig` uses. +//! byte here goes through the same batched FIFO path `../02-pardes-code/src/esp32p4/uart.zig` uses. //! * **No UART reconfiguration.** Not the divider, not the format, not `reset()`. The //! second-stage bootloader configured this block; `hal/uart.zig:195-211` records that resetting //! it returns UART_CLKDIV to its power-on value and takes the session with it. diff --git a/src/pardes/app.zig b/src/pardes/app.zig deleted file mode 100644 index 17bef83..0000000 --- a/src/pardes/app.zig +++ /dev/null @@ -1,483 +0,0 @@ -//! pardes, as ESP32-P4 firmware. -//! -//! There is no operating system under this. `_start` is the reset entry the second-stage bootloader -//! jumps to, and this file is the entire platform: a heap, a millisecond clock, and UART0. -//! -//! ## Where the editor is -//! -//! Not in this package. `../02-pardes-code` compiles its core for riscv32-freestanding and emits -//! ONE object exporting the six C functions declared below; `-Dpardes` links it. The seam is a file -//! rather than a package dependency for a reason recorded at length in `build.zig`: declaring the -//! editor as a `build.zig.zon` path dependency nested its ~30-package graph under this one and -//! broke every build in this repo, including the ones that have nothing to do with it. -//! -//! The seam is deliberately **bytes in, bytes out**. Everything that needs to know what a cell is - -//! vaxis, the ANSI encoder, the input parser, the capability handshake - lives on the far side, -//! next to the vaxis it is built against. What crosses is a byte stream in each direction, which is -//! exactly what a serial line is, so this file has no opinion about terminals at all. -//! -//! ## Where the memory is -//! -//! Measured on this die by `examples/memprobe.zig`, not read off a datasheet: -//! -//! 0x4FF02000..0x4FF3F000 244 KiB .data/.bss/.stack live at the bottom of this -//! 0x4FF3F000..0x4FF40000 4 KiB mask ROM .data/.bss - untouchable, ets_printf needs it -//! 0x4FF40000..0x4FFC0000 512 KiB handed to the editor as its entire heap -//! -//! The 512 KiB arrives as `__heap_start`/`__heap_end` from the generated linker script, so those -//! addresses are written down in exactly one place. The editor owns that span outright: it is -//! passed in at init and this file never allocates from it. -//! -//! PSRAM is not used. The board has 32 MB fitted and it would make all of this comfortable, but -//! ESP-IDF's own ESP32-P4 implementation runs past a thousand lines - MPLL, MSPI clocking, pin -//! drive and DQS, CS timing, mode registers, a connectivity check, and an entire timing-calibration -//! subsystem - and the mask ROM offers only MMU mapping, no device init. Touching it untrained -//! faults and hangs the core, which `examples/memprobe.zig` demonstrates on purpose. - -const std = @import("std"); -const soc = @import("soc"); -const config = @import("config"); - -/// `-Dprof`: time the two phases of a keystroke on the board and print the cycle counts. A -/// diagnostic, not a feature - see the loop. -const prof = config.prof; - -/// Every byte this loop has taken off the UART, for `-Dprof`. Ground truth for "did the burst -/// arrive", which a screen reconstruction cannot answer: a character can be missing from the screen -/// because it never arrived, because the editor never applied it, or because the viewport does not -/// show that column. -var rx_total: u32 = 0; - -/// How many input bytes to hand the editor before draining the receiver again. Chosen against the -/// FIFO rather than against the editor: 128 bytes of FIFO is 11 ms of wire at 115200, and 32 -/// keystrokes cost about 2 ms even on a long line, which leaves five times the margin needed. -const input_chunk = 8; -const hal = @import("hal"); -const heapmod = @import("heap"); -const uart = @import("uart.zig"); - -// ------------------------------------------------------------------------------------- the ABI -// Seven functions, all `callconv(.c)`, all implemented in the linked object. This is the complete -// interface between this board and the editor, and it is deliberately bytes-and-memory only: the -// editor never learns what a UART is, and this file never learns what a cell is. - -/// How the editor emits bytes. Called with finished runs of ANSI, many times per frame. -const WriteFn = *const fn (ctx: ?*anyopaque, ptr: [*]const u8, len: usize) callconv(.c) void; - -/// The board's pads, offered to the editor. Optional on the wire so a firmware with nothing to -/// toggle passes null and the `Gpio` word reports that rather than the object guessing. -const GpioFn = *const fn (ctx: ?*anyopaque, pin: u16, was: *u8, now: *u8) callconv(.c) bool; - -/// This board's allocator, handed across as plain function pointers. `log2_align` is a log2 value, -/// which is exactly how `std.mem.Alignment` represents itself, so neither side needs a conversion -/// table. -/// -/// The memory belongs to THIS side: only the firmware knows that the heap is the 384 KiB at -/// 0x4FF40000, that the 128 KiB above it is L2 cache, and that PSRAM is untrained. The editor gets -/// an allocator, not an address range. -const Allocator = extern struct { - ctx: ?*anyopaque, - alloc: *const fn (ctx: ?*anyopaque, len: usize, log2_align: u8) callconv(.c) ?[*]u8, - resize: *const fn (ctx: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8, new_len: usize) callconv(.c) bool, - free: *const fn (ctx: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8) callconv(.c) void, -}; - -/// The one number both sides must agree on. Linkers do not type-check C symbols, so a signature -/// that drifts on one side of this seam links cleanly and then corrupts the stack; checking this -/// before calling anything else turns that into a refusal to boot. -const abi_version: u32 = 2; -extern fn pardes_p4_abi_version() callconv(.c) u32; - -/// Hand over the allocator and the output sink, and state the initial window size. Returns 0, or a -/// small non-zero code this file can only report. -extern fn pardes_p4_init( - alloc: *const Allocator, - write: WriteFn, - gpio: ?GpioFn, - ctx: ?*anyopaque, - cols: u16, - rows: u16, -) callconv(.c) u32; - -/// Raw bytes off the wire: keystrokes, capability-query replies, and the host bridge's in-band -/// resize reports. The editor parses all three; this file distinguishes none of them. -extern fn pardes_p4_input(ptr: [*]const u8, len: usize) callconv(.c) void; - -/// Advance time. Separate from `input` because animations and timeouts must progress on a wire -/// where nothing is arriving. -extern fn pardes_p4_tick(now_ms: u64) callconv(.c) void; - -/// Emit one frame through the write callback. Returns 0 or an error code. -extern fn pardes_p4_render() callconv(.c) u32; - -/// Is there anything to draw - a dirty surface or a running animation? Asked every iteration so a -/// quiet editor costs no bytes on a 115200-baud link. -extern fn pardes_p4_wants_frame() callconv(.c) bool; - -/// Has the user asked to leave? There is nowhere to go, so this only stops the loop. -extern fn pardes_p4_quit() callconv(.c) bool; - -/// The last frame's three stages in CPU cycles: the copy of pardes's Surface into vaxis's grid, -/// vaxis's own diff-and-emit, and the push into the UART. Only meaningful under `-Dprof`; the -/// editor object always exports it, and it costs two CSR reads per stage. -extern fn pardes_p4_frame_prof(copy: *u64, render: *u64, flush: *u64) callconv(.c) void; - -// ------------------------------------------------------------------------------------ the sink - -/// The write callback handed to `pardes_p4_init`. No context is needed - there is one UART. -fn writeOut(_: ?*anyopaque, ptr: [*]const u8, len: usize) callconv(.c) void { - uart.write(ptr[0..len]); -} - -/// Flip one pad and report the level before and after. The editor's `Gpio` word calls this; the -/// editor has no register of its own for it, deliberately. -/// -/// THIS IS WHY THE SEAM IS HERE. A toggle is not a write to GPIO_OUT: `configureOutput` points the -/// pad's IO MUX at the GPIO function, routes the GPIO matrix's output to it, sets the drive strength -/// and input buffer and clears the pulls, and only then enables the driver - four register files, -/// indexed by a per-pin table. That code already exists in `hal/gpio.zig`, it is the same call -/// `src/main.zig` blinks with, and its register numbers are checked against ESP-IDF's own headers by -/// `zig build diff`. A second copy inside the editor object would be a second copy under no test. -/// -/// `getDrivenLevel` rather than `getLevel`: the answer is the level this board is DRIVING, which is -/// defined for every pin. The pad's own level is what the outside world says, and on an unconnected -/// header pin that is noise. The input buffer is enabled anyway, so `Peek` of GPIO_IN_REG shows the -/// pad for anyone who wants to compare the two. -fn gpioToggle(_: ?*anyopaque, pin: u16, was: *u8, now: *u8) callconv(.c) bool { - if (pin > hal.gpio.max_pin) return false; - const p: u8 = @intCast(pin); - hal.gpio.configureOutput(p, .{ .readback = true }); - const before = hal.gpio.getDrivenLevel(p); - if (before == 1) hal.gpio.setLow(p) else hal.gpio.setHigh(p); - was.* = before; - now.* = hal.gpio.getDrivenLevel(p); - return true; -} - -// ------------------------------------------------------------------------------------- the heap - -/// The span the linker script hands over, from `l2high`'s ORIGIN and LENGTH. -/// -/// Reached with `@extern`, NOT with `extern const __heap_start: anyopaque` plus -/// `@intFromPtr`/`@ptrFromInt`. That spelling was here first and it was silently wrong: declaring a -/// linker symbol as an `anyopaque` OBJECT gives the optimiser a zero-sized object, so a pointer -/// derived from its address carries provenance for zero bytes, and ordinary (non-volatile) stores -/// through it are dead code it may drop. `examples/heapcheck.zig` caught it on the die - the -/// allocator's first block header read back as `size=2988759312 next=0xffffffff`-not, and the free -/// list walk never terminated. A `[*]u8` from `@extern` has no size to lose. -const heap_start = @extern([*]align(heapmod.Heap.granule) u8, .{ .name = "__heap_start" }); -const heap_end = @extern([*]align(heapmod.Heap.granule) u8, .{ .name = "__heap_end" }); - -fn heapSpan() []align(heapmod.Heap.granule) u8 { - return heap_start[0 .. @intFromPtr(heap_end) - @intFromPtr(heap_start)]; -} - -/// The one heap. A K&R coalescing free list over that span, validated on this die by -/// `examples/heapcheck.zig`: 512 blocks fill and free back to a single 393,216-byte block, a holed -/// arena still satisfies a 4 KiB request, and 20,000 random operations drain back to one block. -var gpa_heap: heapmod.Heap = undefined; - -// The four C forwarders the editor is handed. `log2_align` round-trips through -// `std.mem.Alignment`, whose representation IS the log2 value. - -fn cAlloc(_: ?*anyopaque, len: usize, log2_align: u8) callconv(.c) ?[*]u8 { - const a = gpa_heap.allocator(); - return a.vtable.alloc(a.ptr, len, @enumFromInt(log2_align), @returnAddress()); -} - -fn cResize(_: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8, new_len: usize) callconv(.c) bool { - const a = gpa_heap.allocator(); - return a.vtable.resize(a.ptr, ptr[0..len], @enumFromInt(log2_align), new_len, @returnAddress()); -} - -fn cFree(_: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8) callconv(.c) void { - const a = gpa_heap.allocator(); - a.vtable.free(a.ptr, ptr[0..len], @enumFromInt(log2_align), @returnAddress()); -} - -const editor_allocator: Allocator = .{ - .ctx = null, - .alloc = cAlloc, - .resize = cResize, - .free = cFree, -}; - -// ------------------------------------------------------------------------------------ the clock - -/// Milliseconds since boot, off the systimer - a 16 MHz counter (`hal/systimer.zig:31`), which is -/// the cheapest trustworthy clock on this chip. `read` returns null if the unit is not running, in -/// which case time simply does not advance and the editor stops animating; that is a better failure -/// than a clock that jumps. -fn nowMs() u64 { - const us = hal.systimer.micros(.unit0) orelse return 0; - return us / 1000; -} - -// ------------------------------------------------------------------------------------- the loop - -export fn zig_main() noreturn { - // FIRST, before a single byte of `.rodata` is touched - which means before the marker below, - // because that marker IS a string literal in flash and would read as machine code without this. - soc.flushFlashCache(); - const heap = heapSpan(); - soc.rom.print("\r\nMARK B3 rom.print heap 0x%08x..0x%08x %u KiB\r\n", .{ - @as(u32, @intFromPtr(heap.ptr)), - @as(u32, @intFromPtr(heap.ptr)) + @as(u32, @intCast(heap.len)), - @as(u32, @intCast(heap.len / 1024)), - }); - - // The CPU clock, before anything is timed against it. The bootloader leaves 90 MHz and the - // CPLL is already at 360, so this is a divider change that disturbs neither UART0 (XTAL) nor - // the systimer (XTAL/2.5) nor the flash interface (SPLL). See hal/clkrst.zig:setCpuFreq. - if (config.cpu_mhz != 90) hal.clkrst.setCpuFreq(switch (config.cpu_mhz) { - 180 => .mhz180, - 360 => .mhz360, - else => .mhz90, - }); - - const rwdt_was_armed = hal.rwdt.disable(); - hal.systimer.init(); - _ = rwdt_was_armed; - - const their_abi = pardes_p4_abi_version(); - if (their_abi != abi_version) { - uart.write("MARK PARDES_ABI_MISMATCH\r\n"); - while (true) {} - } - - gpa_heap = heapmod.Heap.init(heap); - _ = uart.drainInput(); - - // Ask for more than any grid this board will ever render, so the SHELL's own ceiling is what - // governs - it clamps to `-Dp4-cols`/`-Dp4-rows` and reports the result. Naming 80x24 here made - // the firmware a second opinion about the geometry, which is one opinion too many. - const rc = pardes_p4_init(&editor_allocator, writeOut, gpioToggle, null, 255, 255); - - if (rc != 0) { - soc.rom.print("MARK PARDES_INIT_FAIL rc=%u\r\n", .{rc}); - const s = gpa_heap.stats(); - soc.rom.print("MARK PARDES_HEAP free=%u largest=%u blocks=%u\r\n", .{ - s.free, s.largest_free, s.free_blocks, - }); - while (true) {} - } - - // The HEAP, after the editor has taken what it needs. This is the number that decides how large - // a grid the board can drive, so it is printed on every boot rather than only on failure: a - // geometry that fits with 2 KB to spare and one that fits with 80 KB are not the same answer, - // and the difference is invisible from the host otherwise. - { - const s = gpa_heap.stats(); - soc.rom.print("MARK PARDES_HEAP free=%u largest=%u blocks=%u\r\n", .{ - s.free, s.largest_free, s.free_blocks, - }); - } - - // The CPU clock, measured rather than assumed. Every cycle count this firmware reports is - // divided by it somewhere, and `src/io/chip.zig` records it as "a measured ~90 MHz" that - // nothing here reconfigures - so it is worth printing rather than remembering. The systimer is - // XTAL/2.5 = 16 MHz and is NOT derived from the CPU clock (`hal/systimer.zig:31`, - // `clk_tree_defs.h:196-198`), which is exactly what makes it a valid reference for measuring it. - if (prof) { - const t_start = hal.systimer.micros(.unit0) orelse 0; - const c_start = soc.cycles(); - // 50 ms is long enough that the systimer's 16 MHz granularity and the loop's own overhead - // are both noise, and short enough to be invisible in a boot. - while ((hal.systimer.micros(.unit0) orelse 0) -% t_start < 50_000) {} - const elapsed_us = (hal.systimer.micros(.unit0) orelse 0) -% t_start; - const elapsed_cy = soc.cycles() - c_start; - soc.rom.print("MARK CPU_HZ cycles=%u us=%u khz=%u\r\n", .{ - @as(u32, @intCast(elapsed_cy)), - @as(u32, @intCast(elapsed_us)), - @as(u32, @intCast(if (elapsed_us > 0) elapsed_cy * 1000 / elapsed_us else 0)), - }); - } - soc.rom.print("MARK PARDES_READY\r\n", .{}); - - var in: [256]u8 = undefined; - while (!pardes_p4_quit()) { - // ATTRIBUTION. The host can time a keystroke's round trip but cannot see what the firmware - // spent it on, and the two candidates - parsing and editing, versus rendering - want - // opposite fixes. `soc.cycles()` is the unprivileged cycle counter, so this costs two CSR - // reads per phase and quantises at one cycle, which is four orders of magnitude below the - // milliseconds being attributed. Gated on `prof` so the shipping build carries none of it. - const n = uart.read(&in); - rx_total +%= @intCast(n); - - var input_cy: u64 = 0; - if (n > 0) { - const t0 = if (prof) soc.cycles() else 0; - // IN CHUNKS, rescuing the receiver between them. Applying a keystroke is not free and - // gets dearer as the line grows - measured at 44 us on an empty line and 63 us at 640 - // characters - so handing over a full 128-byte batch is up to 8 ms in which nothing - // drains the receiver, against a FIFO that holds only 11 ms of wire. A 600-byte paste - // lost 93 bytes to exactly that window even with the transmitter's own rescue in place. - // - // Splitting a burst at an arbitrary byte is safe: `pardes_p4_input` keeps whatever it - // could not parse, which is how it already survives an escape sequence split across two - // UART reads. One render still happens per loop iteration, so this costs no extra wire. - var off: usize = 0; - while (off < n) { - const chunk = @min(input_chunk, n - off); - pardes_p4_input(in[off..].ptr, chunk); - off += chunk; - if (off < n) uart.rescueNow(); - } - if (prof) input_cy = soc.cycles() - t0; - } - - pardes_p4_tick(nowMs()); - - // Only when there is something to show. On a link this slow an unconditional repaint per - // iteration would saturate the wire and starve input. - if (pardes_p4_wants_frame()) { - const t0 = if (prof) soc.cycles() else 0; - const err = pardes_p4_render(); - if (err != 0) soc.rom.print("MARK PARDES_RENDER_FAIL rc=%u\r\n", .{err}); - if (prof) { - const render_cy = soc.cycles() - t0; - // A SECOND render with nothing changed since the first. It splits the cost in two: - // whatever this still costs is the price of walking and diffing the whole editor - // state, paid regardless of output, while the difference between the two is the - // price of the change itself. `wants_frame` is false now, so this only happens - // under -Dprof and never on a shipping build. - const t1 = soc.cycles(); - _ = pardes_p4_render(); - const idle_cy = soc.cycles() - t1; - // Reported in cycles, not microseconds: the divisor is the CPU clock, which this - // firmware does not set and has only ever measured, so converting here would bake a - // guess into the data. `experiments/` divides by the clock it measured. - var copy_cy: u64 = 0; - var vx_cy: u64 = 0; - var flush_cy: u64 = 0; - pardes_p4_frame_prof(©_cy, &vx_cy, &flush_cy); - soc.rom.print("PROF in=%u render=%u idle=%u copy=%u vaxis=%u flush=%u rx=%u rxdrop=%u txdrop=%u\r\n", .{ - @as(u32, @intCast(input_cy)), - @as(u32, @intCast(render_cy)), - @as(u32, @intCast(idle_cy)), - @as(u32, @intCast(copy_cy)), - @as(u32, @intCast(vx_cy)), - @as(u32, @intCast(flush_cy)), - rx_total, - uart.inputDropped(), - uart.dropped, - }); - } - } - } - - soc.rom.print("\r\nMARK PARDES_QUIT\r\n", .{}); - while (true) {} -} - -// ------------------------------------------------------------------------------------ the trap - -/// A trap handler, because the absence of one is why this port has been guessing. -/// -/// The mask ROM prints "Guru Meditation" for a trap only while ITS handler is still installed; -/// anything this image does that replaces or outgrows that path fails silently instead, and a silent -/// fault is indistinguishable from an infinite loop over a serial line. This one reports the three -/// registers that name the fault and then stops, using the direct-FIFO writer so it shares nothing -/// with the editor's buffered output. -/// -/// `mtvec` is set in DIRECT mode (low two bits zero), so every trap and every interrupt lands on -/// `trapEntry` regardless of cause - which is what a diagnostic wants. -export fn trapEntry() linksection(".text.entry") callconv(.naked) noreturn { - asm volatile ("j trapReport"); -} - -export fn trapReport() noreturn { - const mcause = asm volatile ("csrr %[o], mcause" - : [o] "=r" (-> u32), - ); - const mepc = asm volatile ("csrr %[o], mepc" - : [o] "=r" (-> u32), - ); - const mtval = asm volatile ("csrr %[o], mtval" - : [o] "=r" (-> u32), - ); - uart.write("\r\nMARK TRAP mcause="); - uart.dumpWord(mcause); - uart.write("MARK TRAP mepc="); - uart.dumpWord(mepc); - uart.write("MARK TRAP mtval="); - uart.dumpWord(mtval); - uart.write("MARK TRAP dropped="); - uart.dumpWord(uart.dropped); - while (true) {} -} - -// --------------------------------------------------------------------------- the root's own duties - -/// `page_size_min`/`max`: the board has no MMU and no pages, but std derives allocator alignment -/// from these. 4 KiB is the ESP32-P4's cache and DMA granularity. -/// -/// `logFn` is not cosmetic. std's default log implementation reaches `std.debug_io`, which -/// instantiates `std.Io.Threaded` - a thread pool, `getrandom`, `IOV_MAX`, `mremap` - none of which -/// exist here, and one `log.warn` from anywhere is enough to drag all of it into the image. -pub const std_options: std.Options = .{ - .page_size_min = 4096, - .page_size_max = 4096, - .logFn = logFn, -}; - -fn logFn( - comptime level: std.log.Level, - comptime scope: @EnumLiteral(), - comptime fmt: []const u8, - args: anytype, -) void { - var buf: [256]u8 = undefined; - const line = std.fmt.bufPrint(&buf, "\r\n[" ++ level.asText() ++ "/" ++ @tagName(scope) ++ "] " ++ fmt ++ "\r\n", args) catch - "\r\n[log overflow]\r\n"; - uart.write(line); -} - -pub const panic = std.debug.FullPanic(panicImpl); - -fn panicImpl(msg: []const u8, first_trace_addr: ?usize) noreturn { - // The fixed text goes out through the ROM deliberately: a panic may BE the console writer - // failing, and `ets_printf` shares nothing with `uart.write` except the FIFO itself. - // - // The MESSAGE does not, and that is a correction rather than a preference. `msg` is a Zig SLICE - // and `%s` reads until a NUL, so handing `msg.ptr` to printf prints the message and then - // whatever happens to sit after it in memory until a zero byte turns up. Literals get away with - // it; std's own panics do not, because they are formatted into a buffer - "index out of bounds: - // index 5, len 3" - and carry no terminator. `uart.write` takes a length. - soc.rom.print("\r\nMARK PARDES_PANIC ", .{}); - uart.write(msg); - // The address is what makes it actionable: addr2line against the ELF in zig-out turns it into a - // source line, and without it a panic message names a KIND of failure with no way to find which - // one of them happened. Zero when the caller had no return address to give. - soc.rom.print("\r\nMARK PARDES_PANIC_AT 0x%08x\r\n", .{@as(u32, @truncate(first_trace_addr orelse 0))}); - while (true) {} -} - -/// Reset entry. The bootloader hands over with an unspecified stack pointer and the FPU off, so: -/// enable the F extension (`mstatus.FS`, which ESP-IDF only ever turns on lazily from a trap handler -/// this image does not have), establish a stack, clear `.bss`, and call into Zig. -/// -/// The cache invalidate that this image also needs is the FIRST thing `zig_main` does, not something -/// done here. Hand-written `la t0, Cache_Invalidate_All` against an absolute linker symbol computed -/// a PC-relative target and jumped into nowhere (measured: PC=0x88b5d788 with the argument stranded -/// in a2); Zig generates the addressing for an `extern fn` correctly, and `zig_main` runs before any -/// `.rodata` is touched anyway. -export fn _start() linksection(".text.entry") callconv(.naked) noreturn { - asm volatile ( - \\ li t0, 1 << 13 - \\ csrs mstatus, t0 - \\ la sp, __stack_top - \\ mv fp, sp - \\ la t0, trapEntry - \\ csrw mtvec, t0 - \\ la t0, __bss_start - \\ la t1, __bss_end - \\ bgeu t0, t1, 2f - \\1: - \\ sw zero, 0(t0) - \\ addi t0, t0, 4 - \\ bltu t0, t1, 1b - \\2: - \\ j zig_main - ); -} diff --git a/src/pardes/input_rescue.zig b/src/pardes/input_rescue.zig deleted file mode 100644 index ea242b2..0000000 --- a/src/pardes/input_rescue.zig +++ /dev/null @@ -1,248 +0,0 @@ -//! Keystrokes rescued from the receive FIFO while the transmitter is busy. -//! -//! THE BUG THIS EXISTS FOR. The firmware's loop is read, apply, render, write, and the write blocks -//! while the transmit FIFO is full - real backpressure, because dropping half an escape sequence -//! would leave the host terminal in the wrong colour for the rest of the session. But nothing -//! drained the RECEIVE FIFO during that wait, and the FIFO is 128 bytes (`hal/uart.zig:52`). A frame -//! of 240 bytes is 21 ms of wire at 115200, and 21 ms of a host sending at line rate is ~240 bytes, -//! so everything past the 128th was silently gone. -//! -//! Measured on the die before the fix, typing a burst in one host write and counting what the editor -//! actually held: 128 bytes arrived intact, 200 bytes lost 88, 300 bytes lost all 300. From a -//! keyboard that is a keystroke that never lands, and it looks like a stuck key - the screen is -//! behind what was typed, and typing more appears to fix it because a later frame repaints the cells -//! the lost keystrokes would have changed. -//! -//! WHY THE POLICY LIVES HERE and not in `uart.zig`: the interesting part is a decision - drain the -//! receiver while spinning on the transmitter, and what to do when even that overflows - and the -//! decision is worth testing. `uart.zig` cannot be tested at all without the chip, because every -//! line of it is an MMIO access. `pump` takes the port as `anytype`, so the same code runs against -//! the real UART on the board and against a fake with a two-byte FIFO in `zig build test`. - -const std = @import("std"); - -/// Capacity, sized for the worst frame this editor emits. -/// -/// A full repaint is ~1.4 KB, which is 121 ms of wire at 115200, and 121 ms of a host pasting at -/// line rate is ~1.4 KB of input. 4 KiB is that with headroom, a power of two so the wrap is a mask -/// rather than a division, and nothing at all against the board's RAM. -pub const capacity = 4096; - -/// A byte queue that drops the NEWEST byte when full. -/// -/// Dropping the newest rather than the oldest is deliberate: what survives is then a PREFIX of what -/// was typed. An editor that loses the end of a paste has done something a person can see and -/// correct; one that silently reorders keystrokes, or keeps the tail and discards the head, has -/// corrupted the document in a way that looks like the editor inventing input. -pub const Ring = struct { - buf: [capacity]u8 = undefined, - head: usize = 0, - len: usize = 0, - /// Bytes lost because even this overflowed. Nonzero means input was dropped; it is the honest - /// version of the bug rather than a cure for it. - dropped: u32 = 0, - - const mask = capacity - 1; - - comptime { - std.debug.assert(capacity & mask == 0); - } - - pub fn push(r: *Ring, b: u8) void { - if (r.len == capacity) { - r.dropped +%= 1; - return; - } - r.buf[(r.head + r.len) & mask] = b; - r.len += 1; - } - - /// Move as much as fits into `out`, oldest first. Returns the count. - pub fn pop(r: *Ring, out: []u8) usize { - const n = @min(out.len, r.len); - for (out[0..n]) |*slot| { - slot.* = r.buf[r.head]; - r.head = (r.head + 1) & mask; - } - r.len -= n; - return n; - } - - pub fn clear(r: *Ring) void { - r.head = 0; - r.len = 0; - } -}; - -/// Drain everything the port has received into `ring`, without waiting. -pub fn rescue(port: anytype, ring: *Ring) void { - var waiting = port.rxCount(); - while (waiting > 0) : (waiting -= 1) ring.push(port.popByte()); -} - -/// Push `bytes` through `port`, rescuing input whenever the transmitter has no room. Returns the -/// number of bytes abandoned because the transmitter stopped making progress altogether. -/// -/// The spin bound is why this returns a count rather than blocking forever: a UART whose core clock -/// has been gated never makes progress, and on a board with no debugger an infinite spin is -/// indistinguishable from a crash. A bounded wait turns that into visibly dropped output plus a -/// counter, which is a diagnosis instead of a mystery. -pub fn pump(port: anytype, ring: *Ring, bytes: []const u8, spin_limit: u32) u32 { - var rest = bytes; - while (rest.len > 0) { - // One status read per burst, not per byte: reading `txFree` once and pushing that many cuts - // the status reads by up to the FIFO depth. - var room = port.txFree(); - var spins: u32 = 0; - while (room == 0) { - // THE FIX. Every iteration of this wait is time the receiver is filling up, and this is - // the only place that can empty it. - rescue(port, ring); - spins += 1; - if (spins > spin_limit) return @intCast(rest.len); - room = port.txFree(); - } - const n = @min(room, rest.len); - for (rest[0..n]) |b| port.pushByte(b); - rest = rest[n..]; - } - return 0; -} - -// ------------------------------------------------------------------------------------ host tests - -test "the ring hands bytes back in order" { - var r: Ring = .{}; - for ("hello") |b| r.push(b); - var out: [8]u8 = undefined; - try std.testing.expectEqual(@as(usize, 5), r.pop(&out)); - try std.testing.expectEqualStrings("hello", out[0..5]); - try std.testing.expectEqual(@as(usize, 0), r.pop(&out)); -} - -test "the ring wraps without reordering" { - var r: Ring = .{}; - var out: [capacity]u8 = undefined; - // Push and pop most of the buffer so head sits near the end, then straddle the wrap. - for (0..capacity - 3) |i| r.push(@intCast(i & 0xff)); - _ = r.pop(out[0 .. capacity - 3]); - for ("straddle") |b| r.push(b); - const n = r.pop(&out); - try std.testing.expectEqualStrings("straddle", out[0..n]); -} - -test "a full ring drops the newest and says so" { - var r: Ring = .{}; - for (0..capacity) |i| r.push(@intCast(i & 0xff)); - try std.testing.expectEqual(@as(u32, 0), r.dropped); - r.push('!'); - r.push('!'); - try std.testing.expectEqual(@as(u32, 2), r.dropped); - // The head is intact: what survived is a prefix of what arrived. - var out: [4]u8 = undefined; - _ = r.pop(&out); - try std.testing.expectEqual(@as(u8, 0), out[0]); - try std.testing.expectEqual(@as(u8, 1), out[1]); -} - -/// A UART with a small transmit FIFO, a small RECEIVE FIFO, and a host that keeps typing into it. -/// -/// The receive FIFO is the part that matters and it is modelled the way the hardware behaves: it has -/// a fixed depth, and a byte that arrives when it is full is *gone*. That is the whole bug. -/// -/// Time advances on each transmitter status read, which is what `pump` does while it waits. The -/// transmitter frees a byte only every fourth tick while a typed byte lands on every one: the -/// transmitter therefore genuinely FILLS, which is the condition the bug needs. A fake whose FIFO -/// drains as fast as it fills never blocks, so `pump` never waits, so the rescue never runs and the -/// test proves nothing - the first version of this fake had exactly that flaw. -const FakePort = struct { - tx_cap: u32, - tx_used: u32 = 0, - sent: std.ArrayList(u8) = .empty, - gpa: std.mem.Allocator, - - incoming: []const u8, - delivered: usize = 0, - rx: [rx_depth]u8 = undefined, - rx_head: usize = 0, - rx_len: usize = 0, - /// Bytes the wire delivered into a full receive FIFO. The hardware has no counter for this, - /// which is exactly why the bug was invisible. - lost: u32 = 0, - - ticks: u32 = 0, - - const rx_depth = 8; - const tx_drain_every = 4; - - fn tick(p: *FakePort) void { - p.ticks += 1; - if (p.ticks % tx_drain_every == 0 and p.tx_used > 0) p.tx_used -= 1; - if (p.delivered < p.incoming.len) { - const b = p.incoming[p.delivered]; - p.delivered += 1; - if (p.rx_len == rx_depth) { - p.lost += 1; - } else { - p.rx[(p.rx_head + p.rx_len) % rx_depth] = b; - p.rx_len += 1; - } - } - } - - fn txFree(p: *FakePort) u32 { - p.tick(); - return p.tx_cap - p.tx_used; - } - - fn pushByte(p: *FakePort, b: u8) void { - p.sent.append(p.gpa, b) catch unreachable; - p.tx_used += 1; - } - - fn rxCount(p: *FakePort) u32 { - return @intCast(p.rx_len); - } - - fn popByte(p: *FakePort) u8 { - const b = p.rx[p.rx_head]; - p.rx_head = (p.rx_head + 1) % rx_depth; - p.rx_len -= 1; - return b; - } -}; - -test "a long transmit does not lose the input that arrives during it" { - // THE REGRESSION. Delete the `rescue` call inside `pump`'s wait and this fails: the receive FIFO - // is eight bytes deep, the typing below is far longer than that, and every byte that arrives - // into a full FIFO is gone with nothing to record it. That is the die's 88-of-200 in miniature. - const typed = "the quick brown fox jumps over the lazy dog, twice over, and then some more"; - var port: FakePort = .{ .tx_cap = 2, .incoming = typed, .gpa = std.testing.allocator }; - defer port.sent.deinit(std.testing.allocator); - var ring: Ring = .{}; - - const frame = "\x1b[1;1H" ++ "x" ** 400; - try std.testing.expectEqual(@as(u32, 0), pump(&port, &ring, frame, 1_000_000)); - - // Every output byte went out, in order. - try std.testing.expectEqualStrings(frame, port.sent.items); - // Nothing the wire delivered was dropped, by the FIFO or by the ring. - try std.testing.expectEqual(@as(u32, 0), port.lost); - try std.testing.expectEqual(@as(u32, 0), ring.dropped); - // And what was rescued, plus whatever is still sitting in the FIFO, is exactly what was typed - - // in order, which is the other half of the contract. - var got: [capacity]u8 = undefined; - var n = ring.pop(&got); - while (port.rxCount() > 0) : (n += 1) got[n] = port.popByte(); - try std.testing.expectEqualStrings(typed[0..port.delivered], got[0..n]); - try std.testing.expect(port.delivered == typed.len); -} - -test "a transmitter that never drains gives up and reports what it abandoned" { - var port: FakePort = .{ .tx_cap = 0, .incoming = "", .gpa = std.testing.allocator }; - defer port.sent.deinit(std.testing.allocator); - var ring: Ring = .{}; - // tx_cap 0 means txFree is always 0, so no byte can ever go out. - try std.testing.expectEqual(@as(u32, 5), pump(&port, &ring, "abcde", 32)); - try std.testing.expectEqual(@as(usize, 0), port.sent.items.len); -} diff --git a/src/pardes/uart.zig b/src/pardes/uart.zig deleted file mode 100644 index 7696742..0000000 --- a/src/pardes/uart.zig +++ /dev/null @@ -1,153 +0,0 @@ -//! UART0 as the editor's terminal: bytes out, bytes in, and nothing else. -//! -//! This is the whole of the firmware's I/O. There is no framebuffer and no keyboard; the board -//! emits ANSI and consumes ANSI, and the terminal emulator on the far end of the CH340 does the -//! rest of the work - including answering the editor's own capability queries, which travel down -//! this wire like any other bytes. -//! -//! Deliberately not a `std.Io.Writer`. The ANSI encoding lives on the other side of the C ABI, next -//! to the vaxis that produces it (see `src/pardes/app.zig` for why the seam is there and not -//! elsewhere), so what crosses into this file is already a finished run of bytes. A writer here -//! would be a second buffer in front of one that already exists. -//! -//! Two decisions worth stating, because both are measurements rather than preferences. -//! -//! **Batched FIFO access.** The naive push is `while (txFree() == 0) {}` then `pushByte`, once per -//! byte: one MMIO read per byte at best, many while the FIFO is full. Reading `txFree` once and -//! then pushing that many cuts the status reads by up to the FIFO depth (128, `hal/uart.zig:52`). -//! At 115200 the wire costs ~86 us per byte and dwarfs either version, so today this is merely -//! free - and it stops being free the moment the divider is raised. -//! -//! **UART0's configuration is never touched.** Not the divider, not the format, not the pad -//! routing, and above all not `reset()`. The second-stage bootloader configured this block, and -//! `hal/uart.zig:195-211` records what happens if it is reset: UART_CLKDIV returns to its power-on -//! value, the console turns to garbage mid-sentence, and the board takes a watchdog reset with -//! nothing readable left to explain it. Everything here touches FIFO offset 0x000 and the status -//! register, and nothing else. - -const hal = @import("hal"); -const input_rescue = @import("input_rescue.zig"); - -/// UART0: the instance the CH340 is wired to, and the one the ROM and bootloader configured. -const uart0 = hal.uart.Uart.init(0); - -/// Keystrokes taken off the receiver while the transmitter was full. See `input_rescue`: without -/// this, anything typed into a frame longer than the 128-byte FIFO was silently gone. -var rescued: input_rescue.Ring = .{}; - -/// Push `bytes` into the TX FIFO, blocking while it is full. -/// -/// The spin is normally bounded by the wire - a full 128-byte FIFO drains in 11 ms at 115200 - and -/// dropping instead of waiting would truncate an escape sequence, leaving the host terminal in the -/// wrong colour for the rest of the session. So the wait is real backpressure. -/// -/// But it is BOUNDED, for the reason `hal/uart.zig:182-186` gives about `update()`: a UART whose -/// core clock has been gated never makes progress, and "on a board with no debugger an infinite -/// spin is indistinguishable from a crash". That is not hypothetical here - it is how this port -/// spent an afternoon: output stopped mid-boot with no panic and no watchdog (the RTC watchdog -/// having been correctly disabled), which looked like a hang in whatever code came next rather than -/// a stalled transmitter. A bounded wait turns that into visibly dropped output plus a counter, -/// which is a diagnosis instead of a mystery. -/// -/// The limit is per burst, not per call, and generous: 1,000,000 status reads is far longer than -/// any legitimate drain and still a fraction of a second. -pub fn write(bytes: []const u8) void { - dropped +%= input_rescue.pump(uart0, &rescued, bytes, 1_000_000); -} - -/// Bytes abandoned because the transmitter stopped making progress. Nonzero means the console is -/// lying about what happened, so it is worth printing. -pub var dropped: u32 = 0; - -/// One byte, for callers that must not touch `.rodata` to say anything - which during bring-up is -/// the difference between a diagnostic and a second copy of the bug being diagnosed. -pub fn writeByte(b: u8) void { - var spins: u32 = 0; - while (uart0.txFree() == 0) { - spins += 1; - if (spins > 1_000_000) { - dropped +%= 1; - return; - } - } - uart0.pushByte(b); -} - -/// Emit `n` bytes read from `addr` as two hex digits each, computing the digits arithmetically so -/// nothing here reads a lookup table. Used to answer "does a load from this address return what the -/// linker put there", which is not a question a string literal can be trusted to ask. -pub fn dumpHex(addr: u32, n: u32) void { - const p: [*]const volatile u8 = @ptrFromInt(addr); - var i: u32 = 0; - while (i < n) : (i += 1) { - const byte = p[i]; - for ([2]u8{ byte >> 4, byte & 0xf }) |nib| { - writeByte(if (nib < 10) '0' + nib else 'a' + (nib - 10)); - } - } - writeByte('\r'); - writeByte('\n'); -} - -/// A u32 as eight hex digits, reading no memory at all. -pub fn dumpWord(v: u32) void { - var shift: u5 = 28; - while (true) { - const nib: u8 = @intCast((v >> shift) & 0xf); - writeByte(if (nib < 10) '0' + nib else 'a' + (nib - 10)); - if (shift == 0) break; - shift -= 4; - } - writeByte('\r'); - writeByte('\n'); -} - -/// Move whatever the host has sent into `buf`, without waiting. Returns the count. -/// -/// Non-blocking on purpose: the loop has a frame to render and a core to pump, and the editor must -/// not stall on a keystroke that may never come. `rxCount` is read once per call and the FIFO -/// drained to that mark, so a fast typist or a pasted buffer cannot hold the loop here. -pub fn read(buf: []u8) usize { - // RESCUED BYTES FIRST. They arrived before anything still sitting in the FIFO, and an editor - // that reorders keystrokes is worse than one that drops them. - var n = rescued.pop(buf); - const waiting = @min(uart0.rxCount(), buf.len - n); - for (buf[n..][0..waiting]) |*slot| slot.* = uart0.popByte(); - n += waiting; - return n; -} - -/// Take whatever has arrived off the receiver right now, without waiting and without handing it to -/// anyone. For callers that are about to spend a while not reading: `write` does this while the -/// transmitter is full, and the loop does it between chunks of input, because applying a keystroke -/// gets more expensive as the line grows and 128 bytes of FIFO is only 11 ms at 115200. -pub fn rescueNow() void { - input_rescue.rescue(uart0, &rescued); -} - -/// Input abandoned because even the rescue buffer overflowed. Distinct from `dropped`, which is -/// OUTPUT abandoned by a stalled transmitter. -pub fn inputDropped() u32 { - return rescued.dropped; -} - -/// Discard anything already received, returning how much. Used once at startup: the host-side -/// bridge injects a window-size report before this program exists, and the bootloader's chatter has -/// already been echoed at the host. Neither is user input. -/// -/// Pops rather than calling `resetRxFifo`, which is a CONF0_SYNC read-modify-write plus two commits -/// on the console UART - see this file's header. -pub fn drainInput() u32 { - var discarded: u32 = 0; - while (uart0.rxCount() > 0) : (discarded += 1) _ = uart0.popByte(); - discarded += @intCast(rescued.len); - rescued.clear(); - return discarded; -} - -/// The rate the hardware is actually producing, by reading its dividers back. Reported rather than -/// assumed: the host has to be opened at the same rate, and a mismatch shows up as garbage on the -/// screen rather than as an error anyone can act on. -pub fn baudrate() u32 { - return uart0.baudrate(uart0.clockSource().nominalHz()); -} diff --git a/tools/bench_main.zig b/tools/bench_main.zig index 973c004..f1932d9 100644 --- a/tools/bench_main.zig +++ b/tools/bench_main.zig @@ -990,7 +990,8 @@ fn check(port: *serial.Port, o: Options, r: *Report) !void { if (!alternates) failures += 1; // A BURST IS NOT CHECKED HERE, deliberately. The bug it would cover - input lost while the - // transmitter was full - has a deterministic host test in `src/pardes/input_rescue.zig` that + // transmitter was full - has a deterministic host test in the editor's own + // `../02-pardes-code/src/esp32p4/input_rescue.zig`, run by its `zig build unit-test`, which // loses 67 bytes with the rescue removed and needs no board at all. Every hardware oracle for it // that was tried here was worse than that: the cursor stops being reported past 160 characters // because the wrapped line outgrows the viewport, and a screen reconstruction cannot be rebuilt -- cgit v1.3