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/device/block/block.zig

@@ -7,12 +7,14 @@
 //! `runtime.dma.alloc`), so whole sectors move without crossing the IPC size
 //! limit — the same handoff usb-storage uses toward the controller.
 
-const std = @import("std");
 const channel = @import("channel");
+const envelope = @import("envelope");
 const ipc = @import("ipc");
 const time = @import("time");
 const block_protocol = @import("block-protocol");
 
+const Protocol = block_protocol.Protocol;
+
 pub const Geometry = struct { block_size: u32, block_count: u64 };
 
 pub const Device = struct {
@@ -20,12 +22,9 @@ pub const Device = struct {
 
     /// The device's block size and total block count.
     pub fn geometry(self: Device) ?Geometry {
-        var request = block_protocol.Request{ .operation = @intFromEnum(block_protocol.Operation.geometry), .lba = 0, .count = 0, .physical = 0 };
-        var reply: [block_protocol.reply_size]u8 = undefined;
-        const n = ipc.call(self.endpoint, std.mem.asBytes(&request), &reply) catch return null;
-        if (n < block_protocol.reply_size) return null;
-        const result = std.mem.bytesToValue(block_protocol.Reply, reply[0..block_protocol.reply_size]);
-        if (result.status != 0) return null;
+        var reply: [block_protocol.message_maximum]u8 = undefined;
+        const answered = self.call(.geometry, {}, null, &reply) orelse return null;
+        const result = Protocol.decodeReply(.geometry, answered) orelse return null;
         return .{ .block_size = result.block_size, .block_count = result.block_count };
     }
 
@@ -34,36 +33,45 @@ pub const Device = struct {
     /// addresses become reachable by the device. Call once per buffer before naming it
     /// in `read`/`write`. Harmless success when no IOMMU is enforcing.
     pub fn attach(self: Device, handle: ipc.Handle) bool {
-        var request = block_protocol.Request{ .operation = @intFromEnum(block_protocol.Operation.attach), .lba = 0, .count = 0, .physical = 0 };
-        var reply: [block_protocol.reply_size]u8 = undefined;
-        const result = ipc.callCap(self.endpoint, std.mem.asBytes(&request), &reply, handle) catch return false;
-        if (result.len < block_protocol.reply_size) return false;
-        return std.mem.bytesToValue(block_protocol.Reply, reply[0..block_protocol.reply_size]).status == 0;
+        var reply: [block_protocol.message_maximum]u8 = undefined;
+        return self.call(.attach, {}, handle, &reply) != null;
     }
 
     /// Read `count` blocks starting at `lba` into the DMA buffer at `physical`.
     pub fn read(self: Device, lba: u64, count: u32, physical: u64) bool {
-        return self.transfer(.read, lba, count, physical);
+        var reply: [block_protocol.message_maximum]u8 = undefined;
+        return self.call(.read, .{ .lba = lba, .count = count, .physical = physical }, null, &reply) != null;
     }
 
     /// Write `count` blocks starting at `lba` from the DMA buffer at `physical`.
     pub fn write(self: Device, lba: u64, count: u32, physical: u64) bool {
-        return self.transfer(.write, lba, count, physical);
+        var reply: [block_protocol.message_maximum]u8 = undefined;
+        return self.call(.write, .{ .lba = lba, .count = count, .physical = physical }, null, &reply) != null;
     }
 
     /// Commit any device write cache to stable media (SCSI SYNCHRONIZE CACHE), so
     /// prior writes survive a power-off. A filesystem calls this before the machine
     /// goes down; no data transfer, so the buffer arguments are unused.
     pub fn flush(self: Device) bool {
-        return self.transfer(.flush, 0, 0, 0);
+        var reply: [block_protocol.message_maximum]u8 = undefined;
+        return self.call(.flush, {}, null, &reply) != null;
     }
 
-    fn transfer(self: Device, operation: block_protocol.Operation, lba: u64, count: u32, physical: u64) bool {
-        var request = block_protocol.Request{ .operation = @intFromEnum(operation), .lba = lba, .count = count, .physical = physical };
-        var reply: [block_protocol.reply_size]u8 = undefined;
-        const n = ipc.call(self.endpoint, std.mem.asBytes(&request), &reply) catch return false;
-        if (n < block_protocol.reply_size) return false;
-        return std.mem.bytesToValue(block_protocol.Reply, reply[0..block_protocol.reply_size]).status == 0;
+    /// One request at the driver. `target` is always 0: one endpoint per device, so
+    /// there is no object within the peer to address.
+    fn call(
+        self: Device,
+        comptime operation: Protocol.Operation,
+        request: Protocol.RequestOf(operation),
+        capability: ?ipc.Handle,
+        reply: []u8,
+    ) ?[]u8 {
+        var packet: [block_protocol.message_maximum]u8 = undefined;
+        const framed = Protocol.encodeRequest(operation, 0, request, &.{}, &packet) orelse return null;
+        const answer = ipc.callCap(self.endpoint, framed, reply, capability) catch return null;
+        const status = envelope.statusOf(reply[0..answer.len]) orelse return null;
+        if (status.status != 0) return null;
+        return reply[0..answer.len];
     }
 };
 

library/device/build.zig

@@ -99,6 +99,7 @@ pub fn build(b: *std.Build) void {
         .root_source_file = b.path("block/block.zig"),
         .imports = &.{
             .{ .name = "channel", .module = channel },
+            .{ .name = "envelope", .module = protocol.module("envelope") },
             .{ .name = "ipc", .module = ipc },
             .{ .name = "time", .module = time },
             .{ .name = "block-protocol", .module = protocol.module("block-protocol") },