The Kore ABI

A contract, not a library#

kore-abi is the narrow waist between Kore and everything above it: the types and layouts that cross the boundary, and nothing else. It carries no kernel behavior. There is no stamping key in it, no revocation closure and no derive, revoke or verify logic. A program that links it can describe requests and read capability fields, but it cannot perform an authority operation, because that logic isn't in the crate.

The crate is no_std, forbids unsafe code and depends only on bitflags and zerocopy. The kernel builds its own typed view of a capability on these same wire types, so the two sides can't drift apart on a layout. A drift would be a security bug, not a style problem.

Two transports, split by what moves#

Because a completion can't carry a capability, no asynchronous authority state can exist. Mapping a device register window, mapping DMA or programming an interrupt are session operations, batched per flow into one crossing, never ring traffic.

One gate into the kernel#

Every kernel effect is a session commit. A program stages a descriptor, traps once and reads results from its own arena slots. There are no system call numbers and no system call table: each architecture has one trap, and the kernel funnels it into a single commit entry. The caller's identity is the current thread, never a register.

A small session rides in the payload registers: the control word sets bit 63 and holds the descriptor length in its low byte. A larger one is staged in the task's descriptor scratch window, and the control word gives its offset. The kernel snapshots a scratch descriptor once, so a sibling thread can't rewrite it between validation and commit.

The return word packs the session's status in bits 0–15, the index of the failing operation in bits 16–31 and the kernel's monotonic clock in milliseconds (mod 2³²) in bits 32–63. Decoding is fail-closed: an unknown status reads as Malformed.

The wire freeze#

The surface is frozen at ABI_VERSION = 1. That covers cap, session, device and mem (memory and devices), task, image, uring and clock. After the freeze, changes are additive only:

• New op-code, status and flag values, and new meanings for reserved fields, are allowed.
• Reordering, resizing or changing a field's type is not.
• The io_uring byte compatibility is part of the freeze: those layouts track the Linux wire, not a Kore-private one.

Wire structs are size-pinned, and most are offset-pinned, by const assertions in each module. Sub-surfaces carry their own version stamps that do advance, and a mismatch fails closed rather than being reinterpreted:

Module map#