Add input module: broadcast keyboard events over IPC

Programs can now subscribe to keyboard events (key_down/key_up/key_press)
and drivers can broadcast them, through a new user-space input service.

The delivery model is forced by danos IPC: a synchronous rendezvous holds
one pending reply, so a server cannot park N subscribers blocked in a
"wait for next event" call — delivery must be push. But a synchronous push
has no timeout and the kernel never wakes a sender parked on a dead peer's
endpoint, so one dying subscriber would hang all input. So this lands the
roadmap's planned asynchronous buffered send and builds the service on it:

- ipc_send (syscall 26): non-blocking post to an endpoint's bounded payload
  ring, delivered through reply_wait as a buffered message (notify_message_bit).
  A full ring drops the oldest. It can never hang on a dead/slow peer.
- input-protocol + runtime.input helpers (subscribe/next, connectSource/
  publish) — the first real consumer of M13 capability passing: a subscriber
  hands the service its own endpoint as a capability.
- input service (fan-out via ipc_send, dead-subscriber pruning), a synthetic
  input-source, and input-test; the ps2-bus keyboard driver publishes to it.
  Real IRQ1 scancode decoding (which must live in the bus, the PNP0303 owner)
  is a documented follow-up; the source is synthetic for now.
- build/init wiring, an `input` QEMU case, and docs/input.md.

Full QEMU suite 48/48, including the new input case and every IPC/endpoint
regression (ipc, ipc-call, ipc-cap, vfs, hpet, bus, irqfree).

library/runtime/input.zig

@@ -0,0 +1,117 @@
+//! User-space input helpers: the client and publisher sides of the input service, so a
+//! program listening for keyboard events — or a driver broadcasting them — doesn't
+//! hand-roll the IPC. Layered over `ipc` (endpoints, capability passing, `send`) and the
+//! shared `input-protocol` wire format, the same way `device.zig` layers over the raw
+//! `device_*` calls. See system/services/input/input.zig.
+//!
+//! A **subscriber** does:
+//!     var listener = input.subscribe() orelse return;
+//!     while (true) { const event = listener.next() orelse continue; ... }
+//!
+//! A **source** (keyboard driver) does:
+//!     var source = input.connectSource() orelse return;
+//!     _ = source.publish(.{ .kind = ..., .keycode = ..., ... });
+
+const std = @import("std");
+const abi = @import("abi");
+const ipc = @import("ipc.zig");
+const system = @import("system.zig");
+const protocol = @import("input-protocol");
+
+pub const KeyEvent = protocol.KeyEvent;
+pub const EventKind = protocol.EventKind;
+pub const Keycode = protocol.Keycode;
+
+/// Look up the input service, retrying while it is still coming up. Both a subscriber and
+/// a source race the service's registration at boot, so both wait for it here rather than
+/// failing. Returns the service endpoint handle, or null if it never appears.
+fn lookupService() ?ipc.Handle {
+    var attempts: usize = 0;
+    while (attempts < 100) : (attempts += 1) {
+        if (ipc.lookup(.input)) |handle| return handle;
+        system.sleep(50);
+    }
+    return null;
+}
+
+/// A subscription to the input service: our own endpoint, which the service pushes events
+/// to. Keep it and call `next` in a loop.
+pub const Subscriber = struct {
+    /// The endpoint the service delivers events to (created and owned by us; its handle
+    /// was handed to the service as a capability at subscribe time).
+    endpoint: ipc.Handle,
+    receive: [protocol.event_size]u8 = undefined,
+
+    /// Block until the next event is pushed, and return it. Events arrive as asynchronous
+    /// buffered messages (`ipc_send` from the service), so nothing is owed in reply — the
+    /// empty reply this issues is a harmless no-op (a pure subscriber holds no client).
+    /// Returns null for any non-event wake-up (there should be none), so callers can loop.
+    pub fn next(self: *Subscriber) ?KeyEvent {
+        const got = ipc.replyWait(self.endpoint, &.{}, &self.receive, null);
+        if (!got.isMessage() or got.len < protocol.event_size) return null;
+        return std.mem.bytesToValue(KeyEvent, self.receive[0..protocol.event_size]);
+    }
+};
+
+/// Subscribe to keyboard events: create an endpoint for the service to push to, and hand
+/// it over as a capability. Returns a `Subscriber` to loop `next` on, or null on failure
+/// (the service never came up, out of handles, or the subscribe call failed).
+pub fn subscribe() ?Subscriber {
+    const service = lookupService() orelse return null;
+    const endpoint = ipc.createIpcEndpoint() orelse return null;
+
+    var request = protocol.Request{ .operation = @intFromEnum(protocol.Operation.subscribe), .event = undefined };
+    var reply: [protocol.reply_size]u8 = undefined;
+    const result = ipc.callCap(service, std.mem.asBytes(&request), &reply, endpoint) catch return null;
+    if (result.len < protocol.reply_size) return null;
+    const header = std.mem.bytesToValue(protocol.Reply, reply[0..protocol.reply_size]);
+    if (header.status != 0) return null;
+    return .{ .endpoint = endpoint };
+}
+
+/// A connection to the input service for a source (a keyboard driver) that publishes
+/// events. Cheap to hold; `publish` is a short synchronous call the service answers at
+/// once (its own fan-out to subscribers is asynchronous, so publishing never blocks on a
+/// slow subscriber).
+pub const Publisher = struct {
+    service: ipc.Handle,
+
+    /// Broadcast one event to every subscriber. Returns false if the call to the service
+    /// failed (e.g. the service is gone).
+    pub fn publish(self: Publisher, event: KeyEvent) bool {
+        var request = protocol.Request{ .operation = @intFromEnum(protocol.Operation.publish), .event = event };
+        var reply: [protocol.reply_size]u8 = undefined;
+        const len = ipc.call(self.service, std.mem.asBytes(&request), &reply) catch return false;
+        if (len < protocol.reply_size) return false;
+        return std.mem.bytesToValue(protocol.Reply, reply[0..protocol.reply_size]).status == 0;
+    }
+};
+
+/// Connect to the input service as an event source, waiting for it to come up. Returns a
+/// `Publisher`, or null if the service never registered.
+pub fn connectSource() ?Publisher {
+    return .{ .service = lookupService() orelse return null };
+}
+
+/// A tiny synthetic key-event generator, shared by the demo source and the keyboard
+/// driver's placeholder stream while real scancode decoding is still a follow-up. `step`
+/// is a monotonically increasing tick; the result rolls through the keys A..E, emitting
+/// for each one a `key_down`, then a `key_press` carrying the character, then a `key_up`.
+/// This is deliberately not wire protocol — it is scaffolding, so it lives with the
+/// helpers, not in `input-protocol`.
+pub fn syntheticEvent(step: usize) KeyEvent {
+    const Key = struct { code: Keycode, character: u32 };
+    const keys = [_]Key{
+        .{ .code = .a, .character = 'A' },
+        .{ .code = .b, .character = 'B' },
+        .{ .code = .c, .character = 'C' },
+        .{ .code = .d, .character = 'D' },
+        .{ .code = .e, .character = 'E' },
+    };
+    const key = keys[(step / 3) % keys.len];
+    return switch (step % 3) {
+        0 => .{ .kind = @intFromEnum(EventKind.key_down), .keycode = @intFromEnum(key.code), .character = 0, .modifiers = 0 },
+        1 => .{ .kind = @intFromEnum(EventKind.key_press), .keycode = @intFromEnum(key.code), .character = key.character, .modifiers = 0 },
+        else => .{ .kind = @intFromEnum(EventKind.key_up), .keycode = @intFromEnum(key.code), .character = 0, .modifiers = 0 },
+    };
+}

library/runtime/ipc.zig

@@ -79,6 +79,16 @@ pub fn call(h: Handle, message: []const u8, reply: []u8) CallError!usize {
     return (try callCap(h, message, reply, null)).len;
 }
 
+/// Post `message` to endpoint `h`'s asynchronous queue and return immediately — no
+/// rendezvous, no reply, no blocking. The receiver picks it up through `replyWait` as a
+/// buffered message (`Received.isMessage`). Unlike `call`, this **cannot hang on a dead
+/// or slow peer**, which is why a broadcaster (the input service) delivers events this
+/// way. The payload must fit an endpoint slot (64 bytes); a full queue drops the oldest
+/// message. Returns false on failure (bad handle, oversized payload, bad buffer).
+pub fn send(h: Handle, message: []const u8) bool {
+    return !failed(sc.systemCall3(.ipc_send, h, @intFromPtr(message.ptr), message.len));
+}
+
 /// Set in `Received.badge` when what arrived is an asynchronous notification — a
 /// bound device interrupt — rather than a client's message. The low bits carry the
 /// GSI. See `isNotification`.
@@ -89,6 +99,12 @@ pub const notify_badge_bit: u64 = abi.notify_badge_bit;
 /// rather than a device interrupt. The low bits carry the child's process id.
 pub const notify_exit_bit: u64 = abi.notify_exit_bit;
 
+/// Set alongside `notify_badge_bit` when the wake-up is a **buffered message** — a payload
+/// posted with `send` (`ipc_send`) — rather than a bare device interrupt or child-exit
+/// notice. The payload is in the `replyWait` receive buffer (`Received.len` bytes); the
+/// low bits of the badge carry the sender's task id. See `Received.isMessage`.
+pub const notify_message_bit: u64 = abi.notify_message_bit;
+
 /// The result of a `replyWait`: the request length, the sender's badge (a task id, or
 /// an IRQ notification if the high bit is set), and any capability the request carried.
 pub const Received = struct {
@@ -109,6 +125,19 @@ pub const Received = struct {
         return self.isNotification() and self.badge & notify_exit_bit != 0;
     }
 
+    /// True if this wake-up is a **buffered message** posted with `send` (`ipc_send`):
+    /// there is a payload in the receive buffer (`self.len` bytes) and no reply is owed.
+    /// The subscriber side of a broadcast branches on this.
+    pub fn isMessage(self: Received) bool {
+        return self.isNotification() and self.badge & notify_message_bit != 0;
+    }
+
+    /// The task id of whoever posted a buffered message, meaningful only when
+    /// `isMessage`. (The badge's low bits, with the three high marker bits masked off.)
+    pub fn senderTaskId(self: Received) u32 {
+        return @intCast(self.badge & ~(notify_badge_bit | notify_exit_bit | notify_message_bit));
+    }
+
     /// The interrupt source (a GSI), meaningful only when `isNotification` and
     /// not `isChildExit`.
     pub fn source(self: Received) u64 {

library/runtime/runtime.zig

@@ -16,6 +16,11 @@ pub const ipc = @import("ipc.zig");
 pub const start = @import("start.zig");
 /// The VFS wire protocol (shared with the VFS server).
 pub const vfs_protocol = @import("vfs-protocol");
+/// Keyboard-event listening (subscribe/next) and broadcasting (publish), over the input
+/// service. See library/runtime/input.zig and system/services/input/.
+pub const input = @import("input.zig");
+/// The input wire protocol (shared with the input service and its clients).
+pub const input_protocol = @import("input-protocol");
 /// POSIX-style file API: open/read/write/lseek/stat/close.
 /// C stdio: fopen/fread/fwrite/fseek/ftell/fclose over unistd.
 /// Device access for drivers: enumerate/claim/mmioMap.