Enumeration was the one operation the interface did not have, and the one a
capability interface owes an explanation for: a listing is the opposite of
"knowing a coordinate is the authorisation to use it". So the walk is bounded
and explicit. A caller names the space, holds a cursor, and gets as many whole
records as fit in the buffer it offered, packed `key(24) | value_len(u32) | value`
in the store's own order. SPACES walks the distinct spaces that hold a record,
one per call; range is that walk with the region as a filter, applied by the
caller rather than by a second operation in the kernel.
Its own argument block, versioned by its own size: SYSCALL_DEFINE2 peeks `size`
and routes — 80 bytes is the coordinate block, 64 is this one. An interface that
cannot grow has to be replaced, and this one grows by being given a new block.
The end of a walk is the cursor alone. A batch holds as many whole records as
fit, so it is FULL only when a record lands on the boundary and most batches
come back short; a caller that reads "the buffer was not filled" as "the space
is exhausted" truncates its listing to the first batch and cannot tell. ENUM
answers a finished walk with no records and the cursor unmoved; SPACES answers
it with -ENOENT, because the space after the last one is not there. That rule is
in the uapi header because it is a contract detail, not an implementation one.
The kernel caches no merged index: each call walks the records in order, asks
the log — small, and the only thing that can override one — what the winner is,
and skips what the cursor has already covered. O(records) a call, tens of
milliseconds for the live store, which is worth more than a cache every write
would have to invalidate.
The store's sort no longer lives on the kernel stack (heapsort, see the parent
commit's gate), and the release is now 6.19.3-cubelinux0.6 instead of
CUBELinux.0.6 — depmod/mkinitramfs reject a version whose first character is
not numeric, so the literal name cannot be uname -r. The box's own kernel uses
the same shape (6.19.3-cube+); this is the same concession.
The write path was proven but unreachable: its operations lived behind a device
node. This is the interface the decision chose (DESIGN-cube-interface.md) — one
syscall number, an opcode, and a versioned argument block, with operations that
are the verbs the command language already defines: put, get, del, sync.
long cube(unsigned int op, struct cube_args __user *args)
`size` comes first and is checked, because syscall numbers are permanent and an
interface that cannot grow would have to be replaced. A coordinate is the space and
its three axes; nothing here resolves a name and nothing enumerates.
Split deliberately: the entry point, the user copies and the argument validation are
in C (cube_syscall.c) because `SYSCALL_DEFINE*` is a C macro this kernel has no Rust
equivalent for; everything that touches the store's bytes is in Rust, which passes
the coordinate to the format code as its parts so that Morton encoding stays in the
one module that must get it exactly right. A read that does not fit returns the size
it needs rather than truncating — a short read would be worse than an error.
Number 548: the x86_64 table says numbers 548 and above are available for
non-x32 use.
Gate (kernel/verify-syscall.sh): a static client in the initramfs does four writes
(including an empty value and a second space), reads one back *through the same
interface*, and folds with `sync`. Three different failures are separated — the
calls failing (a broken ABI), a read not returning what a write stored (a wrong key
encoding or index), and the folded image differing (a wrong format, order or merge).
put 7,0,0 ok (21 bytes)
put 8,0,0 ok (0 bytes)
put 9,0,0 ok (28 bytes)
put 1,2,3 ok (13 bytes)
get 7,0,0 21 bytes: the kernel wrote this
sync ok
and the image left on the device is byte-identical to the one userspace writes from
the same mutations, with the log empty. The interface's store is the same store.
All nine gates pass on 0.6.
surface-camera-build