surface-camera-build
b9a7b8d8f3
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.
76 lines
3.3 KiB
C
76 lines
3.3 KiB
C
/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
|
|
/*
|
|
* CUBELinux: the coordinate interface.
|
|
*
|
|
* The kernel's native interface to the store. Operations are the verbs the command language
|
|
* already defines — one language, and this is its kernel form (DESIGN-cube-interface.md).
|
|
*
|
|
* A coordinate is not a name and not a path: it is *where* a record is, and knowing it is the
|
|
* authorisation to use it. Nothing here resolves a name, and nothing enumerates.
|
|
*/
|
|
#ifndef _UAPI_LINUX_CUBE_H
|
|
#define _UAPI_LINUX_CUBE_H
|
|
|
|
#include <linux/types.h>
|
|
|
|
/* Which cube, and where in it. 32-byte space: unguessable, deliberately. */
|
|
struct cube_coord {
|
|
__u8 space[32];
|
|
__u64 x;
|
|
__u64 y;
|
|
__u64 z;
|
|
};
|
|
|
|
/*
|
|
* The argument block. `size` first, and checked: an interface that cannot grow is an
|
|
* interface that has to be replaced, and syscall numbers are permanent.
|
|
*/
|
|
struct cube_args {
|
|
__u32 size; /* sizeof(struct cube_args) as the caller built it */
|
|
__u32 op; /* CUBE_OP_* */
|
|
struct cube_coord coord; /* unused by CUBE_OP_SYNC */
|
|
__u64 value; /* user pointer: bytes to write, or where to put them */
|
|
__u64 len; /* in: bytes offered, or the buffer's capacity.
|
|
* out: on -ERANGE, the bytes that would be needed;
|
|
* on success for CUBE_OP_GET, the bytes read.
|
|
*/
|
|
};
|
|
|
|
#define CUBE_OP_PUT 1 /* store bytes at a coordinate */
|
|
#define CUBE_OP_GET 2 /* read them back */
|
|
#define CUBE_OP_DEL 3 /* remove the record */
|
|
#define CUBE_OP_SYNC 4 /* fold the log into the image */
|
|
#define CUBE_OP_ENUM 5 /* walk the records of a space, in batches */
|
|
#define CUBE_OP_SPACES 6 /* walk the spaces that hold records */
|
|
|
|
/*
|
|
* The walk's argument block: its own block rather than a wider `cube_args`, because it needs a
|
|
* cursor and a buffer, and the coordinate would otherwise be both an input and an output.
|
|
*
|
|
* Records are packed as `key(24) | value_len(u32, little-endian) | value`, in the store's own
|
|
* order — space first, then key — which is the order a checkpoint writes them and the order the
|
|
* userspace store returns them, so a kernel listing and a userspace listing can be compared
|
|
* directly. The space is not repeated per record: the caller named it.
|
|
*
|
|
* A walk ends when the cursor stops moving, and that is the only end signal: a batch holds as
|
|
* many whole records as fit, so most batches come back short, and reading a short batch as the
|
|
* end truncates a listing to its first batch. CUBE_OP_ENUM answers a finished walk with no
|
|
* records and the cursor unchanged; CUBE_OP_SPACES answers it with -ENOENT, because asking for
|
|
* the space after the last one is asking for a space that is not there. -ERANGE keeps its usual
|
|
* meaning: not one whole record fits, and `len` says how much one needs.
|
|
*/
|
|
struct cube_enum_args {
|
|
__u32 size; /* sizeof(struct cube_enum_args) as the caller built it */
|
|
__u32 op; /* CUBE_OP_ENUM or CUBE_OP_SPACES */
|
|
__u8 space[32]; /* in: the space to walk; out: the space found (CUBE_OP_SPACES) */
|
|
__u64 cursor; /* in: 0 to start, or what the last call returned;
|
|
* out: what to pass next — see the end-of-walk rule above
|
|
*/
|
|
__u64 value; /* user pointer: where to put the records */
|
|
__u64 len; /* in: the buffer's capacity;
|
|
* out: bytes written, or on -ERANGE what would be needed
|
|
*/
|
|
};
|
|
|
|
#endif /* _UAPI_LINUX_CUBE_H */
|