1 files changed, 115 insertions, 0 deletions
diff --git a/src/pardes/uart.zig b/src/pardes/uart.zig
new file mode 100644
index 0000000..ce386fe
--- /dev/null
+++ b/src/pardes/uart.zig
@@ -0,0 +1,115 @@
+//! 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");
+
+/// UART0: the instance the CH340 is wired to, and the one the ROM and bootloader configured.
+const uart0 = hal.uart.Uart.init(0);
+
+/// Push `bytes` into the TX FIFO, blocking while it is full.
+///
+/// The spin is bounded by the wire and there is nothing else for this core to do: a full 128-byte
+/// FIFO drains in 11 ms at 115200. It is also the only backpressure in the system - dropping
+/// instead would truncate an escape sequence, and a half-written SGR leaves the host terminal in
+/// the wrong colour for the rest of the session.
+pub fn write(bytes: []const u8) void {
+    var rest = bytes;
+    while (rest.len > 0) {
+        // One status read per burst, not per byte.
+        var room = uart0.txFree();
+        while (room == 0) room = uart0.txFree();
+        const n = @min(room, rest.len);
+        for (rest[0..n]) |b| uart0.pushByte(b);
+        rest = rest[n..];
+    }
+}
+
+/// 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 {
+    while (uart0.txFree() == 0) {}
+    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 {
+    const waiting = @min(uart0.rxCount(), buf.len);
+    for (buf[0..waiting]) |*slot| slot.* = uart0.popByte();
+    return waiting;
+}
+
+/// 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 dropped: u32 = 0;
+    while (uart0.rxCount() > 0) : (dropped += 1) _ = uart0.popByte();
+    return dropped;
+}
+
+/// 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());
+}