Skip to Content
Viewing feat/v0.5-runtime docs — not the stable branch. Changes vs main · Go to main
axiomOSfeat/v0.5-runtimeChanges from main

Changes from main

Relevant source files

Summary

Branch feat/v0.5-runtime is 108 commits ahead of main and touches about 222 files (+50,351 / -1,890 lines). It implements the accepted v0.5 “bounded runtime evolution” contract: a managed controller slot on the Raspberry Pi 5 that runs one signed, verified eBPF controller at an absolute 100 Hz release grid and can be uploaded, activated, rolled back, deactivated, retired and audited after boot, with every transition passing through an MCU-acknowledged safe-output boundary.

Unmerged. The branch completes the planned M1 software prerequisites and M2 to M6 software with host/model tests. Physical qualification (deferred M1 electronics and the M7 campaign) has not run, physical actuation stays disabled, and the default runtime profile and FPGA artifact remain None.

New architecture

On main, controllers are legacy BPF programs attached to hooks (TIMER, IIO, GPIO) and fanned out by hook snapshots. On this branch the managed controller is a separate object type that ordinary hooks and the JIT cannot accept; legacy hook execution is unchanged outside managed-mode restrictions.

Changed areas

AreaChangePage
Managed runtime (new)Control slot, artifacts/instances/installations, worker, retirementRuntime overview, Lifecycle
Bundle format (new)AXMB v1 bundle, managed verifier, helper 1009, ManagedControlContextV1Managed Bundles
SchedulingAbsolute 100 Hz CPU0 release grid (kernel_time::periodic), missed/late accounting, sticky timer faultExecutor, Scheduling and Locking
Control linkSessionOffer/Ready, SafeBarrier/Ack, Requalify/Prepared messages; whole-frame reverse TX; PL011 bounded resetSafe Handoff and Rearm, Protocols
Management ABI14 versioned SYS_BPF commands, BEHAVIOR_ADMIN capability, installer debug-UART framingInstaller
AuditBounded kernel recorder, audit-export, offline decoderAudit Recorder
VerifierFallible bounded budgets, branch-join stack-depth fix, managed entry, map helper extent checksVerifier
LoaderStricter legacy ELF rejection (one map-free entry, relocation validation)Loader
InterpreterALU32/shift and endian semantics aligned with verifier; managed invocation captureExecution and JIT
TrustFull signer identity retained; AXMB authentication; object ownersTrust Model
MemoryHeap lock access masks local IRQsMemory
Pi 5 platformManaged timer path, sensor snapshot, PL011 quiescence, rearm coordinatorRaspberry Pi 5
Firmware / FPGARP2040 transport, requalification, real UART/SPI/input adapters, verified bitstream streaming, R0.4 RTL/pins/timingDrivers, Hardware-in-the-loop
Toolsrk bundle, rk runtime, rk audit-decode, signed_bpf_loader library + installer + syscall probeTools
ExamplesThree managed C controllersManaged Bundles
Verificationv0.5 host runner, reducers, audit stitcher, Shrike bench capture, FPGA preflights, CI changesAcceptance and Qualification, CI, Tests
Security docsUnsafe ledger refresh, verifier assurance updatesUnsafe Code, Verifier Assurance

No pages were removed: the branch adds subsystems but deletes no tracked files.

Notable commits

CommitDescription
01766ceFreeze runtime contract and host acceptance checks (M0)
8d27130Authenticate bounded managed controller bundles
c977440Retain maximum stack depth across branch joins (verifier fix)
f40a964Add narrow BEHAVIOR_ADMIN authority
1f334bdBound verifier buffer allocation and failure recovery
e44dc70Separate object lifetime from process identifiers
3438690Reject ambiguous legacy ELF composition
2111f87Verify and capture bounded managed invocations
0bb53c2Own bounded managed instances with fresh private state
291b810Prepare bounded managed uploads in kernel worker
4e4f20cMask local IRQs around heap lock access
6e8ff84 / 41e8384Lifecycle worker, absolute releases, managed controller execution
9335e6aGate publication on correlated safe handoff
d176e5f / f1249aaDeactivation and inactive-artifact retirement
49bf178Bounded debug-UART installer workflow
70aaa77Managed bundle authoring and controller examples
ab024ca / 1db9b29Recorder retention core and offline trace decoder
824c833 / 70b4a32FPGA configuration streaming and runtime SPI transactions on the MCU
89ef8a5Integrate R0.4 RTL timing and pin contracts
3f5badfCoordinate explicit rearm over bounded UART
c0c0d01 / d35236aMap helper input extent and aliasing fixes
016dcf0 / c1e1a5cPhysical acceptance reduction and evidence binding
90734303Document rearm ABI and shipped audit decoding

Migration notes

  • Opt-in. All managed functionality is behind the managed-runtime feature (root: managed-runtime for x86_64, managed-runtime-aarch64 for AArch64). Images built without it keep the main behavior.
  • Pi 5 managed build: AXIOM_BPF_TRUSTED_KEY_PATH=... bash scripts/build/rpi5.sh release embedded-rpi5,managed-runtime. This builds the managed init and installer into the rootfs.
  • Controllers use AXMB, not RBPF. Use rk bundle to sign raw instruction streams; rk runtime upload rejects the legacy signed ELF. Legacy rk sign / RBPF loading still works for hook programs.
  • Legacy ELF loading is stricter. Programs must have exactly one map-free entry; unsupported relocation types, RELA, multiple symbol tables and inconsistent string tables reject before publication. BPF-to-BPF call relocations are still supported.
  • Legacy mutation is restricted while managed control owns the wheel pair: legacy BPF mutation syscalls and consuming ring-buffer reads return errors; ordinary userspace commands to the managed pair are rejected.
  • Capabilities. BEHAVIOR_ADMIN is new; legacy init receives none, and administration grants no actuation.
  • Managed images drop generic TIMER fanout and synchronous timer diagnostics.
  • Operational guards unchanged. fpga-runtime remains disabled; physical activation requires the deferred qualification.
Last updated on