path: root/build.zig

//! 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.

const std = @import("std");
const image = @import("tools/image.zig");
const serial = @import("tools/serial.zig");
const rom = @import("tools/rom.zig");
const console = @import("tools/console.zig");

pub fn build(b: *std.Build) void {
    // ---------------------------------------------------------------- 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=src/pardes/app.zig` because it also resolves the lazy `pardes` dependency and raises
    // the default stack: the core recurses through layout and 8 KiB is not enough for it.
    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 = 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 }),
    });

    // ---------------------------------------------------------------- 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.
    const registers = idfRegisters(b, target, optimize);
    const regs_mod = registers.mod;
    // ---------------------------------------------------------------- generated linker script
    // The layout is a build input, not a checked-in file: change -Dstack or the descriptor size
    // and the script follows. Both flash-mapped sections sit in one 64 KiB MMU window, which is
    // what keeps the image ~1 KB instead of ~66 KB (see tools/image.zig).
    const ld = b.addWriteFiles();
    // 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");
    const ld_script = ld.add("app.ld", linkerScript(
        b,
        stack_size,
        if (oracle) readPeripheralsLd(b, registers.idf_path) else null,
    ));


    // ---------------------------------------------------------------- the application
    const options = b.addOptions();
    options.addOption(u8, "led_pin", led_pin);
    options.addOption(u32, "stack_size", stack_size);
    options.addOption([]const u8, "wifi_ssid", wifi_ssid);
    options.addOption([]const u8, "wifi_psk", if (psk_file) |path| blk: {
        const raw = std.Io.Dir.cwd().readFileAlloc(b.graph.io, path, b.allocator, .limited(256)) catch
            @panic("cannot read the file named by -Dpsk-file");
        break :blk std.mem.trim(u8, raw, " \t\r\n");
    } else wifi_psk_opt);
    options.addOption(bool, "full_descriptor", descriptor == .full);
    options.addOption(u16, "min_rev_full", min_rev);
    options.addOption(u16, "max_rev_full", max_rev);
    const config_mod = options.createModule();

    // The board-support modules are real modules, so an app can live anywhere and still
    // `@import("soc")`. src/ holds one copy of each; examples/ holds none.
    const soc_mod = b.createModule(.{
        .root_source_file = b.path("src/soc.zig"),
        .target = target,
        .optimize = optimize,
    });
    // The whole chip's registers, and the typed layer over them. `hal` is what applications and
    // drivers use; `regs` is the raw translate-c output, exposed so a driver can reach a register
    // the HAL does not model yet without waiting for one to be written.
    const mmio_mod = b.createModule(.{
        .root_source_file = b.path("src/mmio.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{.{ .name = "regs", .module = regs_mod }},
    });
    const hal_mod = b.createModule(.{
        .root_source_file = b.path("src/hal.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{
            .{ .name = "regs", .module = regs_mod },
            .{ .name = "mmio", .module = mmio_mod },
        },
    });
    soc_mod.addImport("hal", hal_mod);
    // The app descriptor is its own translation unit, linked in unconditionally. An application
    // that merely `@import`s it would not do: under ReleaseSmall the import is analysed lazily,
    // nothing forces the constant to be emitted, `.flash.rodata` disappears, and the image ends up
    // with a single mapped segment at the wrong offset. As a separate object with an exported
    // symbol it always exists, and no application has to remember anything.
    const appdesc_obj = b.addObject(.{
        .name = "appdesc",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/appdesc.zig"),
            .target = target,
            .optimize = optimize,
            .imports = &.{.{ .name = "config", .module = config_mod }},
        }),
    });

    // The app root still comes from `-Dapp`, so pointing that at a different shell over the same
    // module stays possible.
    const app_source = b.option([]const u8, "app", "root source file (default src/main.zig, or src/pardes/app.zig under -Dpardes)") orelse
        if (pardes_app) "src/pardes/app.zig" else "src/main.zig";
    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 = config_mod },
                .{ .name = "soc", .module = soc_mod },
                .{ .name = "hal", .module = hal_mod },
                .{ .name = "mmio", .module = mmio_mod },
                .{ .name = "regs", .module = regs_mod },
            },
        }),
    });
    // The census is a gate, not a side effect: nothing may compile against the register module
    // without it having been counted.
    app.step.dependOn(registers.census);
    if (oracle) {
        // IDF's LL compiled into this very image, as the reference half of the differential.
        idfReference(b, app.root_module, registers.idf_path, registers.hw_ver);
        // 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 = hal_mod },
                .{ .name = "regs", .module = regs_mod },
                .{ .name = "mmio", .module = mmio_mod },
            },
        });
        app.root_module.addImport("oracle", oracle_mod);
    }
    // `std.Io` implemented for this chip: a cooperative scheduler, timers off the systimer, and
    // futexes. Its own module rather than a file inside `net`, because Zig confines a module's
    // imports to its root directory - src/net/ cannot reach ../io/ - and because it is useful
    // without the radio: any application wanting tasks and timeouts can import it alone.
    const io_mod = b.createModule(.{
        .root_source_file = b.path("src/io/p4.zig"),
        .target = target,
        .optimize = optimize,
        .single_threaded = true,
        .imports = &.{
            .{ .name = "soc", .module = soc_mod },
            .{ .name = "hal", .module = hal_mod },
            .{ .name = "mmio", .module = mmio_mod },
            .{ .name = "regs", .module = regs_mod },
        },
    });
    app.root_module.addImport("io", io_mod);

    // The general-purpose allocator, its own module for exactly the reason given above for `io`: a
    // module's imports cannot escape its root directory, so neither src/pardes/ nor examples/ can
    // reach src/net/heap.zig as a file. Pointed at the existing file rather than copied - `Heap` is
    // a coalescing free-list over one caller-supplied span and has nothing to do with the radio; it
    // lives under src/net/ only because ESP-Hosted needed it first. The file has zero `export`s, so
    // compiling it into two modules cannot collide.
    //
    // Added unconditionally, like `io`: an application that never imports it costs nothing, because
    // an unreferenced module emits no code.
    const heap_mod = b.createModule(.{
        .root_source_file = b.path("src/net/heap.zig"),
        .target = target,
        .optimize = optimize,
        .single_threaded = true,
    });
    app.root_module.addImport("heap", heap_mod);

    if (pardes_app) {
        // The editor arrives as a linked OBJECT, not as a package dependency, and that is a
        // measurement rather than a preference.
        //
        // The obvious design was `build.zig.zon` with a path dependency on ../02-pardes-code, and
        // `dep.module("pardes_p4")`. It was written, and it broke EVERY build in this repo -
        // `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 keeps having no manifest and no dependencies, the editor's
        // renderer stays next to the vaxis it needs, and the boundary is bytes in / bytes out.
        const obj = b.option([]const u8, "pardes-obj", "path to pardes's p4 object (default ../02-pardes-code/zig-out/pardes-p4.o)") orelse
            "../02-pardes-code/zig-out/pardes-p4.o";
        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 = config_mod },
                .{ .name = "soc", .module = soc_mod },
                .{ .name = "hal", .module = hal_mod },
                .{ .name = "mmio", .module = mmio_mod },
                .{ .name = "regs", .module = regs_mod },
                .{ .name = "io", .module = io_mod },
            },
        });
        app.root_module.addImport("net", net_mod);
        // The C half, compiled against this project's Kconfig surface. It attaches to the
        // executable's own module rather than net's, because the C is linked, not imported.
        hostedC(b, app.root_module, registers.idf_path);
    }
    app.setLinkerScript(ld_script);
    app.entry = .{ .symbol_name = "_start" };
    // The app descriptor must survive --gc-sections even though no code reads it: the bootloader
    // does, at image offset 0x20. Asking the linker for the symbol is what keeps the module alive,
    // regardless of whether the application source happens to mention it.
    app.root_module.addObject(appdesc_obj);
    app.link_gc_sections = true;
    app.link_function_sections = true;
    app.link_data_sections = true;


    // One install step for the ELF, reachable two ways: `zig build elf` on its own (handy when
    // debugging the image builder) and `-Delf` to get it alongside the image.
    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;
    const con = ConsoleStep.create(b, port_path, console_baud);
    b.step("console", "attach an interactive terminal to the running application").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 = ConsoleStep.create(b, port_path, console_baud);
    run_con.step.dependOn(&flash.step);
    b.step("interact", "flash the image, then attach an interactive terminal").dependOn(&run_con.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);

    // `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 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 = regs_mod }},
    });
    const host_hal = b.createModule(.{
        .root_source_file = b.path("src/hal.zig"),
        .target = b.graph.host,
        .optimize = .Debug,
        .imports = &.{
            .{ .name = "regs", .module = regs_mod },
            .{ .name = "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 = regs_mod },
                },
            }),
        });
        test_step.dependOn(&b.addRunArtifact(t).step);
    }
}

/// 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,
) struct { mod: *std.Build.Module, census: *std.Build.Step, idf_path: []const u8, hw_ver: u8 } {
    const idf = b.option([]const u8, "idf", "ESP-IDF checkout, for the register headers (default $IDF_PATH or ~/esp/esp-idf)") orelse
        b.graph.environ_map.get("IDF_PATH") orelse
        b.pathJoin(&.{ b.graph.environ_map.get("HOME") orelse "", "esp", "esp-idf" });
    const hw_ver = b.option(u8, "idf-hw-ver", "register header set: 1 for pre-v3 silicon (default), 3 for v3+") orelse 1;

    const 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;
        \\/* 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.

/// The serial port is one device but `flash` and `monitor` are unordered top-level steps, and the
/// build runner executes independent steps concurrently. Serializing them here turns
/// `zig build flash monitor` from a race into a sequence.
var port_lock: std.Io.Mutex = .init;

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

    fn create(b: *std.Build, app: *std.Build.Step.Compile, opts: image.Options) *ImageStep {
        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;
    }

    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.
        layout.validate(self.opts) catch |err|
            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);
    }
};

/// 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) });
}

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

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

    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 step.fail("cannot open {s}: {s}", .{ self.port, @errorName(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();
    }
};

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

    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 step.fail("cannot open {s}: {s}", .{ self.port, @errorName(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();
            }
        }
    }
};

/// `monitor`, but the wire runs both ways. See tools/console.zig for the size handshake, which is
/// the only part of this that is not a straight byte copy.
///
/// Takes the same `port_lock` as every other step that opens the port, so `zig build flash console`
/// cannot have the console pull the board out of download mode mid-write. It then HOLDS that lock
/// for the whole interactive session, which is correct and worth saying out loud: the session ends
/// when the user detaches, so any other port step named on the same command line waits for the
/// human rather than racing them.
const ConsoleStep = struct {
    step: std.Build.Step,
    port: []const u8,
    baud: serial.Baud,

    fn create(b: *std.Build, port: []const u8, baud: serial.Baud) *ConsoleStep {
        const self = b.allocator.create(ConsoleStep) catch @panic("OOM");
        self.* = .{
            .step = std.Build.Step.init(.{ .id = .custom, .name = "console", .owner = b, .makeFn = make }),
            .port = port,
            .baud = baud,
        };
        return self;
    }

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

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

        console.attach(self.port, self.baud, .{}) catch |err|
            return step.fail("console on {s}: {s}", .{ self.port, @errorName(err) });
    }
};

/// Pulse the reset line and leave. One ioctl pair, but it is the difference between "did my app
/// hang or did I forget to reset it" during development.
const ResetStep = struct {
    step: std.Build.Step,
    port: []const u8,

    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 step.fail("cannot open {s}: {s}", .{ self.port, @errorName(err) });
        defer port.close();
        port.resetToRun(.{}) catch |err| return step.fail("reset failed: {s}", .{@errorName(err)});
    }
};

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

    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();
    }
};