tk-axcbpf
tk-axcbpf is a no_std, unsafe-free classic-BPF verifier and
interpreter for operating-system mechanism layers. It accepts the ordinary
classic instruction set, including absolute and indirect loads, sixteen scratch
words, forward jumps, and 32-bit arithmetic.
Installation
[]
= { = "tk-axcbpf", = "0.1.0" }
The Rust library name is axcbpf. This release is tested on x86_64 with
nightly-2026-08-23 (rustc 1.100.0-nightly). Its Cargo rust-version = "1.100"
is a numeric compiler floor, not a stable-toolchain compatibility guarantee.
An allocator is required even though the library is no_std.
Contract
Program::verify rejects empty or over-4096-instruction programs, unsupported
opcodes, immediate division by zero, oversized immediate shifts, invalid
scratch indices, out-of-range jumps, missing final returns, and scratch loads
that are not initialized on every reachable path. Validation and the immutable
program copy use fallible allocation. Program::try_from_vec validates and
takes an adapter's existing instruction vector without a second instruction
allocation or copy. A verified program exposes no mutable instruction storage.
Evaluation initializes A, X, and scratch storage for every invocation and
allocates nothing. Every accepted branch moves forward, so execution is
bounded by the verified instruction count. Register-sourced shift counts use
their low five bits, matching 32-bit classic-BPF behavior. Input access is
expressed through the Input trait. The trait owns byte order and
domain-specific range rules; an absent load terminates with return value zero.
The built-in [u8] input uses network-byte-order halfword and word loads.
Profiles own all domain-specific offset interpretation, including any Linux
socket-filter extensions; the mechanism forwards each u32 offset to its
Input adapter unchanged.
Program::translate emits a real immutable SysV x86_64 function with ABI
extern "C" fn(*const u8, u32) -> u32. The image contains no helper calls or
address-bearing relocations: input bounds, indirect-offset overflow, arithmetic,
branches, and failure-to-zero paths are emitted directly. A publisher may copy
CodeImage::bytes into a W^X executable mapping; entry_offset() is zero and
page_aligned_size() gives the exact page-rounded mapping size.
Use Program::translate_with_profile(InputProfile::NativeAlignedWords) for a
native-endian aligned-word input. That profile rejects byte and
halfword source loads, rejects unaligned absolute word offsets, and checks
indirect word alignment at runtime. NativeWordInput is the corresponding
safe reference-model adapter. Both the interpreter and JIT check indirect word
alignment using the logical offset before adding the data pointer.
NativeWordInput::new intentionally keeps that logical rule independent from
an incidental Rust slice address; adapters with a four-byte-aligned
snapshot-base ABI can use NativeWordInput::new_aligned at their boundary.
CodeImage::validate() independently decodes the restricted native instruction
subset, checks the source semantic trace, direct targets, prologue/epilogue,
and the empty relocation set; it does not make pages executable.
Example
use ;
let filter = verify?;
assert_eq!;
# Ok::