tk-axcbpf 0.1.0

Verified classic-BPF mechanism for no_std operating systems
Documentation
  • Coverage
  • 100%
    106 out of 106 items documented1 out of 1 items with examples
  • Size
  • Source code size: 177.4 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.3 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 2s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • chenty2333/TheKernel
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • chenty2333

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);
# Ok::<(), axcbpf::VerifyError>(())