bpftime Documentation

bpftime is a high-performance userspace eBPF runtime and general extension framework. Unlike a simple VM, it is a complete runtime environment including a loader, verifier, helpers, maps, ufunc (user functions), and support for multiple event sources like Observability, Network, Policy, or Access Control.

It is designed to bypass the kernel to achieve faster performance for Uprobes, USDT, Syscall hooks, and XDP, while maintaining compatibility with existing eBPF toolchains like clang, libbpf, and bpftrace.

bpftime enables eBPF programs to execute within GPU kernels on both NVIDIA (via CUDA) and AMD (via ROCm) GPUs. This allows for real-time profiling, debugging, and runtime extension of GPU computing workloads without requiring modifications to the original application source code.

Note: GPU support is currently considered experimental.

The ubpf-vm is a wrapper around ubpf designed to provide a unified interface for bpftime. It includes specific adaptations to bridge feature gaps between ubpf and the requirements of the bpftime runtime, specifically:

• Helper ID Remapping: It remaps helper IDs to a range of 0-63, as ubpf only supports up to 64 helpers.
• Instruction Patching: It patches lddw (load double word) instructions during the code loading process to ensure compatibility.

The example uses BPF_MAP_TYPE_GPU_ARRAY_MAP and BPF_MAP_TYPE_GPU_HASH_MAP. These are non-per-thread, single-copy shared maps using UVA Zero-Copy (Unified Virtual Addressing), allowing the GPU and host to see the same memory.

Write Semantics (Device Side)

• Mechanism: Uses a memcpy overwrite via the trampoline fast-path. This is non-atomic; the last writer wins.
• Visibility: A system-level memory fence is executed after the write to ensure the host sees the update.
• Optimization: This method avoids the CPU handshake path, reducing latency.

Read Semantics (Host Side)

• Mechanism: Reads are lock-free.
• Consistency: You may read a slightly older value, but you will not read a partially written value. For stronger consistency, implement locks or double-read version checks on the host side.

bpftime operates in two primary modes:

1. Userspace Only: Runs eBPF programs entirely in userspace without kernel involvement. This allows running on older Linux versions or systems where kernel eBPF is unavailable or restricted (no root required). It uses a userspace verifier (like PREVAIL) to ensure safety.
2. Run with Kernel eBPF: Allows bpftime to coexist with the kernel. It can load eBPF programs from the kernel and use kernel eBPF maps to cooperate with kernel-level programs such as kprobes and network filters.

BPFtime includes an embedded eBPF VM designed for low-latency execution. Benchmark results show the embed operation has an average latency of approximately 106.30 ns.

### Embedded VM Performance

| Operation | Min (ns) | Max (ns) | Avg (ns) | Std Dev |
|-----------|----------|----------|----------|---------|
| embed | 75.47 | 221.55 | 106.30 | 39.99 |

The demo implements real-time file access interception using the following workflow:

1. Monitor (Server): Loads the BPF program and initializes the BPF_MAP_TYPE_LPM_TRIE map with a set of allowed prefixes.
2. Target (Client): Executes file operations that trigger uprobe events.
3. LPM Trie: The BPF program uses the LPM Trie to automatically find the longest matching prefix for the requested file path to determine access control.
4. Event Queue: Processes the resulting file access events in real-time.

Architecture Flow:

• Monitor (Server) $\rightarrow$ bpftime Server $\rightarrow$ BPF Maps (LPM Trie, Queue, Counter)
• Target (Client) $\rightarrow$ bpftime Agent $\rightarrow$ Shared Memory
• BPF Program $\rightarrow$ LPM Trie $\rightarrow$ Access Control

bpftime userspace map operations are designed to be faster than kernel operations. The benchmark tests various map types including:

• Hash maps (bpf_map_lookup_elem, bpf_map_update_elem, bpf_map_delete_elem)
• Array maps
• Per-CPU maps (Hash and Array)

Performance can be improved by inlining the map operation functions. Note that current versions may still have performance issues with per-CPU maps in the userspace runtime that are subject to future fixes.