From b42ecaed412be2e30b9e780eb7c9e46e1535f26f Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 26 Aug 2026 13:28:33 -0300 Subject: Make the toolchain a package another build can drive, and move the editor's glue to the editor --- src/pardes/app.zig | 483 -------------------------------------------- src/pardes/input_rescue.zig | 248 ----------------------- src/pardes/uart.zig | 153 -------------- 3 files changed, 884 deletions(-) delete mode 100644 src/pardes/app.zig delete mode 100644 src/pardes/input_rescue.zig delete mode 100644 src/pardes/uart.zig (limited to 'src') diff --git a/src/pardes/app.zig b/src/pardes/app.zig deleted file mode 100644 index 17bef83..0000000 --- a/src/pardes/app.zig +++ /dev/null @@ -1,483 +0,0 @@ -//! pardes, as ESP32-P4 firmware. -//! -//! There is no operating system under this. `_start` is the reset entry the second-stage bootloader -//! jumps to, and this file is the entire platform: a heap, a millisecond clock, and UART0. -//! -//! ## Where the editor is -//! -//! Not in this package. `../02-pardes-code` compiles its core for riscv32-freestanding and emits -//! ONE object exporting the six C functions declared below; `-Dpardes` links it. The seam is a file -//! rather than a package dependency for a reason recorded at length in `build.zig`: declaring the -//! editor as a `build.zig.zon` path dependency nested its ~30-package graph under this one and -//! broke every build in this repo, including the ones that have nothing to do with it. -//! -//! The seam is deliberately **bytes in, bytes out**. Everything that needs to know what a cell is - -//! vaxis, the ANSI encoder, the input parser, the capability handshake - lives on the far side, -//! next to the vaxis it is built against. What crosses is a byte stream in each direction, which is -//! exactly what a serial line is, so this file has no opinion about terminals at all. -//! -//! ## Where the memory is -//! -//! Measured on this die by `examples/memprobe.zig`, not read off a datasheet: -//! -//! 0x4FF02000..0x4FF3F000 244 KiB .data/.bss/.stack live at the bottom of this -//! 0x4FF3F000..0x4FF40000 4 KiB mask ROM .data/.bss - untouchable, ets_printf needs it -//! 0x4FF40000..0x4FFC0000 512 KiB handed to the editor as its entire heap -//! -//! The 512 KiB arrives as `__heap_start`/`__heap_end` from the generated linker script, so those -//! addresses are written down in exactly one place. The editor owns that span outright: it is -//! passed in at init and this file never allocates from it. -//! -//! PSRAM is not used. The board has 32 MB fitted and it would make all of this comfortable, but -//! ESP-IDF's own ESP32-P4 implementation runs past a thousand lines - MPLL, MSPI clocking, pin -//! drive and DQS, CS timing, mode registers, a connectivity check, and an entire timing-calibration -//! subsystem - and the mask ROM offers only MMU mapping, no device init. Touching it untrained -//! faults and hangs the core, which `examples/memprobe.zig` demonstrates on purpose. - -const std = @import("std"); -const soc = @import("soc"); -const config = @import("config"); - -/// `-Dprof`: time the two phases of a keystroke on the board and print the cycle counts. A -/// diagnostic, not a feature - see the loop. -const prof = config.prof; - -/// Every byte this loop has taken off the UART, for `-Dprof`. Ground truth for "did the burst -/// arrive", which a screen reconstruction cannot answer: a character can be missing from the screen -/// because it never arrived, because the editor never applied it, or because the viewport does not -/// show that column. -var rx_total: u32 = 0; - -/// How many input bytes to hand the editor before draining the receiver again. Chosen against the -/// FIFO rather than against the editor: 128 bytes of FIFO is 11 ms of wire at 115200, and 32 -/// keystrokes cost about 2 ms even on a long line, which leaves five times the margin needed. -const input_chunk = 8; -const hal = @import("hal"); -const heapmod = @import("heap"); -const uart = @import("uart.zig"); - -// ------------------------------------------------------------------------------------- the ABI -// Seven functions, all `callconv(.c)`, all implemented in the linked object. This is the complete -// interface between this board and the editor, and it is deliberately bytes-and-memory only: the -// editor never learns what a UART is, and this file never learns what a cell is. - -/// How the editor emits bytes. Called with finished runs of ANSI, many times per frame. -const WriteFn = *const fn (ctx: ?*anyopaque, ptr: [*]const u8, len: usize) callconv(.c) void; - -/// The board's pads, offered to the editor. Optional on the wire so a firmware with nothing to -/// toggle passes null and the `Gpio` word reports that rather than the object guessing. -const GpioFn = *const fn (ctx: ?*anyopaque, pin: u16, was: *u8, now: *u8) callconv(.c) bool; - -/// This board's allocator, handed across as plain function pointers. `log2_align` is a log2 value, -/// which is exactly how `std.mem.Alignment` represents itself, so neither side needs a conversion -/// table. -/// -/// The memory belongs to THIS side: only the firmware knows that the heap is the 384 KiB at -/// 0x4FF40000, that the 128 KiB above it is L2 cache, and that PSRAM is untrained. The editor gets -/// an allocator, not an address range. -const Allocator = extern struct { - ctx: ?*anyopaque, - alloc: *const fn (ctx: ?*anyopaque, len: usize, log2_align: u8) callconv(.c) ?[*]u8, - resize: *const fn (ctx: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8, new_len: usize) callconv(.c) bool, - free: *const fn (ctx: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8) callconv(.c) void, -}; - -/// The one number both sides must agree on. Linkers do not type-check C symbols, so a signature -/// that drifts on one side of this seam links cleanly and then corrupts the stack; checking this -/// before calling anything else turns that into a refusal to boot. -const abi_version: u32 = 2; -extern fn pardes_p4_abi_version() callconv(.c) u32; - -/// Hand over the allocator and the output sink, and state the initial window size. Returns 0, or a -/// small non-zero code this file can only report. -extern fn pardes_p4_init( - alloc: *const Allocator, - write: WriteFn, - gpio: ?GpioFn, - ctx: ?*anyopaque, - cols: u16, - rows: u16, -) callconv(.c) u32; - -/// Raw bytes off the wire: keystrokes, capability-query replies, and the host bridge's in-band -/// resize reports. The editor parses all three; this file distinguishes none of them. -extern fn pardes_p4_input(ptr: [*]const u8, len: usize) callconv(.c) void; - -/// Advance time. Separate from `input` because animations and timeouts must progress on a wire -/// where nothing is arriving. -extern fn pardes_p4_tick(now_ms: u64) callconv(.c) void; - -/// Emit one frame through the write callback. Returns 0 or an error code. -extern fn pardes_p4_render() callconv(.c) u32; - -/// Is there anything to draw - a dirty surface or a running animation? Asked every iteration so a -/// quiet editor costs no bytes on a 115200-baud link. -extern fn pardes_p4_wants_frame() callconv(.c) bool; - -/// Has the user asked to leave? There is nowhere to go, so this only stops the loop. -extern fn pardes_p4_quit() callconv(.c) bool; - -/// The last frame's three stages in CPU cycles: the copy of pardes's Surface into vaxis's grid, -/// vaxis's own diff-and-emit, and the push into the UART. Only meaningful under `-Dprof`; the -/// editor object always exports it, and it costs two CSR reads per stage. -extern fn pardes_p4_frame_prof(copy: *u64, render: *u64, flush: *u64) callconv(.c) void; - -// ------------------------------------------------------------------------------------ the sink - -/// The write callback handed to `pardes_p4_init`. No context is needed - there is one UART. -fn writeOut(_: ?*anyopaque, ptr: [*]const u8, len: usize) callconv(.c) void { - uart.write(ptr[0..len]); -} - -/// Flip one pad and report the level before and after. The editor's `Gpio` word calls this; the -/// editor has no register of its own for it, deliberately. -/// -/// THIS IS WHY THE SEAM IS HERE. A toggle is not a write to GPIO_OUT: `configureOutput` points the -/// pad's IO MUX at the GPIO function, routes the GPIO matrix's output to it, sets the drive strength -/// and input buffer and clears the pulls, and only then enables the driver - four register files, -/// indexed by a per-pin table. That code already exists in `hal/gpio.zig`, it is the same call -/// `src/main.zig` blinks with, and its register numbers are checked against ESP-IDF's own headers by -/// `zig build diff`. A second copy inside the editor object would be a second copy under no test. -/// -/// `getDrivenLevel` rather than `getLevel`: the answer is the level this board is DRIVING, which is -/// defined for every pin. The pad's own level is what the outside world says, and on an unconnected -/// header pin that is noise. The input buffer is enabled anyway, so `Peek` of GPIO_IN_REG shows the -/// pad for anyone who wants to compare the two. -fn gpioToggle(_: ?*anyopaque, pin: u16, was: *u8, now: *u8) callconv(.c) bool { - if (pin > hal.gpio.max_pin) return false; - const p: u8 = @intCast(pin); - hal.gpio.configureOutput(p, .{ .readback = true }); - const before = hal.gpio.getDrivenLevel(p); - if (before == 1) hal.gpio.setLow(p) else hal.gpio.setHigh(p); - was.* = before; - now.* = hal.gpio.getDrivenLevel(p); - return true; -} - -// ------------------------------------------------------------------------------------- the heap - -/// The span the linker script hands over, from `l2high`'s ORIGIN and LENGTH. -/// -/// Reached with `@extern`, NOT with `extern const __heap_start: anyopaque` plus -/// `@intFromPtr`/`@ptrFromInt`. That spelling was here first and it was silently wrong: declaring a -/// linker symbol as an `anyopaque` OBJECT gives the optimiser a zero-sized object, so a pointer -/// derived from its address carries provenance for zero bytes, and ordinary (non-volatile) stores -/// through it are dead code it may drop. `examples/heapcheck.zig` caught it on the die - the -/// allocator's first block header read back as `size=2988759312 next=0xffffffff`-not, and the free -/// list walk never terminated. A `[*]u8` from `@extern` has no size to lose. -const heap_start = @extern([*]align(heapmod.Heap.granule) u8, .{ .name = "__heap_start" }); -const heap_end = @extern([*]align(heapmod.Heap.granule) u8, .{ .name = "__heap_end" }); - -fn heapSpan() []align(heapmod.Heap.granule) u8 { - return heap_start[0 .. @intFromPtr(heap_end) - @intFromPtr(heap_start)]; -} - -/// The one heap. A K&R coalescing free list over that span, validated on this die by -/// `examples/heapcheck.zig`: 512 blocks fill and free back to a single 393,216-byte block, a holed -/// arena still satisfies a 4 KiB request, and 20,000 random operations drain back to one block. -var gpa_heap: heapmod.Heap = undefined; - -// The four C forwarders the editor is handed. `log2_align` round-trips through -// `std.mem.Alignment`, whose representation IS the log2 value. - -fn cAlloc(_: ?*anyopaque, len: usize, log2_align: u8) callconv(.c) ?[*]u8 { - const a = gpa_heap.allocator(); - return a.vtable.alloc(a.ptr, len, @enumFromInt(log2_align), @returnAddress()); -} - -fn cResize(_: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8, new_len: usize) callconv(.c) bool { - const a = gpa_heap.allocator(); - return a.vtable.resize(a.ptr, ptr[0..len], @enumFromInt(log2_align), new_len, @returnAddress()); -} - -fn cFree(_: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8) callconv(.c) void { - const a = gpa_heap.allocator(); - a.vtable.free(a.ptr, ptr[0..len], @enumFromInt(log2_align), @returnAddress()); -} - -const editor_allocator: Allocator = .{ - .ctx = null, - .alloc = cAlloc, - .resize = cResize, - .free = cFree, -}; - -// ------------------------------------------------------------------------------------ the clock - -/// Milliseconds since boot, off the systimer - a 16 MHz counter (`hal/systimer.zig:31`), which is -/// the cheapest trustworthy clock on this chip. `read` returns null if the unit is not running, in -/// which case time simply does not advance and the editor stops animating; that is a better failure -/// than a clock that jumps. -fn nowMs() u64 { - const us = hal.systimer.micros(.unit0) orelse return 0; - return us / 1000; -} - -// ------------------------------------------------------------------------------------- the loop - -export fn zig_main() noreturn { - // FIRST, before a single byte of `.rodata` is touched - which means before the marker below, - // because that marker IS a string literal in flash and would read as machine code without this. - soc.flushFlashCache(); - const heap = heapSpan(); - soc.rom.print("\r\nMARK B3 rom.print heap 0x%08x..0x%08x %u KiB\r\n", .{ - @as(u32, @intFromPtr(heap.ptr)), - @as(u32, @intFromPtr(heap.ptr)) + @as(u32, @intCast(heap.len)), - @as(u32, @intCast(heap.len / 1024)), - }); - - // The CPU clock, before anything is timed against it. The bootloader leaves 90 MHz and the - // CPLL is already at 360, so this is a divider change that disturbs neither UART0 (XTAL) nor - // the systimer (XTAL/2.5) nor the flash interface (SPLL). See hal/clkrst.zig:setCpuFreq. - if (config.cpu_mhz != 90) hal.clkrst.setCpuFreq(switch (config.cpu_mhz) { - 180 => .mhz180, - 360 => .mhz360, - else => .mhz90, - }); - - const rwdt_was_armed = hal.rwdt.disable(); - hal.systimer.init(); - _ = rwdt_was_armed; - - const their_abi = pardes_p4_abi_version(); - if (their_abi != abi_version) { - uart.write("MARK PARDES_ABI_MISMATCH\r\n"); - while (true) {} - } - - gpa_heap = heapmod.Heap.init(heap); - _ = uart.drainInput(); - - // Ask for more than any grid this board will ever render, so the SHELL's own ceiling is what - // governs - it clamps to `-Dp4-cols`/`-Dp4-rows` and reports the result. Naming 80x24 here made - // the firmware a second opinion about the geometry, which is one opinion too many. - const rc = pardes_p4_init(&editor_allocator, writeOut, gpioToggle, null, 255, 255); - - if (rc != 0) { - soc.rom.print("MARK PARDES_INIT_FAIL rc=%u\r\n", .{rc}); - const s = gpa_heap.stats(); - soc.rom.print("MARK PARDES_HEAP free=%u largest=%u blocks=%u\r\n", .{ - s.free, s.largest_free, s.free_blocks, - }); - while (true) {} - } - - // The HEAP, after the editor has taken what it needs. This is the number that decides how large - // a grid the board can drive, so it is printed on every boot rather than only on failure: a - // geometry that fits with 2 KB to spare and one that fits with 80 KB are not the same answer, - // and the difference is invisible from the host otherwise. - { - const s = gpa_heap.stats(); - soc.rom.print("MARK PARDES_HEAP free=%u largest=%u blocks=%u\r\n", .{ - s.free, s.largest_free, s.free_blocks, - }); - } - - // The CPU clock, measured rather than assumed. Every cycle count this firmware reports is - // divided by it somewhere, and `src/io/chip.zig` records it as "a measured ~90 MHz" that - // nothing here reconfigures - so it is worth printing rather than remembering. The systimer is - // XTAL/2.5 = 16 MHz and is NOT derived from the CPU clock (`hal/systimer.zig:31`, - // `clk_tree_defs.h:196-198`), which is exactly what makes it a valid reference for measuring it. - if (prof) { - const t_start = hal.systimer.micros(.unit0) orelse 0; - const c_start = soc.cycles(); - // 50 ms is long enough that the systimer's 16 MHz granularity and the loop's own overhead - // are both noise, and short enough to be invisible in a boot. - while ((hal.systimer.micros(.unit0) orelse 0) -% t_start < 50_000) {} - const elapsed_us = (hal.systimer.micros(.unit0) orelse 0) -% t_start; - const elapsed_cy = soc.cycles() - c_start; - soc.rom.print("MARK CPU_HZ cycles=%u us=%u khz=%u\r\n", .{ - @as(u32, @intCast(elapsed_cy)), - @as(u32, @intCast(elapsed_us)), - @as(u32, @intCast(if (elapsed_us > 0) elapsed_cy * 1000 / elapsed_us else 0)), - }); - } - soc.rom.print("MARK PARDES_READY\r\n", .{}); - - var in: [256]u8 = undefined; - while (!pardes_p4_quit()) { - // ATTRIBUTION. The host can time a keystroke's round trip but cannot see what the firmware - // spent it on, and the two candidates - parsing and editing, versus rendering - want - // opposite fixes. `soc.cycles()` is the unprivileged cycle counter, so this costs two CSR - // reads per phase and quantises at one cycle, which is four orders of magnitude below the - // milliseconds being attributed. Gated on `prof` so the shipping build carries none of it. - const n = uart.read(&in); - rx_total +%= @intCast(n); - - var input_cy: u64 = 0; - if (n > 0) { - const t0 = if (prof) soc.cycles() else 0; - // IN CHUNKS, rescuing the receiver between them. Applying a keystroke is not free and - // gets dearer as the line grows - measured at 44 us on an empty line and 63 us at 640 - // characters - so handing over a full 128-byte batch is up to 8 ms in which nothing - // drains the receiver, against a FIFO that holds only 11 ms of wire. A 600-byte paste - // lost 93 bytes to exactly that window even with the transmitter's own rescue in place. - // - // Splitting a burst at an arbitrary byte is safe: `pardes_p4_input` keeps whatever it - // could not parse, which is how it already survives an escape sequence split across two - // UART reads. One render still happens per loop iteration, so this costs no extra wire. - var off: usize = 0; - while (off < n) { - const chunk = @min(input_chunk, n - off); - pardes_p4_input(in[off..].ptr, chunk); - off += chunk; - if (off < n) uart.rescueNow(); - } - if (prof) input_cy = soc.cycles() - t0; - } - - pardes_p4_tick(nowMs()); - - // Only when there is something to show. On a link this slow an unconditional repaint per - // iteration would saturate the wire and starve input. - if (pardes_p4_wants_frame()) { - const t0 = if (prof) soc.cycles() else 0; - const err = pardes_p4_render(); - if (err != 0) soc.rom.print("MARK PARDES_RENDER_FAIL rc=%u\r\n", .{err}); - if (prof) { - const render_cy = soc.cycles() - t0; - // A SECOND render with nothing changed since the first. It splits the cost in two: - // whatever this still costs is the price of walking and diffing the whole editor - // state, paid regardless of output, while the difference between the two is the - // price of the change itself. `wants_frame` is false now, so this only happens - // under -Dprof and never on a shipping build. - const t1 = soc.cycles(); - _ = pardes_p4_render(); - const idle_cy = soc.cycles() - t1; - // Reported in cycles, not microseconds: the divisor is the CPU clock, which this - // firmware does not set and has only ever measured, so converting here would bake a - // guess into the data. `experiments/` divides by the clock it measured. - var copy_cy: u64 = 0; - var vx_cy: u64 = 0; - var flush_cy: u64 = 0; - pardes_p4_frame_prof(©_cy, &vx_cy, &flush_cy); - soc.rom.print("PROF in=%u render=%u idle=%u copy=%u vaxis=%u flush=%u rx=%u rxdrop=%u txdrop=%u\r\n", .{ - @as(u32, @intCast(input_cy)), - @as(u32, @intCast(render_cy)), - @as(u32, @intCast(idle_cy)), - @as(u32, @intCast(copy_cy)), - @as(u32, @intCast(vx_cy)), - @as(u32, @intCast(flush_cy)), - rx_total, - uart.inputDropped(), - uart.dropped, - }); - } - } - } - - soc.rom.print("\r\nMARK PARDES_QUIT\r\n", .{}); - while (true) {} -} - -// ------------------------------------------------------------------------------------ the trap - -/// A trap handler, because the absence of one is why this port has been guessing. -/// -/// The mask ROM prints "Guru Meditation" for a trap only while ITS handler is still installed; -/// anything this image does that replaces or outgrows that path fails silently instead, and a silent -/// fault is indistinguishable from an infinite loop over a serial line. This one reports the three -/// registers that name the fault and then stops, using the direct-FIFO writer so it shares nothing -/// with the editor's buffered output. -/// -/// `mtvec` is set in DIRECT mode (low two bits zero), so every trap and every interrupt lands on -/// `trapEntry` regardless of cause - which is what a diagnostic wants. -export fn trapEntry() linksection(".text.entry") callconv(.naked) noreturn { - asm volatile ("j trapReport"); -} - -export fn trapReport() noreturn { - const mcause = asm volatile ("csrr %[o], mcause" - : [o] "=r" (-> u32), - ); - const mepc = asm volatile ("csrr %[o], mepc" - : [o] "=r" (-> u32), - ); - const mtval = asm volatile ("csrr %[o], mtval" - : [o] "=r" (-> u32), - ); - uart.write("\r\nMARK TRAP mcause="); - uart.dumpWord(mcause); - uart.write("MARK TRAP mepc="); - uart.dumpWord(mepc); - uart.write("MARK TRAP mtval="); - uart.dumpWord(mtval); - uart.write("MARK TRAP dropped="); - uart.dumpWord(uart.dropped); - while (true) {} -} - -// --------------------------------------------------------------------------- the root's own duties - -/// `page_size_min`/`max`: the board has no MMU and no pages, but std derives allocator alignment -/// from these. 4 KiB is the ESP32-P4's cache and DMA granularity. -/// -/// `logFn` is not cosmetic. std's default log implementation reaches `std.debug_io`, which -/// instantiates `std.Io.Threaded` - a thread pool, `getrandom`, `IOV_MAX`, `mremap` - none of which -/// exist here, and one `log.warn` from anywhere is enough to drag all of it into the image. -pub const std_options: std.Options = .{ - .page_size_min = 4096, - .page_size_max = 4096, - .logFn = logFn, -}; - -fn logFn( - comptime level: std.log.Level, - comptime scope: @EnumLiteral(), - comptime fmt: []const u8, - args: anytype, -) void { - var buf: [256]u8 = undefined; - const line = std.fmt.bufPrint(&buf, "\r\n[" ++ level.asText() ++ "/" ++ @tagName(scope) ++ "] " ++ fmt ++ "\r\n", args) catch - "\r\n[log overflow]\r\n"; - uart.write(line); -} - -pub const panic = std.debug.FullPanic(panicImpl); - -fn panicImpl(msg: []const u8, first_trace_addr: ?usize) noreturn { - // The fixed text goes out through the ROM deliberately: a panic may BE the console writer - // failing, and `ets_printf` shares nothing with `uart.write` except the FIFO itself. - // - // The MESSAGE does not, and that is a correction rather than a preference. `msg` is a Zig SLICE - // and `%s` reads until a NUL, so handing `msg.ptr` to printf prints the message and then - // whatever happens to sit after it in memory until a zero byte turns up. Literals get away with - // it; std's own panics do not, because they are formatted into a buffer - "index out of bounds: - // index 5, len 3" - and carry no terminator. `uart.write` takes a length. - soc.rom.print("\r\nMARK PARDES_PANIC ", .{}); - uart.write(msg); - // The address is what makes it actionable: addr2line against the ELF in zig-out turns it into a - // source line, and without it a panic message names a KIND of failure with no way to find which - // one of them happened. Zero when the caller had no return address to give. - soc.rom.print("\r\nMARK PARDES_PANIC_AT 0x%08x\r\n", .{@as(u32, @truncate(first_trace_addr orelse 0))}); - while (true) {} -} - -/// Reset entry. The bootloader hands over with an unspecified stack pointer and the FPU off, so: -/// enable the F extension (`mstatus.FS`, which ESP-IDF only ever turns on lazily from a trap handler -/// this image does not have), establish a stack, clear `.bss`, and call into Zig. -/// -/// The cache invalidate that this image also needs is the FIRST thing `zig_main` does, not something -/// done here. Hand-written `la t0, Cache_Invalidate_All` against an absolute linker symbol computed -/// a PC-relative target and jumped into nowhere (measured: PC=0x88b5d788 with the argument stranded -/// in a2); Zig generates the addressing for an `extern fn` correctly, and `zig_main` runs before any -/// `.rodata` is touched anyway. -export fn _start() linksection(".text.entry") callconv(.naked) noreturn { - asm volatile ( - \\ li t0, 1 << 13 - \\ csrs mstatus, t0 - \\ la sp, __stack_top - \\ mv fp, sp - \\ la t0, trapEntry - \\ csrw mtvec, t0 - \\ la t0, __bss_start - \\ la t1, __bss_end - \\ bgeu t0, t1, 2f - \\1: - \\ sw zero, 0(t0) - \\ addi t0, t0, 4 - \\ bltu t0, t1, 1b - \\2: - \\ j zig_main - ); -} diff --git a/src/pardes/input_rescue.zig b/src/pardes/input_rescue.zig deleted file mode 100644 index ea242b2..0000000 --- a/src/pardes/input_rescue.zig +++ /dev/null @@ -1,248 +0,0 @@ -//! Keystrokes rescued from the receive FIFO while the transmitter is busy. -//! -//! THE BUG THIS EXISTS FOR. The firmware's loop is read, apply, render, write, and the write blocks -//! while the transmit FIFO is full - real backpressure, because dropping half an escape sequence -//! would leave the host terminal in the wrong colour for the rest of the session. But nothing -//! drained the RECEIVE FIFO during that wait, and the FIFO is 128 bytes (`hal/uart.zig:52`). A frame -//! of 240 bytes is 21 ms of wire at 115200, and 21 ms of a host sending at line rate is ~240 bytes, -//! so everything past the 128th was silently gone. -//! -//! Measured on the die before the fix, typing a burst in one host write and counting what the editor -//! actually held: 128 bytes arrived intact, 200 bytes lost 88, 300 bytes lost all 300. From a -//! keyboard that is a keystroke that never lands, and it looks like a stuck key - the screen is -//! behind what was typed, and typing more appears to fix it because a later frame repaints the cells -//! the lost keystrokes would have changed. -//! -//! WHY THE POLICY LIVES HERE and not in `uart.zig`: the interesting part is a decision - drain the -//! receiver while spinning on the transmitter, and what to do when even that overflows - and the -//! decision is worth testing. `uart.zig` cannot be tested at all without the chip, because every -//! line of it is an MMIO access. `pump` takes the port as `anytype`, so the same code runs against -//! the real UART on the board and against a fake with a two-byte FIFO in `zig build test`. - -const std = @import("std"); - -/// Capacity, sized for the worst frame this editor emits. -/// -/// A full repaint is ~1.4 KB, which is 121 ms of wire at 115200, and 121 ms of a host pasting at -/// line rate is ~1.4 KB of input. 4 KiB is that with headroom, a power of two so the wrap is a mask -/// rather than a division, and nothing at all against the board's RAM. -pub const capacity = 4096; - -/// A byte queue that drops the NEWEST byte when full. -/// -/// Dropping the newest rather than the oldest is deliberate: what survives is then a PREFIX of what -/// was typed. An editor that loses the end of a paste has done something a person can see and -/// correct; one that silently reorders keystrokes, or keeps the tail and discards the head, has -/// corrupted the document in a way that looks like the editor inventing input. -pub const Ring = struct { - buf: [capacity]u8 = undefined, - head: usize = 0, - len: usize = 0, - /// Bytes lost because even this overflowed. Nonzero means input was dropped; it is the honest - /// version of the bug rather than a cure for it. - dropped: u32 = 0, - - const mask = capacity - 1; - - comptime { - std.debug.assert(capacity & mask == 0); - } - - pub fn push(r: *Ring, b: u8) void { - if (r.len == capacity) { - r.dropped +%= 1; - return; - } - r.buf[(r.head + r.len) & mask] = b; - r.len += 1; - } - - /// Move as much as fits into `out`, oldest first. Returns the count. - pub fn pop(r: *Ring, out: []u8) usize { - const n = @min(out.len, r.len); - for (out[0..n]) |*slot| { - slot.* = r.buf[r.head]; - r.head = (r.head + 1) & mask; - } - r.len -= n; - return n; - } - - pub fn clear(r: *Ring) void { - r.head = 0; - r.len = 0; - } -}; - -/// Drain everything the port has received into `ring`, without waiting. -pub fn rescue(port: anytype, ring: *Ring) void { - var waiting = port.rxCount(); - while (waiting > 0) : (waiting -= 1) ring.push(port.popByte()); -} - -/// Push `bytes` through `port`, rescuing input whenever the transmitter has no room. Returns the -/// number of bytes abandoned because the transmitter stopped making progress altogether. -/// -/// The spin bound is why this returns a count rather than blocking forever: a UART whose core clock -/// has been gated never makes progress, and on a board with no debugger an infinite spin is -/// indistinguishable from a crash. A bounded wait turns that into visibly dropped output plus a -/// counter, which is a diagnosis instead of a mystery. -pub fn pump(port: anytype, ring: *Ring, bytes: []const u8, spin_limit: u32) u32 { - var rest = bytes; - while (rest.len > 0) { - // One status read per burst, not per byte: reading `txFree` once and pushing that many cuts - // the status reads by up to the FIFO depth. - var room = port.txFree(); - var spins: u32 = 0; - while (room == 0) { - // THE FIX. Every iteration of this wait is time the receiver is filling up, and this is - // the only place that can empty it. - rescue(port, ring); - spins += 1; - if (spins > spin_limit) return @intCast(rest.len); - room = port.txFree(); - } - const n = @min(room, rest.len); - for (rest[0..n]) |b| port.pushByte(b); - rest = rest[n..]; - } - return 0; -} - -// ------------------------------------------------------------------------------------ host tests - -test "the ring hands bytes back in order" { - var r: Ring = .{}; - for ("hello") |b| r.push(b); - var out: [8]u8 = undefined; - try std.testing.expectEqual(@as(usize, 5), r.pop(&out)); - try std.testing.expectEqualStrings("hello", out[0..5]); - try std.testing.expectEqual(@as(usize, 0), r.pop(&out)); -} - -test "the ring wraps without reordering" { - var r: Ring = .{}; - var out: [capacity]u8 = undefined; - // Push and pop most of the buffer so head sits near the end, then straddle the wrap. - for (0..capacity - 3) |i| r.push(@intCast(i & 0xff)); - _ = r.pop(out[0 .. capacity - 3]); - for ("straddle") |b| r.push(b); - const n = r.pop(&out); - try std.testing.expectEqualStrings("straddle", out[0..n]); -} - -test "a full ring drops the newest and says so" { - var r: Ring = .{}; - for (0..capacity) |i| r.push(@intCast(i & 0xff)); - try std.testing.expectEqual(@as(u32, 0), r.dropped); - r.push('!'); - r.push('!'); - try std.testing.expectEqual(@as(u32, 2), r.dropped); - // The head is intact: what survived is a prefix of what arrived. - var out: [4]u8 = undefined; - _ = r.pop(&out); - try std.testing.expectEqual(@as(u8, 0), out[0]); - try std.testing.expectEqual(@as(u8, 1), out[1]); -} - -/// A UART with a small transmit FIFO, a small RECEIVE FIFO, and a host that keeps typing into it. -/// -/// The receive FIFO is the part that matters and it is modelled the way the hardware behaves: it has -/// a fixed depth, and a byte that arrives when it is full is *gone*. That is the whole bug. -/// -/// Time advances on each transmitter status read, which is what `pump` does while it waits. The -/// transmitter frees a byte only every fourth tick while a typed byte lands on every one: the -/// transmitter therefore genuinely FILLS, which is the condition the bug needs. A fake whose FIFO -/// drains as fast as it fills never blocks, so `pump` never waits, so the rescue never runs and the -/// test proves nothing - the first version of this fake had exactly that flaw. -const FakePort = struct { - tx_cap: u32, - tx_used: u32 = 0, - sent: std.ArrayList(u8) = .empty, - gpa: std.mem.Allocator, - - incoming: []const u8, - delivered: usize = 0, - rx: [rx_depth]u8 = undefined, - rx_head: usize = 0, - rx_len: usize = 0, - /// Bytes the wire delivered into a full receive FIFO. The hardware has no counter for this, - /// which is exactly why the bug was invisible. - lost: u32 = 0, - - ticks: u32 = 0, - - const rx_depth = 8; - const tx_drain_every = 4; - - fn tick(p: *FakePort) void { - p.ticks += 1; - if (p.ticks % tx_drain_every == 0 and p.tx_used > 0) p.tx_used -= 1; - if (p.delivered < p.incoming.len) { - const b = p.incoming[p.delivered]; - p.delivered += 1; - if (p.rx_len == rx_depth) { - p.lost += 1; - } else { - p.rx[(p.rx_head + p.rx_len) % rx_depth] = b; - p.rx_len += 1; - } - } - } - - fn txFree(p: *FakePort) u32 { - p.tick(); - return p.tx_cap - p.tx_used; - } - - fn pushByte(p: *FakePort, b: u8) void { - p.sent.append(p.gpa, b) catch unreachable; - p.tx_used += 1; - } - - fn rxCount(p: *FakePort) u32 { - return @intCast(p.rx_len); - } - - fn popByte(p: *FakePort) u8 { - const b = p.rx[p.rx_head]; - p.rx_head = (p.rx_head + 1) % rx_depth; - p.rx_len -= 1; - return b; - } -}; - -test "a long transmit does not lose the input that arrives during it" { - // THE REGRESSION. Delete the `rescue` call inside `pump`'s wait and this fails: the receive FIFO - // is eight bytes deep, the typing below is far longer than that, and every byte that arrives - // into a full FIFO is gone with nothing to record it. That is the die's 88-of-200 in miniature. - const typed = "the quick brown fox jumps over the lazy dog, twice over, and then some more"; - var port: FakePort = .{ .tx_cap = 2, .incoming = typed, .gpa = std.testing.allocator }; - defer port.sent.deinit(std.testing.allocator); - var ring: Ring = .{}; - - const frame = "\x1b[1;1H" ++ "x" ** 400; - try std.testing.expectEqual(@as(u32, 0), pump(&port, &ring, frame, 1_000_000)); - - // Every output byte went out, in order. - try std.testing.expectEqualStrings(frame, port.sent.items); - // Nothing the wire delivered was dropped, by the FIFO or by the ring. - try std.testing.expectEqual(@as(u32, 0), port.lost); - try std.testing.expectEqual(@as(u32, 0), ring.dropped); - // And what was rescued, plus whatever is still sitting in the FIFO, is exactly what was typed - - // in order, which is the other half of the contract. - var got: [capacity]u8 = undefined; - var n = ring.pop(&got); - while (port.rxCount() > 0) : (n += 1) got[n] = port.popByte(); - try std.testing.expectEqualStrings(typed[0..port.delivered], got[0..n]); - try std.testing.expect(port.delivered == typed.len); -} - -test "a transmitter that never drains gives up and reports what it abandoned" { - var port: FakePort = .{ .tx_cap = 0, .incoming = "", .gpa = std.testing.allocator }; - defer port.sent.deinit(std.testing.allocator); - var ring: Ring = .{}; - // tx_cap 0 means txFree is always 0, so no byte can ever go out. - try std.testing.expectEqual(@as(u32, 5), pump(&port, &ring, "abcde", 32)); - try std.testing.expectEqual(@as(usize, 0), port.sent.items.len); -} diff --git a/src/pardes/uart.zig b/src/pardes/uart.zig deleted file mode 100644 index 7696742..0000000 --- a/src/pardes/uart.zig +++ /dev/null @@ -1,153 +0,0 @@ -//! UART0 as the editor's terminal: bytes out, bytes in, and nothing else. -//! -//! This is the whole of the firmware's I/O. There is no framebuffer and no keyboard; the board -//! emits ANSI and consumes ANSI, and the terminal emulator on the far end of the CH340 does the -//! rest of the work - including answering the editor's own capability queries, which travel down -//! this wire like any other bytes. -//! -//! Deliberately not a `std.Io.Writer`. The ANSI encoding lives on the other side of the C ABI, next -//! to the vaxis that produces it (see `src/pardes/app.zig` for why the seam is there and not -//! elsewhere), so what crosses into this file is already a finished run of bytes. A writer here -//! would be a second buffer in front of one that already exists. -//! -//! Two decisions worth stating, because both are measurements rather than preferences. -//! -//! **Batched FIFO access.** The naive push is `while (txFree() == 0) {}` then `pushByte`, once per -//! byte: one MMIO read per byte at best, many while the FIFO is full. Reading `txFree` once and -//! then pushing that many cuts the status reads by up to the FIFO depth (128, `hal/uart.zig:52`). -//! At 115200 the wire costs ~86 us per byte and dwarfs either version, so today this is merely -//! free - and it stops being free the moment the divider is raised. -//! -//! **UART0's configuration is never touched.** Not the divider, not the format, not the pad -//! routing, and above all not `reset()`. The second-stage bootloader configured this block, and -//! `hal/uart.zig:195-211` records what happens if it is reset: UART_CLKDIV returns to its power-on -//! value, the console turns to garbage mid-sentence, and the board takes a watchdog reset with -//! nothing readable left to explain it. Everything here touches FIFO offset 0x000 and the status -//! register, and nothing else. - -const hal = @import("hal"); -const input_rescue = @import("input_rescue.zig"); - -/// UART0: the instance the CH340 is wired to, and the one the ROM and bootloader configured. -const uart0 = hal.uart.Uart.init(0); - -/// Keystrokes taken off the receiver while the transmitter was full. See `input_rescue`: without -/// this, anything typed into a frame longer than the 128-byte FIFO was silently gone. -var rescued: input_rescue.Ring = .{}; - -/// Push `bytes` into the TX FIFO, blocking while it is full. -/// -/// The spin is normally bounded by the wire - a full 128-byte FIFO drains in 11 ms at 115200 - and -/// dropping instead of waiting would truncate an escape sequence, leaving the host terminal in the -/// wrong colour for the rest of the session. So the wait is real backpressure. -/// -/// But it is BOUNDED, for the reason `hal/uart.zig:182-186` gives about `update()`: a UART whose -/// core clock has been gated never makes progress, and "on a board with no debugger an infinite -/// spin is indistinguishable from a crash". That is not hypothetical here - it is how this port -/// spent an afternoon: output stopped mid-boot with no panic and no watchdog (the RTC watchdog -/// having been correctly disabled), which looked like a hang in whatever code came next rather than -/// a stalled transmitter. A bounded wait turns that into visibly dropped output plus a counter, -/// which is a diagnosis instead of a mystery. -/// -/// The limit is per burst, not per call, and generous: 1,000,000 status reads is far longer than -/// any legitimate drain and still a fraction of a second. -pub fn write(bytes: []const u8) void { - dropped +%= input_rescue.pump(uart0, &rescued, bytes, 1_000_000); -} - -/// Bytes abandoned because the transmitter stopped making progress. Nonzero means the console is -/// lying about what happened, so it is worth printing. -pub var dropped: u32 = 0; - -/// One byte, for callers that must not touch `.rodata` to say anything - which during bring-up is -/// the difference between a diagnostic and a second copy of the bug being diagnosed. -pub fn writeByte(b: u8) void { - var spins: u32 = 0; - while (uart0.txFree() == 0) { - spins += 1; - if (spins > 1_000_000) { - dropped +%= 1; - return; - } - } - uart0.pushByte(b); -} - -/// Emit `n` bytes read from `addr` as two hex digits each, computing the digits arithmetically so -/// nothing here reads a lookup table. Used to answer "does a load from this address return what the -/// linker put there", which is not a question a string literal can be trusted to ask. -pub fn dumpHex(addr: u32, n: u32) void { - const p: [*]const volatile u8 = @ptrFromInt(addr); - var i: u32 = 0; - while (i < n) : (i += 1) { - const byte = p[i]; - for ([2]u8{ byte >> 4, byte & 0xf }) |nib| { - writeByte(if (nib < 10) '0' + nib else 'a' + (nib - 10)); - } - } - writeByte('\r'); - writeByte('\n'); -} - -/// A u32 as eight hex digits, reading no memory at all. -pub fn dumpWord(v: u32) void { - var shift: u5 = 28; - while (true) { - const nib: u8 = @intCast((v >> shift) & 0xf); - writeByte(if (nib < 10) '0' + nib else 'a' + (nib - 10)); - if (shift == 0) break; - shift -= 4; - } - writeByte('\r'); - writeByte('\n'); -} - -/// Move whatever the host has sent into `buf`, without waiting. Returns the count. -/// -/// Non-blocking on purpose: the loop has a frame to render and a core to pump, and the editor must -/// not stall on a keystroke that may never come. `rxCount` is read once per call and the FIFO -/// drained to that mark, so a fast typist or a pasted buffer cannot hold the loop here. -pub fn read(buf: []u8) usize { - // RESCUED BYTES FIRST. They arrived before anything still sitting in the FIFO, and an editor - // that reorders keystrokes is worse than one that drops them. - var n = rescued.pop(buf); - const waiting = @min(uart0.rxCount(), buf.len - n); - for (buf[n..][0..waiting]) |*slot| slot.* = uart0.popByte(); - n += waiting; - return n; -} - -/// Take whatever has arrived off the receiver right now, without waiting and without handing it to -/// anyone. For callers that are about to spend a while not reading: `write` does this while the -/// transmitter is full, and the loop does it between chunks of input, because applying a keystroke -/// gets more expensive as the line grows and 128 bytes of FIFO is only 11 ms at 115200. -pub fn rescueNow() void { - input_rescue.rescue(uart0, &rescued); -} - -/// Input abandoned because even the rescue buffer overflowed. Distinct from `dropped`, which is -/// OUTPUT abandoned by a stalled transmitter. -pub fn inputDropped() u32 { - return rescued.dropped; -} - -/// Discard anything already received, returning how much. Used once at startup: the host-side -/// bridge injects a window-size report before this program exists, and the bootloader's chatter has -/// already been echoed at the host. Neither is user input. -/// -/// Pops rather than calling `resetRxFifo`, which is a CONF0_SYNC read-modify-write plus two commits -/// on the console UART - see this file's header. -pub fn drainInput() u32 { - var discarded: u32 = 0; - while (uart0.rxCount() > 0) : (discarded += 1) _ = uart0.popByte(); - discarded += @intCast(rescued.len); - rescued.clear(); - return discarded; -} - -/// The rate the hardware is actually producing, by reading its dividers back. Reported rather than -/// assumed: the host has to be opened at the same rate, and a mismatch shows up as garbage on the -/// screen rather than as an error anyone can act on. -pub fn baudrate() u32 { - return uart0.baudrate(uart0.clockSource().nominalHz()); -} -- cgit v1.3