diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/design.md | 55 |
1 files changed, 51 insertions, 4 deletions
diff --git a/docs/design.md b/docs/design.md index 2013b3e..dda10a6 100644 --- a/docs/design.md +++ b/docs/design.md @@ -66,6 +66,52 @@ identity verification must provide that policy before using it across a trust boundary. OpenSSL allocations and handshake costs are outside the allocation-free protocol core. Accepted connections must close before their shared listener. +# File server engine + +`fs.Server(Backend, Options)` is a file server built on `Server`: it owns the +fid table, permission checks, the directory-read cursor, flush and hangup, and +asks a backend only for filesystem operations. The backend contract is +`fs.Req` (`Op`: lookup, getattr, setattr, open, read, write, release, readdir; +each names a node, and open/read/write/readdir/release carry the handle open +returned) answered by `fs.Reply` (`Status`, an errno from `fs.E`, `fs.Attr`, +the open handle, the written count) with a read's or readdir's bytes passed +beside the reply. `fs.ReplyWith(Payload)` is the same reply carrying an +application-defined locator for those bytes, which the engine ignores; a +backend declares `Req` and `Reply` as those types. A readdir answers records +of `node:u64le dir:u8 len:u8 name`, which the engine encodes into whole Stat +entries directly in the output frame. + +Every 9P request is a job: attach, walk, open, read, readdir, write, clunk, +remove, stat and wstat become one or more backend requests issued in order +(a walk asks one lookup per element; an open with OTRUNC asks setattr then +open; a clunk of an open fid asks release). `next()` yields the next backend +request and null while one is outstanding, the output is full, or no whole +frame has arrived; the backend answers by the request's tag through +`reply()`, at once or later. Tags are unique per connection and never zero. +A stale tag (flushed, hung up) is ignored; the backend must retire canceled +work before answering. + +A read, readdir or write may answer `Status.again`: the job parks in a slot, +the engine moves on, and `retry()` re-issues each parked request once per +round, oldest first, until it completes; a parked write keeps a copy of its +data up to `park_data_max` bytes. Any other operation answering `again`, or +a park with no free slot, fails with EAGAIN. Tflush answers a parked +request's tag with EINTR before its Rflush and drops the slot; a flush of an +unknown tag is just Rflush. `hangup()` marks every open fid orphaned and +`next()` then yields the release each one owes before anything else, so a +dropped connection still pays the backend; a Tversion does the same before +negotiating. + +Every table is sized at comptime by `fs.Options`: `fid_capacity` (256), +`slot_capacity` (32), `park_data_max` (128), `name_capacity` (28, at most +255) and `username_capacity` (28); the defaults are the editor's, except the +name capacity, which is the board's. `msize_min` (217) is the smallest +negotiable msize, one full Rwalk. Create, remove, auth, attaching a named +tree and any wstat other than a zero-length truncation are refused. Rerror +strings are the ones Linux v9fs maps back to errnos (`fs.errString`). The +engine allocates nothing and makes no OS calls; a session is `push()`, +`retry()`, `next()`, `reply()`, `output()`, `wrote()`. + # Related programs Programs built on the library ship from this repository as `cloud9/<name>/`, @@ -83,12 +129,13 @@ programs follow this layout. # Pardes integration -Pardes consumes the sibling package through build.zig.zon. Its `src/9p.zig` now -adapts filesystem requests and retains editor/GPIO capacities and permissions. +Pardes consumes the sibling package through build.zig.zon. Its control tree +(`src/ninep/`) is an `fs.Server` backend using the contract types above; its +`src/9p.zig` names the editor's and the board's `fs.Options`. `src/9p_io.zig` retains mounting, discovery, the editor's event-loop scheduling, connection limits, and error presentation. Protocol bytes, session validation, -and TCP/Unix/QUIC transport implementation come from cloud9. Pardes selects the -existing `pardes-9p` ALPN for compatibility. +the file-server engine, and TCP/Unix/QUIC transport implementation come from +cloud9. Pardes selects the existing `pardes-9p` ALPN for compatibility. The separate `05-zig-p4` firmware build adds cloud9 to the GPIO application's module map. UART hardware access remains in the board firmware. No hardware was |