Expand description
§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
[dependencies]
axcbpf = { package = "tk-axcbpf", version = "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 axcbpf::{Instruction, Program, opcode};
let filter = Program::verify(&[
Instruction::statement(opcode::LD_B_ABS, 0),
Instruction::jump(opcode::JMP_JEQ_K, 0x45, 0, 1),
Instruction::statement(opcode::RET_K, 1),
Instruction::statement(opcode::RET_K, 0),
])?;
assert_eq!(filter.evaluate(&[0x45][..]), 1);Modules§
- opcode
- Raw classic-BPF opcode values.
Structs§
- Code
Image - Immutable native x86_64 bytes and translation metadata.
- Instruction
- One classic-BPF instruction in the standard eight-byte wire layout.
- Instruction
Map - Maps one source instruction to emitted machine bytes.
- Native
Word Input - Input adapter for
InputProfile::NativeAlignedWordsreference tests. - Program
- Immutable verified classic-BPF program.
- Relocation
- A relocation in an immutable
CodeImage.
Enums§
- External
Call - A call site that a publisher may resolve after image placement.
- Image
Validation Error - Failure found by the independent translation validator.
- Input
Profile - Input ABI used by emitted loads.
- Load
Width - Width requested from a classic-BPF input.
- Relocation
Kind - The kind of an image relocation.
- Translation
Error - Failure while translating a verified program.
- Verify
Error - Failure while validating and owning one classic-BPF program.
Constants§
- MAX_
CODE_ IMAGE_ BYTES - Maximum bytes in one translated x86_64 image.
- MAX_
INSTRUCTIONS - Maximum number of instructions in one verified classic-BPF program.
- SCRATCH_
WORDS - Number of 32-bit scratch words exposed by classic BPF.
Traits§
- Input
- Read-only data source evaluated by a classic-BPF program.
Functions§
- validate_
translation_ bytes - Independently validates raw x86_64 bytes against a verified cBPF source.