diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-05 11:21:15 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-05 12:41:12 -0300 |
| commit | cfd2b993feda1b3f7474225bb32db8cac8edc5ae (patch) | |
| tree | 3248246c043fd1865e74adb979a9cb555f918cd6 /src/esp32p4/uart.zig | |
| parent | c0b2e5d9194ce35b9fbb58d8d6e18de66cb209a8 (diff) | |
| download | pardes-cfd2b993feda1b3f7474225bb32db8cac8edc5ae.tar.gz pardes-cfd2b993feda1b3f7474225bb32db8cac8edc5ae.zip | |
targets: the ESP32-P4 board port goes (src/esp32p4*.zig and src/esp32p4/, -Dplatform=esp32p4 with its pinned riscv32 target, -Desp32p4-cols and -rows, the Peek, Poke, Hexdump and Gpio words and the Board behind them, the board's 9P engine options, the gpio_toggle host slot), and with it every guard and limit only the board needed: terminal_panes and terminal.enabled (ghostty is in every build), memory.limits' board branching (the desktop values stay), MAX_PANES 64 and MAX_COLS 16 fixed, the board's boot buffer and its embedded boot, the pager's and the terminal's emulator-less paths; tests: the board's GPIO, ring and Board ones go, the boot-OOM and transition-grid ones stay under their own names; the perf harness loses the board's fixture, so the Debug baselines of both frontends are recorded again (--only medium --reps 10)
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'src/esp32p4/uart.zig')
| -rw-r--r-- | src/esp32p4/uart.zig | 190 |
1 files changed, 0 insertions, 190 deletions
diff --git a/src/esp32p4/uart.zig b/src/esp32p4/uart.zig deleted file mode 100644 index a185737d..00000000 --- a/src/esp32p4/uart.zig +++ /dev/null @@ -1,190 +0,0 @@ -//! UART0 transport for the editor and standalone GPIO 9P firmware. -//! -//! 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. -//! -//! WHY IT IS IN THIS REPOSITORY. It is not a UART driver - that is `hal.uart`, which stays in the -//! toolchain package and is checked against ESP-IDF's own headers by `zig build diff` there. This is -//! the EDITOR's use of one: which instance the console is, that the transmitter is real -//! backpressure because a truncated escape sequence corrupts the host terminal, that rescued -//! keystrokes must come out before FIFO ones, and that the first thing to do at startup is discard -//! the host bridge's synthetic resize report. Every one of those is a statement about the editor, so -//! the file moved to sit beside it. See `app.zig`'s header for the boundary in full. -//! -//! What it expects from the toolchain package is exactly one module: `hal`, for `hal.uart.Uart`. -//! Nothing else here reaches the chip. The sibling `input_rescue.zig` is a plain file, not a module, -//! because it is this repository's own policy. -//! -//! 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 `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, the toolchain -//! package's `src/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, except by `setBaud`.** Not the format, not the pad -//! routing, and above all not `reset()`. The second-stage bootloader configured this block, and -//! `src/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 else here touches FIFO offset 0x000 and the -//! status register, and nothing else. -//! -//! The editor inherits the bootloader's 115200 divider. `src/esp32p4_9p.zig` -//! calls `setBaud` for its 921600 protocol connection; the host must match it. - -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 the toolchain package's `src/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; - -/// Push as much of `bytes` as the transmitter has room for RIGHT NOW, and answer how much. Never -/// spins, never drops, never rescues — because it never waits for anything. -/// -/// THIS IS THE SANS-IO WRITE, and it exists because `write` above is the wrong primitive for a -/// protocol server. `write` is right for a console: a frame of ANSI is atomic to the terminal on the -/// far end, half an escape sequence leaves it in the wrong colour, so blocking until the whole burst -/// is in the FIFO is real backpressure and worth the stall. A 9P reply is not atomic to anything: -/// every message carries its own length, the reader on the far end reassembles, and -/// `9p.Server.wrote(n)` exists precisely so that a partial write costs nothing but another trip -/// round the loop (`src/9p.zig:2248-2257`). So this hands over what fits and returns, and -/// `src/esp32p4_9p.zig`'s loop keeps the remainder queued in the server where it already was. -/// -/// The difference that matters is DROPPING. `write`'s bounded spin gives up after a million status -/// reads and counts the loss, which turns a stalled transmitter into a diagnosable console; the same -/// behaviour on a 9P stream would truncate a reply mid-message and desynchronise the connection for -/// good. A short count cannot desynchronise anything. -pub fn writeSome(bytes: []const u8) usize { - const n = @min(@as(usize, uart0.txFree()), bytes.len); - for (bytes[0..n]) |b| uart0.pushByte(b); - return n; -} - -/// Reprogram UART0's divider, and answer whether the rate is reachable from the clock this block is -/// running on. Nothing is touched when it is not. -/// -/// THE ONE EXCEPTION to this file's rule, and see the header for who may call it: not this file, not -/// `app.zig`, only an image whose host side is opened at the same rate. `docs/registry.pdf` -/// `BOARD-1` has the numbers — 921600 is one `UART_CLKDIV_SYNC` write on the existing 40 MHz XTAL, -/// int 43 frag 6, +0.064% error, and it takes a byte from 86.8 µs to 10.85 µs. -/// -/// The hazard is worth restating where the call is: the bytes already in the FIFO go out at the OLD -/// rate, so anything written before this and not yet drained is corrupted, and a host that is not -/// reopened sees garbage from here on with no error to report. The 9P image calls this before it -/// answers its first message, which is the one moment when neither of those can have happened yet. -pub fn setBaud(baud: u32) bool { - return uart0.setBaudrate(baud, uart0.clockSource().nominalHz()); -} - -/// 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); -} - -/// 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()); -} |
