From 147ebd4a36ec7199074ba05bcfb79d4a656c0b74 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 27 Aug 2026 16:42:15 -0300 Subject: 9p: the client half, and a board that serves its own tree over the UART Step 5 of the 9P chain (docs/9p.typ 12.5, docs/registry.typ 9P-22, 9P-11, BOARD-1). THE CLIENT. `Client` in src/9p.zig is the mirror of `Server` and the same shape: sans-io, no allocator, no threads, no descriptor, caller-owned buffers, and it builds freestanding. 152 bytes of struct against the server's 9,488, because a client owns neither a fid table nor a park table -- the far end does. The API is submit / push+output+wrote / take. Completion is a PULL: a callback would fire inside push, inside the transport's read, inside the host's poll dispatch, which is exactly where fs9_service says filesystem work must not happen. `take()` returns the next completed operation or null, which is `Server.next()`'s loop-until-null contract read from the other side. Tags are a fixed 16-entry table indexed BY the tag, so an out-of-order reply -- which 9P allows and both reference clients rely on -- costs one bounds check. The reply's TYPE is checked against the request's op, because a tag is only as good as the table behind it. A `Done` borrows the input buffer and is valid until the next call; `take()` releases the previous frame on entry, so the rule is mechanical rather than remembered, and read data and error strings are zero-copy. And one real caller, so this is not a library with no user: the `9p` word takes a dial and a path, walks another instance's tree, and opens the bytes in a pane like any other `Look`. THE BOARD. A SECOND image, not a second role: the console runtime keeps UART0 bidirectionally and is behaviourally untouched. On the new one the UART carries 9P AND NOTHING ELSE -- no ANSI, no vaxis, no allocator, no heap module. The loop is uart.read -> push / retry+next -> handle -> reply / output -> writeSome -> wrote. `writeSome` is new and additive: `write`'s bounded spin DROPS bytes on a stalled transmitter, which on a protocol stream truncates a reply mid-message and desynchronises for good, where a short count cannot. BOARD-1's one divider write raises the line to 921600. 88,000 B text, 49,424 B bss, an 88,080-byte image -- 5.7% of the 1,536,000 B partition, against the console image's 809,536 B. THE COMPTIME BRIDGE, which is the part worth reading. `board9p.caps` is the ONLY place the GPIO tree is described; node ids, parents, names, permissions, handlers, buffer size and the per-pin directories are all derived from it, and `fan.dirs` makes `gpio//value` one table entry serving eleven pins. Modes are derived from which handlers a file has rather than declared. A second capability is a table entry, not new tree code. JP1 became a real table in the new leaf `src/board_pins.zig`, with the ASCII drawing RENDERED from it at comptime and the pin list COLLECTED from it -- the 9P image links no core and so cannot import board_memory.zig, and copying the table was not acceptable. A golden test pins the drawing byte for byte, the console's own shape test still passes, and the identical bytes are present in all three artifacts. PROVED. Two daemons: B read A's `/1/body` through the `9p` word into a pane, byte-identical to plan9port's `9p read` of the same path. Both board images build. No hardware was attached, so nothing about the board is claimed beyond what builds and what the host tests cover. zig build unit-test 585/585. fs-bench unchanged and still zero allocations on every read row. --- REVIEW FIXES FOLDED IN. Steps 3, 4 and 5 were verified on the happy path and then adversarially reviewed by three agents; eight defects, six fixed here, five of them reproduced with measurements before and after. Full writeup in docs/registry.typ `9P-27`. In brief: * a remote crash of the WHOLE daemon: one `size[4]` of zero plus one byte hit `unreachable` in `fs9_service.fill`. Also 99.7% of a core when the stuck buffer made `room == 0` return without reading. Now `srv.dead` is a hangup, checked before the room guard. * the editor froze 177 s on a dial: `connect(2)` ran on a still-BLOCKING socket before the deadline existed, and a full accept backlog waits forever. Now non-blocking with the wait spent against the budget. After: 2.03 s. * a 64 KiB pty read is exactly `queue_cap` and wiped every unread byte AND dropped itself. `notePtyOutput` splits at half the cap. Deterministic. * four silent sockets denied `--fs9` forever; connections now expire on the same five-second rule the frontend transport already had. * EMFILE spun a core; the listener pauses and leaves the poll set, as the frontend listener does. * `max_fids = 32` made `find` over `9pfuse` fail with 57 consecutive `Rerror`s -- refuting this step's own acceptance clause. 256 for a host, `board_fids` 32 for the microcontroller. Found clean and worth recording: `sig` reaches the foreground process group; the two-namespace pty lookup is right over both transports; `PaneFile`'s u4 wall is guarded; reader counts release on every abrupt-death path; `fs_origin` routing and the reply arithmetic hold under probing. --- src/builtins.zig | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'src/builtins.zig') diff --git a/src/builtins.zig b/src/builtins.zig index 0e92f5ce..4e096c97 100644 --- a/src/builtins.zig +++ b/src/builtins.zig @@ -29,6 +29,11 @@ const image_pane = @import("image_pane.zig"); const config = @import("config.zig"); const runtime_config = @import("runtime_config.zig"); const board_memory = @import("board_memory.zig"); +/// The host half of the 9P client, for the `9p` word at the bottom. Imported +/// unconditionally and gated on `fs9_client.supported`, exactly like +/// board_memory above: nothing in it is analysed for a build whose platform +/// has no unix sockets, because the word is not registered there at all. +const fs9_client = @import("fs9_client.zig"); /// The platform's runtime-setting facilities, stated once as plain data. /// Registry generation, leader paths, Config, and EffectCode all consume this @@ -1065,3 +1070,38 @@ pub const Gpio = struct { c.p.reportError(c.id, "gpio", err); } }; + +// ---- somebody else's tree ---- + +/// `9p ` — walk to a file in ANOTHER pardes's tree, read it, and +/// open the bytes in a pane. +/// +/// THE OTHER END OF `--fs9`, and the reason the client in `src/9p.zig` is not a +/// library with no caller: one pardes serves acme's control filesystem over +/// 9P2000 on a unix socket, and this word is the second one reading it. `9p +/// work /1/body` shows you what pane 1 of the session called `work` is holding, +/// from a pane in this session, with no mount and no `plan9port` in the way. +/// +/// A DIAL IS A NAME OR A PATH: `work` resolves through the same +/// `fs9_service.socketPath` that bound it, and anything with a `/` in it is a +/// socket path taken as given. Unix sockets only for now — a 9P server across a +/// network is tunnelled (docs/9p.typ §10), and this word is not the place to +/// decide otherwise. +/// +/// It BLOCKS while it fetches, bounded by `fs9_client.budget_ms`, exactly the +/// way Look blocks on a disk read; `src/fs9_client.zig` argues that at length +/// and enforces it with a deadline rather than a promise. +pub const @"9p" = struct { + pub const takes_arg = true; + pub const enabled = fs9_client.supported; + /// Prose and not a list: the bytes are a file's, so n/N walks its words the + /// way it walks any document's, and there is nothing here to step to. + pub const output: OutputTraits = .{ .name = config.ninep_buffer, .doc = true }; + pub fn run(c: Ctx) void { + if (comptime enabled) apply(c) else unreachable; + } + fn apply(c: Ctx) void { + fs9_client.fetch(c.p, c.id, c.arg orelse "") catch |err| + c.p.reportError(c.id, "9p", err); + } +}; -- cgit v1.3