Skip to Content
Viewing feat/fpga-bringup docs — not the stable branch. Changes vs main · Go to main
axiomOSfeat/fpga-bringupeBPF SubsystemOverview

eBPF Subsystem

Relevant source files

The axiomOS eBPF subsystem lets user-supplied, verified bytecode run synchronously inside kernel hooks (timer tick, syscall entry and exit, scheduler switch, GPIO and IIO events). It is split into a no_std library crate, kernel_bpf, that provides mechanisms (loader, verifier, interpreter, maps, signing, actuation policy) and a kernel-side integration layer, kernel/src/bpf, that owns policy (authorization, quotas, handles, hook snapshots).

Execution is interpreter-only. No shipped profile enables a JIT (see Execution and JIT).

Crate layout

LocationRole
kernel/crates/kernel_bpf/src/bytecodeRaw instructions, opcodes, registers, and the BpfProgram / VerifiedProgram representations
kernel/crates/kernel_bpf/src/loaderELF64 parser, relocations, subprogram call normalization
kernel/crates/kernel_bpf/src/verifierCFG, register/stack state, tnum, pruning, liveness, helper registry, WCET cost model, admission ledger
kernel/crates/kernel_bpf/src/executionInterpreter, BpfContext, hook context structs; non-shipped compilers
kernel/crates/kernel_bpf/src/mapsArray, hash, ring buffer, time-series maps
kernel/crates/kernel_bpf/src/attachAttach metadata types (GPIO, IIO, PWM, kprobe, tracepoint) and the GPIO route table
kernel/crates/kernel_bpf/src/signingSigned container (RBPF) parsing and Ed25519 verification
kernel/crates/kernel_bpf/src/profileCloudProfile and EmbeddedProfile constants
kernel/crates/kernel_bpf/src/actuationARM-A actuation reference monitor decision core
kernel/crates/kernel_bpf/src/concurrencyEpochSnapshot used to publish hook snapshots
kernel/src/bpfBpfManager, authorization, handles, limits, trust, snapshot, helpers
kernel/src/syscall/bpf.rssys_bpf command dispatch and capability gating
kernel/crates/kernel_abi/src/bpf.rsCommand, map type, attach type, helper and capability constants shared with userspace

Tests and tooling live in kernel/crates/kernel_bpf/tests (integration, profile contracts, semantic consistency, concurrency model), kernel/crates/kernel_bpf/fuzz (four libfuzzer targets: verify_only, verify_then_exec, signed_container, ringbuf_sequences), and kernel/crates/kernel_bpf/benches.

Build-time profiles

Exactly one of the cloud-profile or embedded-profile features must be enabled on kernel_bpf; enabling both or neither is a compile_error!. The profile is exposed as the ActiveProfile type alias.

ConstantCloudEmbedded
Stack512 KiB8 KiB
Max instructions1,000,000100,000
Per-map profile budget0 (kernel quotas only)64 KiB
JIT_ALLOWEDfalsefalse
Per-program WCET budgetunbounded1 ms period at 6 ns per unit (about 166,666 units)
Utilization budgetunbounded500,000,000 ns per second
Map resize methodscompilederased

See PROFILES.md  for the normative table.

Load-to-fire pipeline

Key properties, each described in detail on the linked pages:

  • Only verifier-produced VerifiedProgram values can reach the interpreter (Verifier).
  • Raw instruction loads carry no signature and are rejected whenever signature enforcement is active (Trust Model).
  • Attach re-runs verification with the exact payload size for the hook and forbids logging helpers on latency-sensitive hooks (Hooks).
  • Hook dispatch reads a fixed-capacity immutable snapshot and takes no manager lock (Hooks).

Honest scope notes

The crate documentation states that the embedded profile does not provide an EDF BPF scheduler or a static allocator: admission is a utilization ledger, and all maps use checked heap allocation. Performance figures quoted in source comments (for example the 6 ns per WCET unit calibration) come from historical benchmark records; the source itself notes they are not claimed as current artifact-backed measurement. This documentation does not restate them as current results.

Page map

Last updated on
Protocols & ABILoader