//! A complete ESP32-P4 toolchain in one build graph.
//!
//!   zig build            compile, link, and emit a flashable image
//!   zig build flash      the above, then write it to the chip over the serial port
//!   zig build monitor    open the console
//!   zig build console    attach an interactive terminal: keystrokes in, screen out
//!   zig build size       print where every byte of the image went
//!
//! There is no CMake, no ninja, no idf.py, no esptool and no external linker: Zig's own LLD does
//! 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");
// `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;
    const led_pin = b.option(u8, "led", "GPIO to blink, 0-31 (default 20 = JP1 pin 17)") orelse 20;
    if (led_pin > 31) {
        std.log.err(
            "-Dled={d}: src/soc.zig models GPIO0-31; GPIO32-56 need the OUT1/ENABLE1/IN1 bank",
            .{led_pin},
        );
        std.process.exit(1);
    }
    const app_offset = b.option(u32, "offset", "flash offset of the app partition (default 0x10000)") orelse 0x10000;
    const flash_size = b.option(image.FlashSize, "flash-size", "fitted flash (default 16MB)") orelse .@"16MB";
    const min_rev = b.option(u16, "min-rev", "minimum silicon revision, major*100+minor (default 100)") orelse 100;
    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=../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);
    // ReleaseSmall by default: this is firmware, and `standardOptimizeOption` would otherwise
    // hand out Debug builds - which for this target means panic machinery and formatting code
    // linked into a 500-byte image.
    const optimize = b.option(std.builtin.OptimizeMode, "optimize", "optimize mode (default ReleaseSmall)") orelse .ReleaseSmall;

    const target = chipTarget(b);

    // ---------------------------------------------------------------- the chip's registers
    // Every peripheral register of the P4, taken from ESP-IDF's own `*_reg.h` headers by
    // `zig translate-c`. There is no generator and no checked-in generated file: the C front end
    // does the work, so the addresses, shifts and masks in Zig are not a re-derivation of IDF's
    // numbers, they *are* IDF's numbers. 94 headers -> 86,253 constants in about 0.26 s, and
    // importing the module costs ~0.16 s because Zig only analyses the handful of decls used.
    //
    // `*_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.
    //
    // 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). `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.
    const oracle = b.option(bool, "oracle", "link ESP-IDF's LL functions in as the differential reference") orelse false;
    // `-Dhosted` links ESP-Hosted's transport C into the image, on top of this project's Zig
    // runtime and SDIO driver. The P4 has no radio: the ESP32-C6 beside it does, and it speaks a
    // protocol whose host half is 13,000 lines of already-debugged C. Reimplementing that before
    // anything can reach the network would be the wrong order, so it is linked in and replaced from
    // the bottom up - exactly as -Doracle links IDF's LL beside the HAL.
    //
    // Off by default: it needs an IDF checkout, and a managed_components tree from the sibling
    // 02-esp32p4-m3-radio project.
    const hosted = b.option(bool, "hosted", "link ESP-Hosted's SDIO transport C in, for the radio path") orelse false;
    // Wi-Fi credentials arrive as build options, never as source. This keeps the passphrase out of
    // the tree and out of git. It does end up in the image - unavoidable for a device that has to
    // join a network - but nothing here writes it to a file or prints it.
    const wifi_ssid = b.option([]const u8, "ssid", "Wi-Fi SSID to join (hosted builds)") orelse "";
    const wifi_psk_opt = b.option([]const u8, "psk", "Wi-Fi passphrase; prefer -Dpsk-file") orelse "";
    // 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");

    // ---------------------------------------------------------------- the application
    // 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".
    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
    // image behaves, and because 90 is what every measurement in experiments/ was taken against.
    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", .{});

    // 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,
        .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. 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(.{
            .root_source_file = if (std.fs.path.isAbsolute(app_source))
                .{ .cwd_relative = app_source }
            else
                b.path(app_source),
            .target = target,
            .optimize = optimize,
            .strip = true,
            .single_threaded = true,
            .unwind_tables = .none,
            .omit_frame_pointer = true,
            .error_tracing = false,
            .imports = &.{
                .{ .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.
                .{ .name = "perfproto", .module = b.createModule(.{
                    .root_source_file = b.path("tools/perfproto.zig"),
                    .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 },
            },
        }),
    });
    if (oracle) {
        // IDF's LL compiled into this very image, as the reference half of the differential.
        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(.{
            .root_source_file = b.path("src/oracle/all.zig"),
            .target = target,
            .optimize = optimize,
            .imports = &.{
                .{ .name = "hal", .module = fw.hal },
                .{ .name = "regs", .module = fw.regs },
                .{ .name = "mmio", .module = fw.mmio },
            },
        });
        app.root_module.addImport("oracle", oracle_mod);
    }

    // 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")` (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:
        //
        //   * std/Build.zig:2091 evaluates `mem.eql(u8, decl.name, pkg_hash)` over the whole
        //     dependency table at comptime, and the enlarged table exceeds the 1000 backwards
        //     branch quota. It is reached from ghostty's own build (SharedDeps.zig:874 calls
        //     `b.lazyImport`), which is not lazy in pardes's manifest and so is always compiled.
        //   * pardes's package cache holds seven tree_sitter versions, and the stale ones use
        //     `Compile.addCSourceFile`/`linkLibrary`, removed in Zig 0.16. Nesting made them
        //     reachable and their build.zig files failed to compile.
        //
        // 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'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-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
        // directories and the second one silently links whatever the first one left behind - which is
        // exactly the shape of mistake that ends with a firmware whose grid does not match the
        // firmware you think you flashed.
        //
        // Implemented as a nested `zig build`, not a package dependency, for the reasons above: the
        // seam between these repositories is a file, and it stays a file. This only reaches across it
        // to ask for the file to be made a particular way. Skipped entirely when `-Dpardes-obj` names
        // an object explicitly, because then the caller has said which one they want.
        const cols = b.option(u16, "cols", "board grid width in cells; rebuilds pardes's object");
        const rows = b.option(u16, "rows", "board grid height in cells; rebuilds pardes's object");
        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=esp32p4" });
            build_editor.setCwd(.{ .cwd_relative = editor_dir });
            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.
            build_editor.has_side_effects = true;
            app.step.dependOn(&build_editor.step);
        }

        app.root_module.addObjectFile(if (std.fs.path.isAbsolute(obj))
            .{ .cwd_relative = obj }
        else
            b.path(obj));
    }

    if (hosted) {
        // The Zig half: the port table, the libc surface and the IP stack.
        //
        // A plain module, NOT an `addObject` like appdesc. The object route looks tempting - these
        // files exist to define exported C symbols, and appdesc is an object for exactly that
        // reason - but it is wrong here and fails loudly: an object gets its own copy of every
        // module it imports, so `hal` and `io` end up compiled into both net.o and the executable,
        // and the link dies on duplicate `trapEntry`, `intrDispatch`, `intrFault`, `g_h` and
        // `g_hosted_osi_funcs`.
        //
        // A module is safe here for a reason appdesc could not rely on: a hosted application has to
        // call `net.init(io, gpa)` to bring the radio up, so the module is genuinely referenced and
        // its exports are emitted. appdesc had nothing referencing it at all.
        const net_mod = b.createModule(.{
            .root_source_file = b.path("src/net/all.zig"),
            .target = target,
            .optimize = optimize,
            .single_threaded = true,
            .imports = &.{
                .{ .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, fw.idf_path);
    }
    // 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;

    // 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.
    const elf_only = b.addInstallArtifact(app, .{});
    b.step("elf", "build and install just the ELF, skipping the image").dependOn(&elf_only.step);
    if (b.option(bool, "elf", "also install the ELF (default false)") orelse false)
        b.getInstallStep().dependOn(&elf_only.step);

    // ---------------------------------------------------------------- ELF -> image
    const img = ImageStep.create(b, app, .{
        .chip = .esp32p4,
        .min_rev_full = min_rev,
        .max_rev_full = max_rev,
        .flash_size = flash_size,
        .flash_offset = app_offset,
    });
    b.getInstallStep().dependOn(&b.addInstallBinFile(img.getOutput(), "app.bin").step);

    // ---------------------------------------------------------------- flash / monitor / size
    const flash = FlashStep.create(b, img, .{
        .port = port_path,
        .baud = baud,
        .verify = b.option(bool, "verify", "ask the ROM for an MD5 of what it stored (default true)") orelse true,
        .opts = img.opts,
    });
    b.step("flash", "write the image to the chip and run it").dependOn(&flash.step);

    const monitor_seconds = b.option(u32, "seconds", "monitor duration (default 5)") orelse 5;
    const mon = MonitorStep.create(b, port_path, monitor_seconds);
    b.step("monitor", "reset the board and print its console output").dependOn(&mon.step);

    // `zig build flash monitor` names two independent steps, and the runner may start either
    // first - in practice monitor wins and prints the *old* firmware. This one is ordered.
    const run_mon = MonitorStep.create(b, port_path, monitor_seconds);
    run_mon.step.dependOn(&flash.step);
    b.step("run", "flash the image, then print its console output").dependOn(&run_mon.step);

    // The interactive counterpart of `monitor`. `monitor` prints for N seconds and sends nothing,
    // which is right for an application that only reports; an application the human drives needs
    // the keyboard on the wire. `-Dconsole-baud` is separate from `-Dbaud` because they are
    // genuinely different rates: the flasher's rate is negotiated by the ROM loader's SYNC
    // auto-detect, while the console's is whatever the running firmware programmed into UART0.
    const console_baud = b.option(
        serial.Baud,
        "console-baud",
        "interactive console baud (default 115200, the rate the bootloader leaves UART0 at)",
    ) orelse .b115200;

    // 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(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(&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(tools.console);
    run_con.addArgs(con_args);
    run_con.stdio = .inherit;
    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);

    const bench = b.addRunArtifact(tools.bench);
    bench.addArgs(&.{ "--port", port_path });
    bench.stdio = .inherit;
    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=../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("../02-pardes-code/src/esp32p4/selftest.zig"),
            .target = target,
            .optimize = optimize,
            .strip = true,
            .single_threaded = true,
            .unwind_tables = .none,
            .omit_frame_pointer = true,
            .error_tracing = false,
            .imports = &.{
                .{ .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("../02-pardes-code/src/esp32p4/input_rescue.zig"),
                    .target = target,
                    .optimize = optimize,
                    .single_threaded = true,
                }) },
            },
        }),
    });
    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,
        .baud = flash.baud,
        .verify = flash.verify,
        .opts = img.opts,
    });
    const selftest_run = SelftestStep.create(b, port_path, 20);
    selftest_run.step.dependOn(&selftest_flash.step);
    b.step("selftest", "flash the on-die test suite, run it, and fail the build if any check fails")
        .dependOn(&selftest_run.step);
    b.step("bench", "measure the serial link: verified throughput each way, and latency")
        .dependOn(&bench.step);

    const reset = ResetStep.create(b, port_path);
    b.step("reset", "reset the board and let the flashed application run").dependOn(&reset.step);

    const size = SizeStep.create(b, img);
    b.step("size", "print the image layout byte by byte").dependOn(&size.step);
    const layout_step = LayoutStep.create(b, app, img.opts);
    b.step("layout", "print the ELF's image segments and the loader's verdict, without building an image")
        .dependOn(&layout_step.step);

    // `zig build diff` - the hardware oracle. Builds the differential harness with ESP-IDF's own LL
    // functions linked in beside ours, flashes it, and prints the comparison. This is the project's
    // real correctness argument for the HAL: not "the tests pass" but "the registers this leaves
    // behind are the registers ESP-IDF leaves behind, measured on the die".
    //
    // It is a separate step rather than part of `test` because it needs the board, and because it
    // needs an ESP-IDF checkout to compile the reference against.
    if (oracle) {
        const diff_mon = MonitorStep.create(b, port_path, monitor_seconds);
        diff_mon.step.dependOn(&flash.step);
        b.step("diff", "flash the differential harness and compare against ESP-IDF's LL on the die")
            .dependOn(&diff_mon.step);
    } else {
        const hint = b.step("diff", "flash the differential harness and compare against ESP-IDF's LL on the die");
        hint.dependOn(&NeedsOracle.create(b).step);
    }

    // Host tests for the image builder: every case is a rule the ROM bootloader enforces.
    const tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("tools/image_test.zig"),
            .target = b.graph.host,
            .optimize = .Debug,
        }),
    });
    const test_step = b.step("test", "run the host tests: image builder, and the register layer's field arithmetic");
    test_step.dependOn(&b.addRunArtifact(tests).step);

    // The typed register layer's arithmetic - masks, shifts, bank splits - is host-testable and
    // worth testing there: a wrong shift is otherwise a silent misconfiguration on the die. These
    // run against the host target, so they exercise mmio.zig without needing the chip's registers.
    const mmio_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/mmio.zig"),
            .target = b.graph.host,
            .optimize = .Debug,
        }),
    });
    test_step.dependOn(&b.addRunArtifact(mmio_tests).step);

    // The console bridge's escape-sequence matcher. `ModeWatch` has to recognise `\x1b[?2048h`
    // split across arbitrary read boundaries, and the naive reset-on-mismatch loses a sequence
    // whose own ESC is the byte that broke the previous match - a bug that would show up on the
    // wire as an editor that never learns the window size. Host-testable, so tested here.
    const console_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("tools/console.zig"),
            .target = b.graph.host,
            .optimize = .Debug,
        }),
    });
    test_step.dependOn(&b.addRunArtifact(console_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
    // boundary - a plain counter would hash identically after losing exactly 256 bytes and the
    // instrument would report a clean run over corrupt data.
    const proto_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("tools/perfproto.zig"),
            .target = b.graph.host,
            .optimize = .Debug,
        }),
    });
    test_step.dependOn(&b.addRunArtifact(proto_tests).step);

    // The radio path's host-testable parts. A wrong checksum, a wrong snprintf, or a scheduler that
    // loses a task is far cheaper to find here than on a board whose only output is a serial line.
    //
    // These need the board-support modules built for the *host*, not for the chip: handing a test
    // the riscv-targeted `hal` crashes the compiler outright rather than reporting a target
    // mismatch. The modules themselves are happy to be built either way - src/mmio.zig computes
    // addresses with @ptrFromInt and never dereferences one at comptime - so a second instance of
    // the same source files is all it takes. Nothing here touches a real register; the tests that
    // must do that run on the die, through examples/halcheck.zig.
    const host_mmio = b.createModule(.{
        .root_source_file = b.path("src/mmio.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
        .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 = fw.regs },
            .{ .name = "mmio", .module = host_mmio },
        },
    });
    const host_soc = b.createModule(.{
        .root_source_file = b.path("src/soc.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
    });
    host_soc.addImport("hal", host_hal);

    for ([_][]const u8{
        "src/net/libc.zig", // the malloc header trick, and snprintf's conversions
        "src/net/ip.zig", // checksums, ARP, DHCP, the TCP state machine
        "src/net/heap.zig", // the allocator behind the port table
        "src/net/hosted_os.zig", // the port table's sync and queue wrappers
        "src/io/p4.zig", // the scheduler, futexes and timers
    }) |path| {
        // Skip quietly if a file has not landed: these are written in parallel, and one missing
        // file should not stop the rest of the suite from running.
        std.Io.Dir.cwd().access(b.graph.io, b.pathFromRoot(path), .{}) catch continue;
        const t = b.addTest(.{
            .root_module = b.createModule(.{
                .root_source_file = b.path(path),
                .target = b.graph.host,
                .optimize = .Debug,
                .imports = &.{
                    .{ .name = "soc", .module = host_soc },
                    .{ .name = "hal", .module = host_hal },
                    .{ .name = "mmio", .module = host_mmio },
                    .{ .name = "regs", .module = fw.regs },
                },
            }),
        });
        test_step.dependOn(&b.addRunArtifact(t).step);
    }
}

// ---------------------------------------------------------------------------- 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/<hash>/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.
///
/// This is the one place the toolchain reads ESP-IDF, and it reads it as *data*: header files, at
/// build time, through the C front end Zig already ships. No IDF program runs, nothing from IDF is
/// linked, and no generated file is committed. What it needs is a checkout to point at.
///
/// `hw_ver1` is the correct register set for a pre-v3 die, which is what this board has (silicon
/// rev v1.3). ESP-IDF makes the same choice the same way: soc/CMakeLists.txt:37-41 selects
/// `register/hw_ver1` when CONFIG_ESP32P4_SELECTS_REV_LESS_V3 is set, and this project's own IDF
/// build resolved to that directory.
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 = resolveIdf(b, idf_opt);

    const reg_dir = b.pathJoin(&.{ idf, "components", "soc", "esp32p4", "register", b.fmt("hw_ver{d}", .{hw_ver}), "soc" });

    // One umbrella translation unit including every peripheral header, listed by reading the
    // directory: a new IDF release that adds a peripheral is picked up without editing this file.
    var names: std.ArrayList([]const u8) = .empty;
    const io = b.graph.io;
    var dir = std.Io.Dir.cwd().openDir(io, reg_dir, .{ .iterate = true }) catch {
        std.log.err(
            \\cannot read the ESP-IDF register headers at
            \\    {s}
            \\This is the only thing the build needs ESP-IDF for - the headers are read as data at
            \\build time; no IDF program runs and nothing from IDF is linked. Point at a checkout:
            \\    zig build -Didf=/path/to/esp-idf
            \\or set IDF_PATH. ESP-IDF v6.0.2 is what this was developed against.
        , .{reg_dir});
        std.process.exit(1);
    };
    defer dir.close(io);
    var it = dir.iterate();
    while (it.next(io) catch null) |entry| {
        // Deliberately not testing `entry.kind`: a `*_reg.h` that is a symlink - ordinary in Nix
        // store paths, Bazel sandboxes and `cp -as` mirrors - was silently dropped from the
        // umbrella. Replacing one header with a symlink to its own content removed all three I2S
        // controllers (600 constants) while the build stayed green and the poison census stayed at
        // exactly 524, because a clean header contributes no poison. The name suffix decides.
        if (entry.kind == .directory or !std.mem.endsWith(u8, entry.name, "_reg.h")) continue;
        names.append(b.allocator, b.dupe(entry.name)) catch @panic("OOM");
    }
    // Directory order is filesystem order. Sorting keeps the generated C - and therefore the
    // translate-c cache key and the module's decl order - stable across machines.
    std.mem.sort([]const u8, names.items, {}, struct {
        fn lt(_: void, x: []const u8, y: []const u8) bool {
            return std.mem.lessThan(u8, x, y);
        }
    }.lt);

    var umbrella: std.ArrayList(u8) = .empty;
    umbrella.appendSlice(b.allocator,
        \\/* GENERATED by build.zig: every ESP32-P4 peripheral register header, in one translation
        \\   unit, for zig translate-c. */
        \\
    ) catch @panic("OOM");
    for (names.items) |n| {
        umbrella.print(b.allocator, "#include \"soc/{s}\"\n", .{n}) catch @panic("OOM");
    }
    // Not a register header, but the other half of the GPIO matrix: 474 peripheral signal indices,
    // which is what a driver routes to a pad. Taking SIG_GPIO_OUT_IDX from here rather than writing
    // 256 in Zig is not pedantry - it is 128 on the ESP32-S3, and the wrong one leaves a pad
    // undriven with no error anywhere.
    umbrella.appendSlice(b.allocator, "#include \"soc/gpio_sig_map.h\"\n") catch @panic("OOM");
    // Six more register headers live in include/soc/ rather than the generated register directory,
    // and they are not minor ones: clic_reg.h is the interrupt controller this chip actually has
    // (the P4 has a CLIC, not a PLIC - soc_caps.h:191 SOC_INT_CLIC_SUPPORTED), interrupt_reg.h
    // carries the per-die threshold selection, and spi_mem/system/hwcrypto are the flash and system
    // blocks. Globbing only the register directory silently omits all of them.
    //
    // They use an older macro-comment form than the generated headers, which matters not at all
    // here: nothing in this toolchain parses those comments, clang does the reading.
    for ([_][]const u8{
        "clic_reg.h",
        "interrupt_reg.h",
        "spi_mem_reg.h",
        "system_reg.h",
        "hwcrypto_reg.h",
        "regi2c_dig_reg.h",
    }) |extra| {
        umbrella.print(b.allocator, "#include \"soc/{s}\"\n", .{extra}) catch @panic("OOM");
    }

    const wf = b.addWriteFiles();
    const umbrella_c = wf.add("esp32p4_regs.c", umbrella.items);

    const tc = b.addTranslateC(.{
        .root_source_file = umbrella_c,
        .target = target,
        .optimize = optimize,
        // Header text only: nothing in the register macros calls a libc function, and this target
        // has no libc to link (`unable to provide libc for target riscv32-freestanding-none`).
        .link_libc = false,
    });

    // The hw_ver the headers came from, as a constant inside the module. It is load-bearing and
    // otherwise invisible: 61 macros keep their name and change their value between hw_ver1 and
    // hw_ver3 (AHB_DMA_INFIFO_CNT_CH0 is bits [7:2] on v1 and [14:8] on v3), so a module built from
    // the wrong header set is silently wrong rather than absent. hal.zig comptime-asserts it.
    tc.defineCMacroRaw(b.fmt("ZIG_P4_HW_VER={d}", .{hw_ver}));
    // soc.h pulls in a few headers that only exist for a hosted target. The register headers
    // themselves need nothing from them, so empty stand-ins are enough and keep the include set to
    // ESP-IDF proper.
    const shims = b.addWriteFiles();
    _ = shims.add("stdlib.h", "#pragma once\n");
    _ = shims.add("string.h", "#pragma once\n");
    _ = shims.add("assert.h", "#pragma once\n#define assert(x) ((void)0)\n");
    tc.addIncludePath(shims.getDirectory());
    for ([_][]const u8{
        "components/soc/include",
        "components/soc/esp32p4/include",
        b.fmt("components/soc/esp32p4/register/hw_ver{d}", .{hw_ver}),
        "components/esp_common/include",
        "components/esp_rom/include",
    }) |rel| {
        tc.addIncludePath(.{ .cwd_relative = b.pathJoin(&.{ idf, rel }) });
    }

    // Six base macros are referenced by IDF's own register headers and defined nowhere in IDF:
    // DMAC, MB, TSENS, RTCLOCKCALI, H264 and H264_DMA. Those 507 register macros are dead in C too
    // - nothing expands them, so nothing notices - and translate-c makes them visible by turning
    // each into a poisoned decl that fails only if a driver names it.
    //
    // IDF reaches those peripherals a different way: through the linker, not a macro.
    // soc/esp32p4/ld/esp32p4.peripherals.ld PROVIDEs 111 instance addresses, and for the 65
    // peripherals that appear in both that file and reg_base.h the two agree on all 65. That makes
    // it a sound source for the missing three that are in scope here.
    //
    // H264 and H264_DMA stay unavailable on purpose (video encode is out of scope) and
    // RTCLOCKCALI is absent from both files, so its 21 registers stay unreachable rather than
    // reachable at a guessed address.
    for ([_][]const u8{
        "DR_REG_DMAC_BASE=0x50081000", // ld: DW_GDMA - the AXI general-purpose DMA
        "DR_REG_MB_BASE=0x50118000", // ld: LP_MAILBOX - LP<->HP mailbox
        "DR_REG_TSENS_BASE=0x5012f000", // ld: LP_TSENS - temperature sensor
    }) |def| {
        tc.defineCMacroRaw(def);
    }

    // translate-c exits 0 with empty stderr and still emits `pub const X = @compileError(...)` for
    // every macro it could not translate. Those are invisible until a driver names one, months
    // later, with a message that blames Zig for an ESP-IDF header bug. So count them and fail the
    // build if the number grows: the current 524 are accounted for, and a 525th means either a new
    // IDF release broke something or an include path was lost.
    const census = PoisonCensus.create(b, tc.getOutput(), 524);
    return .{ .mod = tc.createModule(), .census = &census.step, .idf_path = idf, .hw_ver = hw_ver };
}

/// Counts the poisoned declarations in the translated register module and fails if there are more
/// than expected.
///
/// Composition of the 524 expected today, all of them harmless *here* and none of them ours:
///   * 333 `*_REG` addresses whose `DR_REG_*_BASE` ESP-IDF references but never defines. 308 are
///     H264 and H264_DMA (video encode, out of scope) and 21 are RTCLOCKCALI, which is absent from
///     both reg_base.h and peripherals.ld, so there is no honest address to supply.
///   * 153 `_M` pre-shifted masks that are broken C inside ESP-IDF: interrupt_core0_reg.h writes
///     `(CORE0_x_V << CORE0_x_S)` for `INTERRUPT_CORE0_x_M`, dropping the prefix, and spi_mem_c
///     does the same with `SPI_XTS_PLAIN_V`. Nothing in C expands them, so nobody noticed. This
///     toolchain builds every field from the `_S`/`_V` pair and never from `_M`, which is why all
///     153 sit in code it cannot reach - and mmio.Field.of rejects a pre-shifted mask at comptime
///     if one is ever passed by hand.
///   * 38 function-like or compiler-predefined macros (`REG_WRITE`, `ESP_STATIC_ASSERT`,
///     `__UINT32_C_SUFFIX__`), which have Zig equivalents in mmio.zig.
const PoisonCensus = struct {
    step: std.Build.Step,
    zig_file: std.Build.LazyPath,
    budget: usize,

    fn create(b: *std.Build, zig_file: std.Build.LazyPath, budget: usize) *PoisonCensus {
        const self = b.allocator.create(PoisonCensus) catch @panic("OOM");
        self.* = .{
            .step = std.Build.Step.init(.{
                .id = .custom,
                .name = "register poison census",
                .owner = b,
                .makeFn = make,
            }),
            .zig_file = zig_file,
            .budget = budget,
        };
        zig_file.addStepDependencies(&self.step);
        return self;
    }

    fn make(step: *std.Build.Step, options: std.Build.Step.MakeOptions) anyerror!void {
        const self: *PoisonCensus = @fieldParentPtr("step", step);
        const b = step.owner;
        const io = b.graph.io;
        const gpa = options.gpa;

        const path = self.zig_file.getPath2(b, step);
        const text = std.Io.Dir.cwd().readFileAlloc(io, path, gpa, .limited(64 << 20)) catch |err|
            return step.fail("unable to read the translated registers at {s}: {s}", .{ path, @errorName(err) });
        defer gpa.free(text);

        const found = std.mem.count(u8, text, "@compileError");
        if (found > self.budget) {
            return step.fail(
                \\the translated register module has {d} untranslatable macros, expected at most {d}.
                \\Each one is a `pub const X = @compileError(...)` that compiles fine until a driver
                \\names it. Find the new ones with:
                \\    grep -n '@compileError' {s}
                \\A likely cause is a lost include path or an ESP-IDF version whose headers moved.
            , .{ found, self.budget, path });
        }
        if (found < self.budget) {
            std.log.info(
                "register poison census: {d} untranslatable macros, below the expected {d} - tighten the budget in build.zig",
                .{ found, self.budget },
            );
        }
    }
};

/// ESP-Hosted's SDIO transport C, compiled into this image on top of this project's Zig runtime.
///
/// The P4 has no radio. The ESP32-C6 on this board does, and the host half of the protocol between
/// them is ~13,000 lines of C that already works. This function compiles the SDIO path of that C
/// with Zig's clang, for this target, so the Zig side can be built underneath it and the C replaced
/// layer by layer - with the C still linked in as the differential reference, the same way
/// `idfReference` above keeps IDF's LL beside the HAL.
///
/// Every decision here was measured, not guessed. 31 of ESP-Hosted's 43 host sources compile under
/// these flags (the 12 that do not are the SPI and UART transports, which this board does not use,
/// plus protobuf-c's own test files). Linking just the SDIO set leaves 26 undefined symbols, which
/// is the entire cost of the reuse: src/net/libc.zig covers the libc ones, src/net/port.zig
/// defines `g_h`, and src/net/hosted_glue.zig covers logging and the upper-layer hooks.
fn hostedC(b: *std.Build, mod: *std.Build.Module, idf: []const u8) void {
    const io = b.graph.io;

    // The managed_components tree lives in the sibling project that proved this C on this board.
    // Not vendored: it is 19,000 lines of someone else's code, it is pinned by that project's
    // dependency lock, and copying it would make the provenance of the sdkconfig checked in here
    // a lie.
    const mc_root = b.pathJoin(&.{ b.pathFromRoot(".."), "02-esp32p4-m3-radio" });
    {
        var probe = std.Io.Dir.cwd().openDir(io, b.pathJoin(&.{ mc_root, "managed_components" }), .{}) catch {
            std.debug.print(
                \\-Dhosted needs the ESP-Hosted component from the sibling radio project:
                \\  {s}/managed_components/espressif__esp_hosted
                \\That tree is created by `idf.py build` in 02-esp32p4-m3-radio, which is also where
                \\the checked-in src/net/hosted/sdkconfig.h came from.
                \\
            , .{mc_root});
            @panic("ESP-Hosted component not found");
        };
        probe.close(io);
    }
    const hosted_root = b.pathJoin(&.{ mc_root, "managed_components", "espressif__esp_hosted" });

    // Include order is ESP-IDF's own, taken from the compile_commands.json of the build that
    // worked, and it matters: esp_wifi_remote's `injected` directory has to precede
    // components/esp_wifi/include, because a host with no radio needs the injected Wi-Fi types
    // rather than the real ones. See src/net/hosted/include_dirs.txt for the provenance note.
    {
        const list = std.Io.Dir.cwd().readFileAlloc(
            io,
            b.pathFromRoot("src/net/hosted/include_dirs.txt"),
            b.allocator,
            .limited(1 << 20),
        ) catch @panic("src/net/hosted/include_dirs.txt is missing");
        var lines = std.mem.tokenizeScalar(u8, list, '\n');
        while (lines.next()) |raw| {
            const line = std.mem.trim(u8, raw, " \t\r");
            if (line.len == 0 or line[0] == '#') continue;
            const abs = if (std.mem.startsWith(u8, line, "IDF/"))
                b.pathJoin(&.{ idf, line["IDF/".len..] })
            else if (std.mem.startsWith(u8, line, "MC/"))
                b.pathJoin(&.{ mc_root, line["MC/".len..] })
            else
                @panic("include_dirs.txt: every line must start with IDF/ or MC/");
            mod.addIncludePath(.{ .cwd_relative = abs });
        }
    }

    // Our own Kconfig surface and the two compile-time assertion files.
    mod.addIncludePath(b.path("src/net/hosted"));

    // libc *declarations* from Zig's own bundled musl headers. This is the alternative to a pile of
    // hand-written stubs: real prototypes, real errno values, real sys/queue.h, and no drift. The
    // few symbols actually referenced come from the P4 mask ROM, compiler_rt and src/net/libc.zig -
    // nothing links a libc. Resolved through the Zig installation rather than hardcoded, so this
    // survives a toolchain move.
    const zig_lib = b.graph.zig_lib_directory.path orelse
        @panic("cannot locate the Zig lib directory for the bundled libc headers");
    for ([_][]const u8{ "riscv32-linux-musl", "generic-musl", "any-linux-any" }) |flavour| {
        mod.addIncludePath(.{ .cwd_relative = b.pathJoin(&.{ zig_lib, "libc", "include", flavour }) });
    }

    // Four headers musl does not have and IDF or ESP-Hosted expects. Each is here for one named
    // reason, and none of them invents a declaration.
    const shims = b.addWriteFiles();
    // `sys/queue.h` is the BSD linked-list macros. musl has no such header; ESP-Hosted's
    // common/mempool/include/mempool.h:12 includes it, and every transport source reaches it
    // through that. Zig does bundle a copy for glibc targets, so this forwards to exactly that one
    // file by absolute path. Putting glibc's whole include directory on the path would work too and
    // would be a trap: it would shadow musl's headers wholesale and mix two libcs' declarations.
    _ = shims.add("sys/queue.h", b.fmt(
        \\#pragma once
        \\/* Generated by build.zig. The BSD queue macros, from Zig's bundled glibc headers -
        \\   musl has no sys/queue.h, and mempool.h needs one. Pure macros: nothing is linked. */
        \\#include "{s}"
        \\
    , .{b.pathJoin(&.{ zig_lib, "libc", "include", "generic-glibc", "sys", "queue.h" })}));
    _ = shims.add("esp_newlib.h",
        \\#pragma once
        \\/* FreeRTOS's riscv portmacro.h:76 includes this for newlib re-entrancy hooks. This image
        \\   has no newlib runtime, so nothing is declared. */
        \\
    );
    _ = shims.add("sys/features.h",
        \\#pragma once
        \\/* A newlib feature-test header. IDF's platform_include wrappers include it by name; the
        \\   musl headers underneath supply the real declarations. */
        \\
    );
    _ = shims.add("machine/endian.h",
        \\#pragma once
        \\/* newlib puts the byte-order macros here and esp_netif_ip_addr.h:11 includes that path.
        \\   riscv32 is little-endian. */
        \\#define _LITTLE_ENDIAN 1234
        \\#define _BIG_ENDIAN    4321
        \\#define _PDP_ENDIAN    3412
        \\#define _BYTE_ORDER    _LITTLE_ENDIAN
        \\#define LITTLE_ENDIAN  _LITTLE_ENDIAN
        \\#define BIG_ENDIAN     _BIG_ENDIAN
        \\#define BYTE_ORDER     _BYTE_ORDER
        \\
    );
    mod.addIncludePath(shims.getDirectory());

    // The SDIO path, and nothing else. Named one by one rather than globbed: the SPI, SPI-half-
    // duplex and UART transports are in the same tree and compile, and pulling them in would link
    // three unused transports and their symbol demands into a 128 KB image.
    const sources = [_][]const u8{
        // The transport state machine and its helpers.
        "host/drivers/transport/transport_drv.c",
        "host/drivers/transport/transport_util.c",
        "host/drivers/transport/sdio/sdio_drv.c",
        // common/mempool/mempool.c is deliberately NOT here. Its backend is NimBLE's os_mempool -
        // MYNEWT_VAL and struct os_mempool - so the file only compiles in a build that carries the
        // NimBLE host, which is why the IDF project this came from had NimBLE enabled. Bluetooth and
        // the pool are both off (src/net/hosted/sdkconfig.h overrides 2 and 3), and every mempool
        // call site in sdio_drv.c is behind `#if H_USE_MEMPOOL` (:109, :177, :244, :264), so with the
        // pool off there is nothing to link. Buffers come straight from _h_malloc instead.
        // The RPC layer: what carries Wi-Fi association, scanning and everything else the
        // coprocessor does on our behalf. The transport alone gets the two chips talking; this is
        // what gives that conversation vocabulary. Reached at transport_delayed_init -> rpc_start.
        // transport_drv.c:807 calls create_debugging_tasks() unconditionally. This is the vendor's
        // own implementation; with the stats Kconfig options off it spawns nothing, which is the
        // answer we want and one we do not have to write.
        "host/utils/stats.c",
        // The control endpoint the RPC layer talks over: a virtual serial device multiplexed onto
        // the same SDIO transport. transport_drv.c dispatches into serial_ll_rx_handler.
        "host/drivers/serial/serial_ll_if.c",
        "host/drivers/serial/serial_drv.c",
        "host/drivers/virtual_serial_if/serial_if.c",
        "host/drivers/rpc/core/rpc_core.c",
        "host/drivers/rpc/core/rpc_req.c",
        "host/drivers/rpc/core/rpc_rsp.c",
        "host/drivers/rpc/core/rpc_evt.c",
        "host/drivers/rpc/core/rpc_utils.c",
        "host/drivers/rpc/slaveif/rpc_slave_if.c",
        "host/drivers/rpc/wrap/rpc_wrap.c",
        // The wire format underneath it. esp_hosted_rpc.pb-c.c is 33,000 generated lines of
        // protobuf descriptors - almost entirely .rodata, so it costs flash rather than the L2MEM
        // this image is actually short of.
        "common/protobuf-c/protobuf-c/protobuf-c.c",
        "common/proto/esp_hosted_rpc.pb-c.c",
        // Bluetooth, declined. transport_drv.c:126 calls hci_drv_init() unconditionally, and this
        // is ESP-Hosted's own no-op for a host without BT - a real answer from the vendor rather
        // than a stub of ours. Bluetooth is switched off in src/net/hosted/sdkconfig.h, which is
        // what keeps this file from pulling NimBLE in.
        "host/drivers/bt/hci_stub_drv.c",
        // The transport configuration, derived from Kconfig. Compiled rather than transcribed into
        // Zig: the real struct interleaves `gpio_pin_t {void *port; int pin;}` pairs, and a
        // hand-copy of that layout is a silent wrong-pin bug. src/net/hosted/pin_assert.c checks
        // the values these produce against the board.
        "host/api/src/esp_hosted_transport_config.c",
        "host/port/esp/freertos/src/port_esp_hosted_host_transport_defaults.c",
    };

    // The force-include is load-bearing, and this is the single most expensive thing to get wrong
    // in this whole file.
    //
    // `hosted_osi_funcs_t` guards four mempool entries with `#ifdef H_USE_MEMPOOL`
    // (host/esp_hosted_os_abstraction.h:64-69). H_USE_MEMPOOL is *defined* - to 1 or to 0, but
    // always defined - by port_esp_hosted_host_config.h:127-131, and `#ifdef` does not care which.
    // So the struct is four pointers longer in any translation unit that saw that header first.
    // Both host/esp_hosted.h:14 and host/drivers/transport/transport_util.h:10 include
    // esp_hosted_os_abstraction.h as their very first include, so reaching the short layout is
    // easy. Measured with these exact flags:
    //
    //                              sizeof   _h_config_gpio   _h_event_post
    //     without this -include      268          132              264
    //     with this -include         284          148              280
    //
    // A TU with the short layout calling _h_config_gpio jumps through a mempool pointer instead.
    // On a board with no debugger that is a hang whose symptom is indistinguishable from the SDIO
    // bus failing to come up. src/net/hosted/abi_assert.c asserts the long layout so this cannot
    // regress silently.
    const force_include = b.fmt("-include{s}", .{
        b.pathJoin(&.{ hosted_root, "host/port/esp/freertos/include/port_esp_hosted_host_config.h" }),
    });

    const flags = [_][]const u8{
        "-std=gnu17",
        // Same reason as the oracle: IDF's code otherwise pulls in six __ubsan_handle_* symbols
        // that do not exist in a freestanding image.
        "-fno-sanitize=undefined",
        // The reference should be the code as shipped, not a debug build of it.
        "-O2",
        // IDF's build defines this, and ESP-Hosted's config header uses it to decide whether to
        // derive the slave target from Kconfig or from a hand-edited block of #defines. Without it
        // the build fails with "No Slave Target or more than one Slave Target was defined".
        "-DESP_PLATFORM",
        "-DIDF_VER=\"v6.0.2\"",
        // esp_libc/platform_include/stdio.h:46 uses newlib's spelling of off_t for its
        // fopencookie typedefs. musl spells it off_t.
        "-D__off_t=off_t",
        // esp_private/interrupt_clic.h:34 uses newlib's assert.h internals.
        "-D__ASSERT_FUNC=__func__",
        // ESP-Hosted's own code is not this project's to clean up.
        "-Wno-everything",
        force_include,
    };

    for (sources) |rel| mod.addCSourceFile(.{
        .file = .{ .cwd_relative = b.pathJoin(&.{ hosted_root, rel }) },
        .flags = &flags,
    });

    // The Wi-Fi shim: a narrow C surface over the RPC layer, so Zig never transcribes an IDF
    // struct. Compiled with the ESP-Hosted flags because it includes their headers.
    mod.addCSourceFile(.{
        .file = b.path("src/net/hosted/wifi_shim.c"),
        .flags = &flags,
    });

    // The two assertion files. They define nothing anyone calls; they exist so that a Kconfig
    // value drifting from the board, or an include order shifting a struct, fails the build with a
    // sentence instead of hanging the radio.
    for ([_][]const u8{ "pin_assert.c", "abi_assert.c" }) |name| mod.addCSourceFile(.{
        .file = b.path(b.pathJoin(&.{ "src/net/hosted", name })),
        .flags = &flags,
    });
}

/// ESP-IDF's own `*_ll.h` functions, compiled into this image as the differential reference.
///
/// The whole point of the oracle is that both implementations run on the same die, in the same
/// boot, against the same clocks - so IDF's headers have to be *compiled*, by Zig's clang, for the
/// same target. They are, with a 10-file shim and one flag; the details below each cost a debugging
/// round to find, so they are recorded rather than summarised.
fn idfReference(
    b: *std.Build,
    mod: *std.Build.Module,
    idf: []const u8,
    hw_ver: u8,
) void {

    // IDF's LL headers include a handful of hosted-libc headers for types they mostly do not use.
    // Empty stand-ins are enough for all but one line: `assert.h` must define `static_assert`,
    // because esp_assert.h defines ESP_STATIC_ASSERT in terms of it and IDF sprinkles those through
    // the `*_types.h` headers. Without that single line, 16 of the 96 LL headers fail to compile.
    const shims = b.addWriteFiles();
    _ = shims.add("stdlib.h", "#pragma once\ntypedef unsigned int size_t;\n#define NULL ((void *)0)\n");
    _ = shims.add("string.h", "#pragma once\n");
    _ = shims.add("stdio.h", "#pragma once\n");
    _ = shims.add("math.h", "#pragma once\n");
    _ = shims.add("inttypes.h", "#pragma once\n");
    _ = shims.add("sys/param.h", "#pragma once\n");
    _ = shims.add("sys/cdefs.h", "#pragma once\n");
    _ = shims.add("assert.h",
        \\#pragma once
        \\#define assert(x) ((void)0)
        \\/* the load-bearing line: ESP_STATIC_ASSERT expands to this, in 16 headers */
        \\#define static_assert _Static_assert
        \\
    );
    // IDF's headers include "sdkconfig.h" by that exact name. The real content is checked in as
    // src/oracle/oracle_sdkconfig.h, where the name says what it is; this is the bridge.
    _ = shims.add("sdkconfig.h", "#pragma once\n#include \"oracle_sdkconfig.h\"\n");
    mod.addIncludePath(shims.getDirectory());
    // Our own Kconfig surface, checked in next to the reference so it is part of the experiment.
    mod.addIncludePath(b.path("src/oracle"));

    // ESP-IDF v6 split the HAL into one component per peripheral, so a reference for peripheral X
    // needs components/esp_hal_X/{esp32p4/include,include} on the path. Rather than listing them -
    // and editing this file every time the oracle grows - take all of them: there are ~30, they are
    // header-only, and an unused include path costs nothing.
    {
        const io = b.graph.io;
        const comp_path = b.pathJoin(&.{ idf, "components" });
        var dir = std.Io.Dir.cwd().openDir(io, comp_path, .{ .iterate = true }) catch
            @panic("cannot read ESP-IDF components/");
        defer dir.close(io);
        var names: std.ArrayList([]const u8) = .empty;
        var it = dir.iterate();
        while (it.next(io) catch null) |entry| {
            if (entry.kind != .directory or !std.mem.startsWith(u8, entry.name, "esp_hal_")) continue;
            names.append(b.allocator, b.dupe(entry.name)) catch @panic("OOM");
        }
        std.mem.sort([]const u8, names.items, {}, struct {
            fn lt(_: void, x: []const u8, y: []const u8) bool {
                return std.mem.lessThan(u8, x, y);
            }
        }.lt);
        for (names.items) |n| {
            mod.addIncludePath(.{ .cwd_relative = b.pathJoin(&.{ comp_path, n, "esp32p4", "include" }) });
            mod.addIncludePath(.{ .cwd_relative = b.pathJoin(&.{ comp_path, n, "include" }) });
        }
    }

    for ([_][]const u8{
        "components/hal/esp32p4/include",
        "components/hal/include",
        "components/hal/platform_port/include",
        "components/soc/include",
        "components/soc/esp32p4/include",
        b.fmt("components/soc/esp32p4/register/hw_ver{d}", .{hw_ver}),
        "components/esp_common/include",
        "components/esp_rom/include",
        "components/esp_rom/esp32p4/include",
        "components/esp_rom/esp32p4/include/esp32p4",
        "components/riscv/include",
        "components/esp_hw_support/include",
    }) |rel| {
        mod.addIncludePath(.{ .cwd_relative = b.pathJoin(&.{ idf, rel }) });
    }

    // Every reference translation unit in src/oracle. Adding a peripheral to the oracle means
    // adding one `<name>_ref.c` there; this file does not need to know about it.
    var refs: std.ArrayList([]const u8) = .empty;
    {
        const io = b.graph.io;
        var dir = std.Io.Dir.cwd().openDir(io, b.pathFromRoot("src/oracle"), .{ .iterate = true }) catch
            @panic("src/oracle is missing");
        defer dir.close(io);
        var it = dir.iterate();
        while (it.next(io) catch null) |entry| {
            if (entry.kind != .file or !std.mem.endsWith(u8, entry.name, "_ref.c")) continue;
            refs.append(b.allocator, b.dupe(entry.name)) catch @panic("OOM");
        }
        std.mem.sort([]const u8, refs.items, {}, struct {
            fn lt(_: void, x: []const u8, y: []const u8) bool {
                return std.mem.lessThan(u8, x, y);
            }
        }.lt);
    }
    for (refs.items) |name| mod.addCSourceFile(.{
        .file = b.path(b.pathJoin(&.{ "src/oracle", name })),
        .flags = &.{
            "-std=gnu17",
            // Without this, IDF's LL code pulls in six __ubsan_handle_* symbols that have nothing
            // to do with the peripheral and do not exist in a freestanding image.
            "-fno-sanitize=undefined",
            // The reference should be the code IDF ships, not a debug build of it.
            "-O2",
            // gpio_ll.h:588 (`gpio_ll_is_digital_io_hold`) has a path that returns nothing under
            // this chip's `#if`s. It is IDF's bug, in a function nothing here calls, but clang
            // analyses every static inline in a header it parses. Downgrading it is the only way to
            // compile the reference at all, and pretending we could fix IDF here would be worse.
            "-Wno-return-type",
            // Force the Kconfig surface into every reference translation unit. Some IDF headers read
            // CONFIG_* macros without including sdkconfig.h themselves - soc/interrupt_reg.h keys
            // the CLIC threshold mechanism off CONFIG_ESP32P4_SELECTS_REV_LESS_V3 and assumes the
            // includer already has it - so relying on each file to remember is a silent
            // misconfiguration waiting to happen. On this die that particular one decides whether
            // the interrupt threshold is a memory-mapped register or a CSR that does nothing.
            // Absolute path to the checked-in file, not `-include sdkconfig.h`: the bridging header
            // lives in a WriteFiles directory whose name changes with its hash, and a C object cached
            // against the old path fails the build with CacheCheckFailed on the next run.
            b.fmt("-include{s}", .{b.pathFromRoot("src/oracle/oracle_sdkconfig.h")}),
        },
    });
}

/// `zig build diff` without -Doracle would silently flash whatever app is default and compare
/// nothing, so it fails with the command to run instead.
const NeedsOracle = struct {
    step: std.Build.Step,

    fn create(b: *std.Build) *NeedsOracle {
        const self = b.allocator.create(NeedsOracle) catch @panic("OOM");
        self.* = .{ .step = std.Build.Step.init(.{
            .id = .custom,
            .name = "diff needs -Doracle",
            .owner = b,
            .makeFn = make,
        }) };
        return self;
    }

    fn make(step: *std.Build.Step, _: std.Build.Step.MakeOptions) anyerror!void {
        return step.fail(
            \\the differential harness needs ESP-IDF's LL functions linked in as the reference:
            \\    zig build diff -Doracle -Dapp=examples/differ.zig
            \\That compiles ESP-IDF's own *_ll.h into this image with zig cc, so both go on the die
            \\in one boot. It needs an ESP-IDF checkout, via -Didf=<path> or $IDF_PATH.
        , .{});
    }
};

/// ESP-IDF's peripheral instance addresses, as text to splice into the generated linker script.
///
/// IDF's LL code addresses peripherals through struct instances (`GPIO`, `IO_MUX`, `HP_SYS_CLKRST`)
/// which are not C objects at all: esp32p4.peripherals.ld PROVIDEs 111 of them as linker symbols.
fn readPeripheralsLd(b: *std.Build, idf: []const u8) []const u8 {
    const path = b.pathJoin(&.{ idf, "components/soc/esp32p4/ld/esp32p4.peripherals.ld" });
    const text = std.Io.Dir.cwd().readFileAlloc(b.graph.io, path, b.allocator, .limited(256 << 10)) catch {
        std.log.err("cannot read {s}, which the oracle needs for ESP-IDF's peripheral symbols", .{path});
        std.process.exit(1);
    };
    return b.fmt("/* spliced from {s} */\n{s}", .{ path, text });
}

const DescriptorKind = enum { minimal, full };

fn featureSet(features: []const std.Target.riscv.Feature) std.Target.Cpu.Feature.Set {
    var set = std.Target.Cpu.Feature.Set.empty;
    for (features) |f| set.addFeature(@intFromEnum(f));
    return set;
}

/// The eleven ESP-IDF linker scripts, replaced by these twenty lines.
fn linkerScript(b: *std.Build, stack_size: u32, peripherals_ld: ?[]const u8) []const u8 {
    // `peripherals_ld` is the *text* of ESP-IDF's peripherals.ld, not a path, and that is the whole
    // point. An earlier version emitted `INCLUDE "<path>"`: LLD read the file at link time, but only
    // the generated app.ld was a cache input, so the 111 peripheral base addresses the reference
    // half is linked against were untracked. Perturbing GPIO's base in that file and rebuilding
    // produced a byte-identical image - no relink at all - and the reverse was worse: a relink
    // forced for an unrelated reason baked the perturbed address in, and restoring the file left it
    // there under a green build. Splicing the text in makes the content hash the link's cache key,
    // and drops an absolute host path out of a generated artefact.
    return b.fmt(
        \\/* generated by build.zig - do not edit */
        \\ENTRY(_start)
        \\{s}
        \\
        \\/* ESP32-P4 mask ROM entry points, the only "library" this image links against */
        \\ets_printf   = 0x4fc00024;
        \\ets_delay_us = 0x4fc0003c;
        \\/* Recalibrate the ROM's cycles-per-microsecond after a CPU clock change; without it every
        \\   ets_delay_us is wrong by exactly the frequency ratio (esp32p4.rom.ld:32). */
        \\ets_update_cpu_frequency = 0x4fc00044;
        \\/* Invalidate the caches. The bootloader leaves lines that do not match the mapping it
        \\   finally installs, so a large image reads its own .rodata and gets its own .text back. */
        \\Cache_Invalidate_All = 0x4fc00404;
        \\
        \\MEMORY {{
        \\  /* Flash-mapped code and rodata.
        \\
        \\     This was 0xFFE0 - one 64 KiB MMU window - for as long as every application here was a
        \\     few KB, and the comment said the bootloader demands two mapped segments and nothing
        \\     says they may not share a page. Both halves of that are still true; what changed is
        \\     that -Dhosted links ESP-Hosted's transport and RPC layers, and the generated protobuf
        \\     descriptors alone are 33,000 lines of .rodata. One window overflowed by 14,744 bytes.
        \\
        \\     1.5 MiB now, less 32 KiB of slack. It is a *region*, not a reservation: the image
        \\     contains only the sections actually emitted, so a blink app is still ~1.7 KB. The
        \\     ceiling that matters is the factory partition - `zig build monitor` reads it off the
        \\     bootloader's own table as `factory 00010000 00177000` - and the region is deliberately
        \\     set just under it so that an application which outgrows the partition fails at the
        \\     LINK, with a section-overflow naming the section, rather than at the flash write or
        \\     (worse) at boot. Segments still come in the two the loader wants; they simply span
        \\     more than one MMU page now, which the bootloader maps without complaint. */
        \\  flash (rx) : ORIGIN = 0x40000020, LENGTH = 0x170000
        \\
        \\  /* .data/.bss/.stack. This was 0x20000 for as long as nothing needed more.
        \\
        \\     The die was asked (examples/memprobe.zig) rather than the datasheet, because the
        \\     relevant ESP-IDF fragment (esp_system/ld/esp32p4/memory.ld.in:18-33) is parameterised
        \\     on CONFIG_CACHE_L2_CACHE_SIZE, whose Kconfig help says the size is set "on application
        \\     startup" - by an application this is not. Measured, on this rev v1.3 die:
        \\
        \\         0x4FF03000..0x4FF3F000   240 KiB  RAM
        \\         0x4FF3F000..0x4FF40000     4 KiB  the mask ROM's .data/.bss, never written
        \\         0x4FF40000..0x4FFA0000   384 KiB  RAM
        \\         0x4FFA0000..0x4FFC0000   128 KiB  NOT memory - the L2 cache lives here
        \\
        \\     That last line cost a bug worth recording. The first version of the probe wrote a
        \\     pattern and read it back one page at a time, and reported the whole upper 512 KiB as
        \\     RAM - because a store followed immediately by a load of the SAME address returns the
        \\     stored value whether the backing store is real, an address mirror, or merely a dirty
        \\     cache line. Writing every page before reading any page separates the three, and the
        \\     top 128 KiB then failed. It is the L2 cache, and ESP-IDF's own arithmetic agrees
        \\     exactly: SRAM_HIGH_SIZE = 0x80000 - CONFIG_CACHE_L2_CACHE_SIZE, with the Kconfig
        \\     default of 128 KiB (esp_system/port/soc/esp32p4/Kconfig.cache:5,19). Handing those
        \\     128 KiB to an allocator hung the heap on its first free-list walk.
        \\
        \\     This region stops at 0x4FF3F000 because `ets_printf` - the only console this image
        \\     has - reads the ROM statics that begin at 0x4FF3FBA4, and losing them loses the
        \\     ability to report having lost them. */
        \\  l2mem (rw) : ORIGIN = 0x4FF00000, LENGTH = 0x3F000
        \\
        \\  /* The upper RAM, 384 KiB and contiguous, free once the second-stage bootloader has
        \\     jumped away. Nothing is *linked* here: it carries no section, and the two symbols
        \\     below hand it to the application as one span for a run-time heap. Kept out of `l2mem`
        \\     because the ROM's statics sit between the two, and stops at 0x4FFA0000 because the
        \\     L2 cache is above that - see the measurement in `l2mem`'s comment. */
        \\  l2high (rw) : ORIGIN = 0x4FF40000, LENGTH = 0x60000
        \\}}
        \\
        \\/* The heap span, from the linker rather than from a constant in Zig, so the region above is
        \\   the single place these addresses are written down. */
        \\__heap_start = ORIGIN(l2high);
        \\__heap_end   = ORIGIN(l2high) + LENGTH(l2high);
        \\
        \\SECTIONS {{
        \\  /* Two flash-mapped segments, rodata then text, and the split is NOT optional: the
        \\     second-stage bootloader asserts it. On a chip whose D and I external vaddr ranges are
        \\     shared - which the P4's are (soc.h:146-149, both 0x40000000..0x44000000) - ESP-IDF
        \\     takes the `SOC_MMU_DI_VADDR_SHARED` branch of `unpack_load_app`
        \\     (bootloader_utility.c:805-851). That branch does not classify segments as D or I at
        \\     all; it collects them positionally into rom_addr[2] and ends with
        \\
        \\         assert(rom_index == 2);
        \\
        \\     so one mapped segment aborts the boot with
        \\     `Assert failed in unpack_load_app, bootloader_utility.c:842 (rom_index == 2)`, and a
        \\     third trips `assert(rom_index < 2)` inside the loop. Measured, by trying it. */
        \\  .flash.rodata : ALIGN(16) {{
        \\    KEEP(*(.rodata.appdesc))     /* the loader reads esp_app_desc_t at image offset 0x20 */
        \\    *(.rodata .rodata.* .srodata .srodata.*)
        \\    /* Leave the 8 bytes the image builder needs for the next segment's header before the
        \\       boundary .flash.text starts on. ALIGN alone does not guarantee any hole: for one
        \\       rodata length in eight the gap is 0 or 4 bytes and the build dies with
        \\       MappedSegmentsTooClose. */
        \\    . = ALIGN(. + 8, 0x10000) - 8;
        \\  }} > flash
        \\
        \\  /* ALIGN(0x10000), one whole MMU page, and NOT the 64 bytes this used to be.
        \\
        \\     Two mapped segments may share a 64 KiB MMU page only if they also share a flash page,
        \\     which the image builder's anchor guarantees - and that reasoning holds right up until
        \\     an application is large enough for rodata to END inside the page where text BEGINS.
        \\     Measured on the die with a 578 KB image: a volatile read of a string literal at
        \\     0x4004a1d1 returned `37 09 fa 4f`, which disassembles to `lui s2, 0x4ffa0` - this
        \\     image's own .flash.text. Every literal in that shared page read as code, so the first
        \\     thing the firmware tried to print was machine code.
        \\
        \\     Aligning text to a page boundary makes the segments page-disjoint, so no MMU entry is
        \\     ever claimed by both. It costs up to 64 KiB of image padding, which against a 1.5 MiB
        \\     partition is not worth reasoning about - the packing trick this project opened with
        \\     only mattered when the alternative was 64 KiB of zeros in a 1 KB image. */
        \\  .flash.text : ALIGN(0x10000) {{
        \\    *(.text.entry)
        \\    *(.text .text.*)
        \\  }} > flash
        \\
        \\  .data : ALIGN(4) {{ *(.data .data.* .sdata .sdata.*) }} > l2mem
        \\  .bss (NOLOAD) : ALIGN(4) {{
        \\    __bss_start = .;
        \\    *(.bss .bss.* .sbss .sbss.* COMMON)
        \\    __bss_end = .;
        \\  }} > l2mem
        \\  /* ALIGN(16) aligns the section start; __stack_top is start + size, so round that too -
        \\     the RISC-V ABI wants sp 16-byte aligned and -Dstack takes any integer. */
        \\  .stack (NOLOAD) : ALIGN(16) {{ . = ALIGN(. + {d}, 16); __stack_top = .; }} > l2mem
        \\
        \\  /DISCARD/ : {{ *(.eh_frame) *(.eh_frame_hdr) *(.comment) *(.riscv.attributes) }}
        \\}}
        \\
    , .{
        // ESP-IDF's LL code addresses peripherals through struct instances (`GPIO`, `IO_MUX`,
        // `HP_SYS_CLKRST`), which are not C objects at all: soc/esp32p4/ld/esp32p4.peripherals.ld
        // PROVIDEs 111 of them as linker symbols. Pulling that file in with INCLUDE rather than a
        // second -T matters - Zig's driver honours only the last -T given, a limitation this project
        // already ran into once.
        if (peripherals_ld) |text| text else "",
        stack_size,
    });
}

// ---------------------------------------------------------------------------- custom steps
//
// Three steps, each following the same shape the standard steps use (see std/Build/Step/ObjCopy.zig):
// 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;

pub const ImageStep = struct {
    step: std.Build.Step,
    elf: std.Build.LazyPath,
    opts: image.Options,
    basename: []const u8,
    generated: std.Build.GeneratedFile,

    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(.{
                .id = .custom,
                .name = "image",
                .owner = b,
                .makeFn = make,
            }),
            .elf = app.getEmittedBin(),
            .opts = opts,
            .basename = "app.bin",
            .generated = .{ .step = undefined },
        };
        self.generated.step = &self.step;
        self.elf.addStepDependencies(&self.step);
        return self;
    }

    pub fn getOutput(self: *ImageStep) std.Build.LazyPath {
        return .{ .generated = .{ .file = &self.generated } };
    }

    fn make(step: *std.Build.Step, options: std.Build.Step.MakeOptions) anyerror!void {
        const self: *ImageStep = @fieldParentPtr("step", step);
        const b = step.owner;
        const io = b.graph.io;
        const gpa = options.gpa;

        var man = b.graph.cache.obtain();
        defer man.deinit();

        const elf_path = self.elf.getPath2(b, step);
        _ = try man.addFile(elf_path, null);
        // The image builder is part of the input: without these two, editing tools/image.zig gives
        // a cache hit and ships the previous bytes, and `--watch` never notices the edit at all.
        _ = try man.addFile(b.pathFromRoot("tools/image.zig"), null);
        _ = try man.addFile(b.pathFromRoot("build.zig"), null);
        inline for (@typeInfo(image.Options).@"struct".fields) |f| {
            const v = @field(self.opts, f.name);
            man.hash.add(switch (@typeInfo(@TypeOf(v))) {
                .@"enum" => @as(u32, @intFromEnum(v)),
                else => @as(u32, v),
            });
        }

        if (try step.cacheHitAndWatch(&man)) {
            const digest = man.final();
            self.generated.path = try b.cache_root.join(b.allocator, &.{ "o", &digest, self.basename });
            return;
        }

        const digest = man.final();
        const cache_dir = "o" ++ std.fs.path.sep_str ++ digest;
        b.cache_root.handle.createDirPath(io, cache_dir) catch |err|
            return step.fail("unable to make {s}: {s}", .{ cache_dir, @errorName(err) });

        const elf_bytes = std.Io.Dir.cwd().readFileAlloc(io, elf_path, gpa, .limited(8 << 20)) catch |err|
            return step.fail("unable to read {s}: {s}", .{ elf_path, @errorName(err) });
        defer gpa.free(elf_bytes);

        var layout = image.fromElf(gpa, elf_bytes, self.opts) catch |err|
            return step.fail("image build failed: {s}", .{@errorName(err)});
        defer layout.deinit(gpa);

        // Validate before anything is written: a rejected image must never exist on disk under a
        // name the flash step - or a human with esptool - would pick up.
        //
        // The TABLE goes out with the error, and that is not decoration. `NotTwoMappedSegments` says
        // the count is wrong and says nothing about what the segments were, which is the only thing
        // that tells you which section grew, shrank, or stopped being emitted at all. Diagnosing one
        // of these by hand - readelf on an artifact that turned out to be a stale install, then
        // guessing at the linker script - took an hour that this print makes unnecessary. It has to
        // happen here because a rejected image is never written, so no later step can show it.
        layout.validate(self.opts) catch |err| {
            var buf: [4096]u8 = undefined;
            var stderr = std.Io.File.stderr().writer(io, &buf);
            describeLayout(&stderr.interface, layout, self.opts) catch {};
            stderr.interface.flush() catch {};
            return step.fail("image violates a loader rule: {s}", .{@errorName(err)});
        };

        const out_path = try b.cache_root.join(b.allocator, &.{ cache_dir, self.basename });
        std.Io.Dir.cwd().writeFile(io, .{ .sub_path = out_path, .data = layout.bytes }) catch |err|
            return step.fail("unable to write {s}: {s}", .{ out_path, @errorName(err) });

        self.generated.path = out_path;
        try step.writeManifestAndWatch(&man);
    }
};

/// The image's segment table, in one place because three callers want exactly this and disagreeing
/// about it would be its own bug: `size` on an image that built, the failure path above on one the
/// loader rejected, and `layout` on an ELF that never got as far as an image.
///
/// The mapped count is spelled out because it is the subject of the rule that fails most often - the
/// bootloader asserts on exactly two - and counting rows by eye is how you misread it.
fn describeLayout(w: *std.Io.Writer, l: image.Layout, opts: image.Options) !void {
    var mapped: usize = 0;
    var loaded: usize = 0;
    for (l.segments) |s| switch (s.kind) {
        .mapped => mapped += 1,
        else => loaded += 1,
    };
    try w.print("image {d} B = {d} B segments + {d} B overhead, entry 0x{x}\n", .{
        l.bytes.len, l.payload, l.overhead, l.entry,
    });
    var off: usize = 24;
    for (l.segments) |s| {
        const flash = opts.flash_offset + off + 8;
        try w.print("  {s:<6} vaddr=0x{x:0>8} len={d:>6}  flash=0x{x:0>6}{s}\n", .{
            @tagName(s.kind), s.addr, s.len, flash,
            if (s.kind == .mapped and flash % opts.mmu_page == s.addr % opts.mmu_page)
                "  congruent"
            else
                "",
        });
        off += 8 + s.len;
    }
    try w.print("  {d} mapped, {d} loaded", .{ mapped, loaded });
    if (mapped != 2) {
        // The one that bites, and the two ways it happens, because the error name says neither.
        try w.print("  <-- the bootloader asserts on exactly 2 mapped segments.\n", .{});
        try w.print("      .flash.rodata and .flash.text are what produce them; one of them is\n", .{});
        try w.print("      empty or merged. `zig build layout` on the ELF shows which.\n", .{});
    } else try w.print("\n", .{});
    try w.print("  24 B header + {d} B segment headers + checksum pad + 32 B sha256\n", .{l.segments.len * 8});
}

/// `zig build layout` - the segment table for an ELF, WITHOUT validating it.
///
/// `size` cannot do this job: it reads the finished image, so it only runs when the image built, and
/// 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.
pub const LayoutStep = struct {
    step: std.Build.Step,
    elf: std.Build.LazyPath,
    opts: image.Options,

    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 }),
            .elf = app.getEmittedBin(),
            .opts = opts,
        };
        self.elf.addStepDependencies(&self.step);
        return self;
    }

    fn make(step: *std.Build.Step, options: std.Build.Step.MakeOptions) anyerror!void {
        const self: *LayoutStep = @fieldParentPtr("step", step);
        const b = step.owner;
        const io = b.graph.io;
        const gpa = options.gpa;

        const elf_path = self.elf.getPath2(b, step);
        const elf_bytes = std.Io.Dir.cwd().readFileAlloc(io, elf_path, gpa, .limited(8 << 20)) catch |err|
            return step.fail("unable to read {s}: {s}", .{ elf_path, @errorName(err) });
        defer gpa.free(elf_bytes);

        var layout = image.fromElf(gpa, elf_bytes, self.opts) catch |err|
            return step.fail("cannot derive segments from {s}: {s}", .{ elf_path, @errorName(err) });
        defer layout.deinit(gpa);

        var buf: [4096]u8 = undefined;
        var stdout = std.Io.File.stdout().writer(io, &buf);
        const w = &stdout.interface;
        try w.print("{s}\n", .{elf_path});
        try describeLayout(w, layout, self.opts);
        if (layout.validate(self.opts)) |_| {
            try w.print("  verdict: the loader would accept this image\n", .{});
        } else |err| {
            try w.print("  verdict: the loader would REFUSE this image: {s}\n", .{@errorName(err)});
        }
        try w.flush();
    }
};

/// Read a built image back off disk. Both the flash and size steps do exactly this, which is what
/// lets them work on a cache hit, in any order, or on an image from a previous build.
fn readImage(step: *std.Build.Step, gpa: std.mem.Allocator, path: std.Build.LazyPath, opts: image.Options) !image.Layout {
    const b = step.owner;
    const io = b.graph.io;
    const p = path.getPath2(b, step);
    const bytes = std.Io.Dir.cwd().readFileAlloc(io, p, gpa, .limited(4 << 20)) catch |err|
        return step.fail("unable to read {s}: {s}", .{ p, @errorName(err) });
    defer gpa.free(bytes);
    return image.parse(gpa, bytes, opts) catch |err|
        return step.fail("{s} is not a usable image: {s}", .{ p, @errorName(err) });
}

/// Fail a step that could not open the serial port, and for the one error that is always the same
/// mistake, say what to do about it.
///
/// `AccessDenied` is the first thing anyone hits: the device is owned by a group (uucp on Arch,
/// dialout on Debian) and the account is not in it. The subtlety worth printing is the SECOND half -
/// adding the group with `usermod -aG` does not affect any shell that is already running, because
/// credentials are captured at login. That produces exactly this error from a user who has already
/// "fixed" it, which is a genuinely confusing place to be.
fn failPort(step: *std.Build.Step, port: []const u8, err: anyerror) anyerror {
    if (err != error.AccessDenied) return step.fail("cannot open {s}: {s}", .{ port, @errorName(err) });
    return step.fail("cannot open {s}: AccessDenied\n\n" ++ serial.access_denied_help, .{port});
}

pub const FlashStep = struct {
    step: std.Build.Step,
    bin: std.Build.LazyPath,
    opts: image.Options,
    port: []const u8,
    baud: serial.Baud,
    verify: bool,

    pub const Args = struct {
        port: []const u8,
        baud: serial.Baud,
        verify: bool,
        opts: image.Options,
    };

    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 }),
            .bin = img.getOutput(),
            .opts = args.opts,
            .port = args.port,
            .baud = args.baud,
            .verify = args.verify,
        };
        self.bin.addStepDependencies(&self.step);
        return self;
    }

    fn make(step: *std.Build.Step, options: std.Build.Step.MakeOptions) anyerror!void {
        const self: *FlashStep = @fieldParentPtr("step", step);
        const b = step.owner;
        const gpa = options.gpa;

        var layout = try readImage(step, gpa, self.bin, self.opts);
        defer layout.deinit(gpa);

        port_lock.lockUncancelable(b.graph.io);
        defer port_lock.unlock(b.graph.io);

        var port = serial.Port.open(self.port, self.baud) catch |err|
            return failPort(step, self.port, err);
        defer port.close();

        const t_open = port.nowMs();
        port.resetToDownload(.{}) catch |err| return step.fail("reset failed: {s}", .{@errorName(err)});

        var loader = rom.Loader{ .port = &port };
        loader.sync(gpa) catch |err| return step.fail("ROM loader did not answer: {s}", .{@errorName(err)});
        const t_sync = port.nowMs();
        loader.attachFlash(gpa) catch |err| return step.fail("SPI attach failed: {s}", .{@errorName(err)});
        loader.setFlashParams(gpa, self.opts.flash_size.bytes()) catch |err|
            return step.fail("SPI params failed: {s}", .{@errorName(err)});
        const t_setup = port.nowMs();

        loader.writeFlash(gpa, self.opts.flash_offset, layout.bytes) catch |err|
            return step.fail("write failed: {s}", .{@errorName(err)});
        const t_write = port.nowMs();

        // The ROM hashes what it actually stored; compare that with our own digest of what we sent.
        var expect: [16]u8 = undefined;
        std.crypto.hash.Md5.hash(layout.bytes, &expect, .{});
        var expect_hex: [32]u8 = undefined;
        _ = std.fmt.bufPrint(&expect_hex, "{x}", .{&expect}) catch unreachable;
        if (self.verify) {
            var rom_md5: [32]u8 = undefined;
            if (loader.flashMd5(gpa, self.opts.flash_offset, @intCast(layout.bytes.len), &rom_md5)) |_| {
                if (!std.mem.eql(u8, &rom_md5, &expect_hex)) return step.fail(
                    "flash verify failed: the ROM reports {s}, the image is {s}",
                    .{ &rom_md5, &expect_hex },
                );
            } else |err| return step.fail("flash verify failed: {s}", .{@errorName(err)});
        }
        const t_verify = port.nowMs();

        port.resetToRun(.{}) catch {};
        const t_run = port.nowMs();

        var buf: [256]u8 = undefined;
        var stdout = std.Io.File.stdout().writer(b.graph.io, &buf);
        try stdout.interface.print(
            "flashed {d} B at 0x{x} in {d} ms: reset+sync {d}, setup {d}, write {d}, verify {d}, run {d} (md5 {s})\n",
            .{
                layout.bytes.len,   self.opts.flash_offset, t_run - t_open,
                t_sync - t_open,    t_setup - t_sync,       t_write - t_setup,
                t_verify - t_write, t_run - t_verify,       expect_hex[0..16],
            },
        );
        try stdout.interface.flush();
    }
};

pub const MonitorStep = struct {
    step: std.Build.Step,
    port: []const u8,
    seconds: u32,

    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 }),
            .port = port,
            .seconds = seconds,
        };
        return self;
    }

    fn make(step: *std.Build.Step, _: std.Build.Step.MakeOptions) anyerror!void {
        const self: *MonitorStep = @fieldParentPtr("step", step);
        const b = step.owner;

        port_lock.lockUncancelable(b.graph.io);
        defer port_lock.unlock(b.graph.io);

        var port = serial.Port.open(self.port, .b115200) catch |err|
            return failPort(step, self.port, err);
        defer port.close();
        port.resetToRun(.{}) catch {};

        var out_buf: [4096]u8 = undefined;
        var stdout = std.Io.File.stdout().writer(b.graph.io, &out_buf);
        var buf: [1024]u8 = undefined;
        const deadline = port.nowMs() + @as(i64, self.seconds) * 1000;
        while (port.nowMs() < deadline) {
            const n = port.readTimeout(&buf, 200) catch break;
            if (n > 0) {
                try stdout.interface.writeAll(buf[0..n]);
                try stdout.interface.flush();
            }
        }
    }
};

/// 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.
pub const ResetStep = struct {
    step: std.Build.Step,
    port: []const u8,

    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 }),
            .port = port,
        };
        return self;
    }

    fn make(step: *std.Build.Step, _: std.Build.Step.MakeOptions) anyerror!void {
        const self: *ResetStep = @fieldParentPtr("step", step);
        const b = step.owner;
        port_lock.lockUncancelable(b.graph.io);
        defer port_lock.unlock(b.graph.io);
        var port = serial.Port.open(self.port, .b115200) catch |err|
            return failPort(step, self.port, err);
        defer port.close();
        port.resetToRun(.{}) catch |err| return step.fail("reset failed: {s}", .{@errorName(err)});
    }
};

/// `zig build selftest` - run the die's own test suite and make its verdict the build's.
///
/// `monitor` already prints what the board says, so this exists for one reason: an exit code. A
/// suite whose result a human has to read out of a scrolling log is a suite that gets ignored the
/// first busy afternoon, and the whole point of putting tests on the board was that the interesting
/// failures are the ones a host cannot see.
///
/// 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.
pub const SelftestStep = struct {
    step: std.Build.Step,
    port: []const u8,
    seconds: u32,

    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 }),
            .port = port,
            .seconds = seconds,
        };
        return self;
    }

    fn make(step: *std.Build.Step, _: std.Build.Step.MakeOptions) anyerror!void {
        const self: *SelftestStep = @fieldParentPtr("step", step);
        const b = step.owner;

        port_lock.lockUncancelable(b.graph.io);
        defer port_lock.unlock(b.graph.io);

        var port = serial.Port.open(self.port, .b115200) catch |err|
            return failPort(step, self.port, err);
        defer port.close();
        port.resetToRun(.{}) catch {};

        var out_buf: [4096]u8 = undefined;
        var stdout = std.Io.File.stdout().writer(b.graph.io, &out_buf);
        var buf: [1024]u8 = undefined;
        // The summary can straddle a read, so the tail of every read is kept. 128 is far more than
        // the marker needs and costs nothing.
        var tail: [128]u8 = undefined;
        var tail_len: usize = 0;
        const deadline = port.nowMs() + @as(i64, self.seconds) * 1000;

        while (port.nowMs() < deadline) {
            const n = port.readTimeout(&buf, 200) catch break;
            if (n == 0) continue;
            try stdout.interface.writeAll(buf[0..n]);
            try stdout.interface.flush();

            const keep = @min(tail_len, tail.len - @min(n, tail.len));
            if (keep > 0) std.mem.copyForwards(u8, tail[0..keep], tail[tail_len - keep ..][0..keep]);
            const take = @min(n, tail.len - keep);
            @memcpy(tail[keep..][0..take], buf[n - take ..][0..take]);
            tail_len = keep + take;

            if (std.mem.indexOf(u8, tail[0..tail_len], "SELFTEST DONE")) |at| {
                const rest = tail[at..tail_len];
                const fail_at = std.mem.indexOf(u8, rest, "fail=") orelse continue;
                var digits = rest[fail_at + 5 ..];
                var end: usize = 0;
                while (end < digits.len and digits[end] >= '0' and digits[end] <= '9') end += 1;
                if (end == 0) continue;
                const failures = std.fmt.parseInt(u32, digits[0..end], 10) catch continue;
                if (failures != 0) return step.fail("{d} on-board check(s) failed", .{failures});
                return;
            }
        }
        return step.fail(
            "the board never reported a result within {d}s - it did not reach the end of the suite",
            .{self.seconds},
        );
    }
};

pub const SizeStep = struct {
    step: std.Build.Step,
    bin: std.Build.LazyPath,
    opts: image.Options,

    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 }),
            .bin = img.getOutput(),
            .opts = img.opts,
        };
        self.bin.addStepDependencies(&self.step);
        return self;
    }

    fn make(step: *std.Build.Step, options: std.Build.Step.MakeOptions) anyerror!void {
        const self: *SizeStep = @fieldParentPtr("step", step);
        const b = step.owner;
        const gpa = options.gpa;

        var layout = try readImage(step, gpa, self.bin, self.opts);
        defer layout.deinit(gpa);

        var buf: [4096]u8 = undefined;
        var stdout = std.Io.File.stdout().writer(b.graph.io, &buf);
        const w = &stdout.interface;
        try w.print("image {d} B = {d} B segments + {d} B overhead, entry 0x{x}\n", .{
            layout.bytes.len, layout.payload, layout.overhead, layout.entry,
        });
        var off: usize = 24;
        for (layout.segments) |s| {
            const flash = self.opts.flash_offset + off + 8;
            try w.print("  {s:<6} vaddr=0x{x:0>8} len={d:>6}  flash=0x{x:0>6}{s}\n", .{
                @tagName(s.kind), s.addr, s.len, flash,
                if (s.kind == .mapped and flash % self.opts.mmu_page == s.addr % self.opts.mmu_page)
                    "  congruent"
                else
                    "",
            });
            off += 8 + s.len;
        }
        try w.print("  24 B header + {d} B segment headers + checksum pad + 32 B sha256\n", .{layout.segments.len * 8});
        try w.flush();
    }
};