Protocols & ABI

Relevant source files

• docs/reference/generated/abi.md 
• kernel/crates/kernel_abi/src 
• kernel/src/syscall/mod.rs 
• kernel/src/arch/idt.rs 
• kernel/src/arch/aarch64/exceptions.rs 
• docs/architecture/protocols/rk-bridge.md 
• userspace/tools/rk_bridge/src/input.rs 
• kernel/crates/shrike_link/src/lib.rs 
• kernel/crates/shrike_link/src/watchdog.rs 
• kernel/crates/shrike_link/src/session.rs 
• kernel/crates/shrike_link/src/handoff.rs 
• kernel/crates/shrike_link/src/installer.rs 
• kernel/crates/kernel_abi/src/managed.rs 
• kernel/crates/kernel_abi/src/recorder.rs 
• kernel/src/syscall/managed.rs 

axiomos exposes three wire-level contracts: the userspace syscall ABI, a newline-delimited JSON stream for bridging BPF events to a host (rk-bridge), and a binary UART control link between the Pi 5 and the Shrike RP2040 board. The feat/v0.5-runtime branch extends the syscall ABI with versioned managed-runtime commands, extends the control link with session/handoff messages, and adds a fourth contract: the framed debug-UART installer protocol.

Syscall ABI v1

The generated ABI catalog  contains only interfaces dispatched by shipped kernels; reserved numbers, verifier-known but undispatched helpers, and verifier-cost instrumentation are not supported ABI. Numbers are defined in kernel_abi and dispatched by dispatch_syscall in kernel/src/syscall/mod.rs . On x86_64 the entry is interrupt vector 0x80; on AArch64 it is the svc synchronous exception.

Errors follow ADR-0002: subsystem errors stay typed and are mapped to Errno once, in the syscall adapter. Unknown syscalls return ENOSYS (checked by the UNKNOWN_SYSCALL_ENOSYS_OK gate marker) and bad user pointers return EFAULT.

sys_bpf surface

SYS_BPF multiplexes BPF commands: map create/lookup/update/delete (0 to 3), BPF_PROG_LOAD (5), pin/get (6, 7), attach/detach (8, 9), BPF_OBJ_GET_INFO_BY_FD (15), BPF_PROG_LOAD_ELF (36), BPF_RINGBUF_POLL (37), and axiomos extensions BPF_PROG_UNLOAD (101), BPF_MAP_DESTROY (102), BPF_OBJ_UNPIN (103). Map types, helpers and attach types are documented in the eBPF Subsystem section. Managed-runtime commands are listed below. Attach type numbers from kernel_abi:

Managed-runtime commands (managed-runtime feature)

The branch adds independently versioned SYS_BPF commands (kernel_abi/src/managed.rs , recorder.rs ). They are dispatched by syscall/managed.rs  before the legacy full-BpfAttr size check, require BPF_CAP_BEHAVIOR_ADMIN, copy bounded caller buffers, and reject unknown versions, wrong sizes and nonzero reserved fields. MANAGED_ADMIN_VERSION is 1.

Operation states are IDLE, UPLOADING, QUEUED, PREPARING, RESIDENT, FAILED, CANCELLED, STAGED, HANDOFF, COMMITTED and CLEANUP. Lifecycle targets are CANDIDATE (1), PREVIOUS (2), DEACTIVATE (3), RETIRE (4) and REARM (5). The generated ABI catalog also lists helper 1009 (BPF_HELPER_MANAGED_MOTOR_PAIR_V1, managed interpreter only), which captures one wheel-pair request and never actuates directly. Managed programs receive the 56-byte ManagedControlContextV1 (version, size, cycle_id, scheduled/actual/sensor timestamps in ns, raw sensor_value, sensor_valid). Details are in Lifecycle and Executor.

BPF_CAP_BEHAVIOR_ADMIN (1 << 11) is a new capability bit. It grants no legacy load, attach, map mutation, privileged verification or actuation authority, and legacy init does not receive it.

rk-bridge NDJSON stream

rk_bridge resolves pinned BPF objects through sys_bpf, which only exists on a running axiomos kernel. To get the same events into a ROS 2 graph on a developer host, rk_uart_forwarder (running on axiomos, launched from init) writes newline-delimited JSON to stdout, which is the UART, and the host runs rk-to-ros --input stdin.

socat /dev/ttyUSB0,raw,echo=0,b1500000 STDOUT \
  | rk-to-ros --input stdin --topic /rk/sched_switch

{"type":"meta","protocol":1,"source":"sched_switch"}
{"type":"ready","map_fd":3}
{"type":"sched_switch","seq":1,"cpu":0,"prev_pid":1,"prev_tid":1,"next_pid":2,"next_tid":2}

Consumer rules: skip lines not starting with { (tolerates kernel log noise), reject an unknown protocol version, ignore unknown record types and fields, treat a malformed line as recoverable, and stop cleanly at end of stream. There is no reliability layer: at 1.5 Mbit/s and about 120 bytes per event the ceiling is roughly 1500 events/s, and seq only detects gaps. Records for sys_enter, sys_exit, gpio, pwm and iio are anticipated but must be added to WireRecord before a host can decode them. The protocol is explicitly a stop-gap; the long-term target is Ethernet (#67) with a DDS-shaped transport.

Shrike-link UART control link

shrike_link is a no_std, zero-dependency, host-tested codec shared by the kernel (Pi 5 side) and the RP2040 firmware.

SYNC(0x7E) VER(0x01) TYPE LEN PAYLOAD[LEN] CRC_LO CRC_HI
CRC16-CCITT/FALSE over VER, TYPE, LEN, PAYLOAD; MAX_PAYLOAD = 16

The decoder is a byte-fed state machine: only the Idle state treats 0x7E as SYNC; once LEN is accepted, payload and CRC are consumed by count, so no byte stuffing is needed. LEN must match each type’s fixed payload length.

The branch messages carry a little-endian u32 session (4-byte payload) or session, u64 correlation and u8 sequence (13-byte payload). A zero session or correlation is rejected as BadIdentity on both encode and decode. They implement the acknowledged safe handoff (barrier/ack) and explicit rearm (Requalify, Prepared, Offer, Ready); see Handoff & Rearm.

Safety behavior lives in pure, host-tested state machines rather than in drivers:

• Shrike-side watchdog (watchdog.rs): output is SafeStop on cold start, after command silence beyond a timeout (heartbeats cannot extend motor authority), and while a soft e-stop is latched. A MotorSetpoint whose seq is not newer than the last accepted one is rejected (anti-replay).

• Pi-side session (session.rs): heartbeats the RP2040 while inbound traffic is alive; when inbound goes silent it stops heartbeating (so the RP2040 watchdog trips) and retries a one-shot e-stop every tick until the transport confirms it was sent.

• Handoff state (handoff.rs, branch): shared by the Pi poller and the managed timer. At a release boundary it inhibits the old controller, discards unsent motion, sends a prioritized SafeBarrier after any started frame, and only a matching SafeAck received after whole-frame transmission produces a publication receipt. The 80 ms handoff timeout includes the acknowledgement wait.

Installer frames (debug UART, branch)

installer.rs is a separate fixed-size transport, outside the actuator message namespace, used between host rk runtime and the in-guest installer over the Pi debug UART.

MAGIC(0xA5) KIND<<4|LEN SEQ[4, LE] DATA[8] CRC16[2, LE]   = 16 bytes
KIND: Request(0) RequestLast(1) Poll(2) Reset(3) Ack(8) Response(9) ResponseLast(10) Error(11)
MAX_MESSAGE_BYTES = 320

One frame is sent per credit; the installer replays exact duplicate requests without redispatch, rejects stale or altered identities, and requires Reset after receive faults. See Installer.