eBPF Fundamentals

The loader exits, yet the program remains attached; the verifier passes, but counters may still be lost. Object lifetime, memory safety proofs, and business correctness are three distinct concerns in eBPF.

This article discusses extended BPF. seccomp uses the classic BPF filter format and specialized system call semantics, and should not be confused with standard eBPF program types.

1. Multiple Independent Objects in the Lifecycle

libbpf coordinates ELF parsing, relocations, and kernel interface calls; do not treat successful loading as successful attachment.

Closing the loader process does not necessarily revoke all programs: resources pinned or referenced by other objects may still exist; lifetime rules differ across attach APIs. When designing tools, clearly define who holds the link, whether pinning is used, and how to revoke upon exit. Do not rely solely on the assumption that "process termination will automatically clean up." See libbpf Overview.

2. The Verifier Checks Provable Safety Conditions

The verifier propagates abstract state along the control flow, tracking scalar ranges, pointer types, initialized regions, and resources requiring release in registers and stack slots. It handles paths through mechanisms like state merging and pruning, rather than executing every specific input individually.

Bounded loops, bpf_loop, or iterators expand expressiveness, but not all loops are accepted. Program instruction count and verifier exploration complexity are distinct limits; do not treat "one million" as a unified upper bound for source code length, execution count, and all programs simultaneously.

BPF stacks have strict limits; the common maximum stack frame per subprogram is 512 bytes; call chains and tail call combinations add further constraints. Tail call chain limits differ from standard BPF-to-BPF call depth. Rely on the target kernel's verification logs rather than memorizing a universal constant table across versions.

Non-null Proof and Key Range Are Not the Same Thing

Below is a local pattern after a map lookup, assuming counts value type is __u64 and the key is an initialized __u32:

__u32 key = 7;
__u64 *value = bpf_map_lookup_elem(&counts, &key);
if (!value)
    return 0;
__sync_fetch_and_add(value, 1);

The lookup helper determines the result based on map type and key content; the verifier must confirm the key memory is readable and that the value is not NULL before dereferencing. Do not treat if (x < 10) as a proof that any map lookup will succeed, especially if x may be signed and the lower bound has not been checked.

Standard (*value)++ may lose counts on concurrent updates to shared values; the example uses atomic addition; atomic operations still must satisfy target instruction and access constraints. The verifier accepts that it does not prove business statistical correctness, nor does it guarantee that the kernel or verifier implementation is bug-free. See Verifier Documentation.

Compare one successful sample with the proof required for every reachable path. Removing the NULL guard changes the proof even when this particular key exists.

3. JIT Reduces Interpretation Overhead, But Does Not Eliminate All Costs

When JIT is supported and enabled, BPF instructions are compiled to target machine code; other available execution paths depend on architecture and build configuration. You cannot specify a fixed "corresponds to 1 to 3 x86 instructions" for all BPF instructions: calls, atomic operations, checks, and JIT hardening all affect the generated code.

Runtime costs also include hooks, map lookups, locks, event copying, and user-space consumption. Verification occurs at load time, but boundary checks from the source program used for proof may still remain in the runtime code, so you cannot claim "zero runtime overhead for all boundary checks."

4. Maps Are State Objects with Different Semantics

Per-CPU reduces cross-CPU shared write contention, but does not imply the entire map is "absolutely lock-free," nor does it automatically resolve consistency during user-space reads. Distinction is also needed between hash structure updates and atomic consistency of multiple fields within values.

BPF global variables can also retain state; libbpf often organizes related data sections as maps, so "programs are completely stateless" is an oversimplification. See BPF Maps for more semantics.

5. Choosing Between Ring Buffer and Perf Buffer

Perf event arrays are often paired with per-CPU perf buffers to output BPF events; BPF ringbuf provides a multi-producer, single-consumer shared ring buffer, and multiple ringbufs can also be used for sharding. Both support variable-length records; do not claim that perf buffers only support fixed-length records.

Early Reservations Unfinished May Cause Later Events to Wait

The ringbuf reserve/submit path allows direct filling of reserved records; if earlier reserved records are not yet completed, it affects the consumer's ability to continue reading subsequent records. Ordering corresponds to the reservation sequence within the same ringbuf, not to the absolute chronological order of events across CPUs, nor to a global order across multiple ringbufs.

Both solutions may lose events. Ringbuf reservation failures must be counted; perf buffer lost information must be handled; timestamps, CPU IDs, event identifiers, and loss counts should become part of the data protocol. Whether shared memory is used and whether copying occurs depend on the specific output API and consumption path; do not simply claim that perf always involves two copies and ringbuf never involves copying. See BPF Ring Buffer.

6. Compatibility Boundaries of BTF and CO-RE

BTF describes type information; CO-RE uses target BTF at load time to handle relocations for field offsets, sizes, presence, etc. BPF_CORE_READ(task, pid) allows correct access even if fields move, but does not turn the entire kernel internal ABI into a stable interface.

The program must still pass the verifier for the target version.

/sys/kernel/btf/vmlinux often provides the running kernel's BTF; module BTFs have their own availability conditions. CO-RE does not require installing a full compiler on every target machine, but build and release planning still requires defining minimum capabilities, compatibility paths, and verification matrices.

7. Permissions and Observation Tools

Loading tracing-related programs often involves CAP_PERFMON; network management operations may involve CAP_NET_ADMIN; CAP_BPF is not a pass for all attachments. Unprivileged BPF is subject to sysctls, program types, and other restrictions. LSM, lockdown, etc., may further constrain operations.

After installing bpftool, the following commands are used for read-only inspection of objects; what you can see depends on permissions:

bpftool prog show
bpftool map show
bpftool link show

bpftool feature probe probes capabilities by attempting relevant operations; do not treat it as purely reading a static version table. JIT instruction display also depends on permissions and kernel configuration, and does not guarantee that every program has exportable machine code.

Continue reading: Program Types, Tracing and Debugging.