library: five protocols speak the envelope

The folded header stops being a rule in a document and becomes the layout
on the wire. Verbs number from sixteen, leaving describe, enumerate,
subscribe and unsubscribe reserved and answered the same way by every
provider — none of them writes a line to do it. What each protocol used to
carry in a field of its own now travels in the header: a vfs node and a
display layer are the packet's target, and a reply opens with a status the
envelope stamps rather than one each protocol spelled for itself.

Display gains the most. One forty-byte request had served eleven verbs, so
attach_scanout smuggled stride through x, refresh through y and format
through colour, and every coordinate crossed as a bitcast. Per-operation
structs end all three: the fields have their own names and their own signs,
and the tile payload grows to 224 bytes because the prefix shrank. Scanout
loses a message maximum of 64 it had no business declaring — it answers
calls, and the floor for a call is 256 — and virtio-gpu stops hard-coding
that number at its harness.

Two changes are semantic rather than notational. A directory now ends at an
entry with no name, because the fixed part of a reply always travels and a
zero-length reply no longer exists to mean anything. And input joins the
service harness, the last loop in the tree that answered no ping and heard
no terminate; its subscriber table, its pruning and its fan-out are the
same code, and a shutdown now asks it to stop instead of killing it.

A new conformance case reads the registry's own listing and asks every
protocol it finds for its name, its version and its verb count, then offers
a verb nobody defines and requires -ENOSYS — the envelope's promise,
checked against providers rather than against itself. What it cannot reach
in that boot it names on the serial line instead of passing quietly.

Suite 110/110.

library/protocol/block/block-protocol.zig

@@ -1,51 +1,61 @@
 //! The block-device wire protocol — what a filesystem (the FAT server) says to a
-//! block driver (usb-storage) over its well-known `.block` endpoint. A protocol
-//! module like vfs-protocol / usb-transfer-protocol: extern-struct messages, an
-//! `Operation` tag, everything in one IPC message.
+//! block driver (usb-storage) over `/protocol/block`. Defined through the
+//! envelope, so every packet begins with the folded `Header`.
+//!
+//! **`Header.target` is always 0 here**: a block driver instance serves exactly
+//! one device over its own endpoint, so there is no object within the peer to
+//! address. A driver that later fronts several volumes gives them target ids and
+//! `enumerate` lists them; nothing else about the protocol changes.
 //!
 //! Data path: read and write move whole blocks to or from a **caller-owned DMA
 //! buffer**, named by its physical address — the same physical-address handoff
 //! usb-storage already uses toward the controller, one layer up. So a 512-byte
-//! sector never has to cross the 256-byte IPC boundary; only the small request /
-//! reply headers do. Under an enforcing IOMMU the buffer's physical addresses are
-//! only reachable by the device once the filesystem has `attach`ed the buffer's
-//! capability (the block server forwards it to the controller); see docs/driver-model.md.
+//! sector never has to cross the packet floor; only the small request / reply
+//! parts do. Under an enforcing IOMMU the buffer's physical addresses are only
+//! reachable by the device once the filesystem has `attach`ed the buffer's
+//! capability (the block server forwards it to the controller); see
+//! docs/driver-model.md.
 
-pub const Operation = enum(u32) {
-    /// geometry() -> { block_size, block_count }
-    geometry = 0,
-    /// read(lba, count, physical): read `count` blocks from `lba` into the buffer
-    read = 1,
-    /// write(lba, count, physical): write `count` blocks at `lba` from the buffer
-    write = 2,
-    /// flush(): commit any device write cache to stable media (no data transfer).
-    /// A filesystem calls this to make prior writes durable — e.g. before power-off,
-    /// so a shutdown-time write isn't lost in the USB flash controller's cache.
-    flush = 3,
-    /// attach(): the caller's DMA-region capability rides the call's cap slot; the
-    /// block server forwards it to the controller so the buffer's physical addresses
-    /// (named in later read/write) are reachable by the device under an enforcing
-    /// IOMMU. Call once per buffer before using it in a transfer.
-    attach = 4,
+const envelope = @import("envelope");
+
+/// The answer to `geometry()`.
+pub const Geometry = extern struct {
+    block_size: u32, // bytes per block (512)
+    _padding: u32 = 0,
+    block_count: u64, // total blocks
 };
 
-pub const Request = extern struct {
-    operation: u32,
-    reserved: u32 = 0,
+/// `read(lba, count, physical)` / `write(...)`: move `count` blocks between the
+/// device and the caller's DMA buffer at `physical`.
+pub const Transfer = extern struct {
     lba: u64,
-    count: u32, // number of blocks (read/write)
-    reserved2: u32 = 0,
-    physical: u64, // caller's DMA buffer physical address (read/write)
+    count: u32,
+    _padding: u32 = 0,
+    physical: u64, // caller's DMA buffer physical address
 };
 
-pub const Reply = extern struct {
-    status: i32, // 0 on success, negative on failure
-    reserved: u32 = 0,
-    block_size: u32, // geometry: bytes per block (512)
-    reserved2: u32 = 0,
-    block_count: u64, // geometry: total blocks; read/write: blocks moved
-};
+/// How many blocks a transfer actually moved.
+pub const Transferred = extern struct { count: u32 };
 
-pub const message_maximum: usize = 256;
-pub const request_size: usize = @sizeOf(Request);
-pub const reply_size: usize = @sizeOf(Reply);
+pub const Protocol = envelope.Define(.{
+    .name = "block",
+    .version = 1,
+    .operations = &.{
+        .{ .name = "geometry", .reply = Geometry },
+        .{ .name = "read", .request = Transfer, .reply = Transferred },
+        .{ .name = "write", .request = Transfer, .reply = Transferred },
+        // flush(): commit any device write cache to stable media (no data
+        // transfer). A filesystem calls this to make prior writes durable —
+        // before power-off, so a shutdown-time write isn't lost in the USB flash
+        // controller's cache.
+        .{ .name = "flush" },
+        // attach(): the caller's DMA-region capability rides the call's cap
+        // slot; the block server forwards it to the controller so the buffer's
+        // physical addresses (named in later read/write) are reachable by the
+        // device under an enforcing IOMMU. Call once per buffer before using it.
+        .{ .name = "attach" },
+    },
+});
+
+pub const Operation = Protocol.Operation;
+pub const message_maximum: usize = Protocol.message_maximum;