Skip to main content

Crate axcbpf

Crate axcbpf 

Source
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§

CodeImage
Immutable native x86_64 bytes and translation metadata.
Instruction
One classic-BPF instruction in the standard eight-byte wire layout.
InstructionMap
Maps one source instruction to emitted machine bytes.
NativeWordInput
Input adapter for InputProfile::NativeAlignedWords reference tests.
Program
Immutable verified classic-BPF program.
Relocation
A relocation in an immutable CodeImage.

Enums§

ExternalCall
A call site that a publisher may resolve after image placement.
ImageValidationError
Failure found by the independent translation validator.
InputProfile
Input ABI used by emitted loads.
LoadWidth
Width requested from a classic-BPF input.
RelocationKind
The kind of an image relocation.
TranslationError
Failure while translating a verified program.
VerifyError
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.