This document provides a comprehensive technical specification for reimplementing libbpf v1.0+ in Zig. It covers architecture, binary formats, algorithms, and implementation details derived from a deep code analysis.
The library is organized into distinct, interdependent layers:
sys(Syscalls): Strictly mirrorsuapi/linux/bpf.h. No logic, just definitions and direct kernel calls.btf(Type System): Handles parsing and navigation of.BTFand.BTF.extdata.elf(Object Parsing): Generic ELF reader tailored for BPF object files.relo(Relocation Engine): Implements CO-RE logic, map relocations, and subprogram fixups.obj(High-Level API): ManagesBpfObject,BpfProgram, andBpfMaplifecycles.
Zig must use extern struct to match the kernel's binary layout for union bpf_attr.
pub const BpfMapCreateAttr = extern struct {
map_type: u32,
map_name: [16]u8, // BPF_OBJ_NAME_LEN
key_size: u32,
value_size: u32,
max_entries: u32,
map_flags: u32,
inner_map_fd: u32,
numa_node: u32,
map_name_len: u32,
map_ifindex: u32,
btf_fd: u32,
btf_key_type_id: u32,
btf_value_type_id: u32,
btf_vmlinux_value_type_id: u32,
map_extra: u64,
};pub const BpfProgLoadAttr = extern struct {
prog_type: u32,
insn_cnt: u32,
insns: u64, // Pointer to instructions
license: u64, // Pointer to string
log_level: u32,
log_size: u32,
log_buf: u64, // Pointer to buffer
kern_version: u32,
prog_flags: u32,
prog_name: [16]u8,
prog_ifindex: u32,
expected_attach_type: u32,
prog_btf_fd: u32,
func_info_rec_size: u32,
func_info: u64, // Pointer to .BTF.ext func_info
func_info_cnt: u32,
line_info_rec_size: u32,
line_info: u64, // Pointer to .BTF.ext line_info
line_info_cnt: u32,
attach_btf_id: u32,
attach_prog_fd: u32, // Union with attach_btf_obj_fd
attach_btf_obj_fd: u32, // Note: Overlaps with attach_prog_fd in C union
core_relo_cnt: u32,
fd_array: u64,
core_relos: u64,
core_relo_rec_size: u32,
};The .BTF.ext section contains CO-RE relocations, function info, and line info. It is not a standard BTF header.
const BtfExtHeader = extern struct {
magic: u16,
version: u8,
flags: u8,
hdr_len: u32,
// Offsets and lengths for subsections
func_info_off: u32,
func_info_len: u32,
line_info_off: u32,
line_info_len: u32,
core_relo_off: u32,
core_relo_len: u32,
};Subsection Structure:
Each subsection (e.g., core_relo) follows this pattern:
rec_size(u32): Size of a single record in this subsection.- List of
BtfExtInfoSecstructures.
const BtfExtInfoSec = extern struct {
sec_name_off: u32, // Offset in .BTF string table
num_info: u32,
// Followed immediately by `num_info * rec_size` bytes of data
};CO-RE Relocation Record:
const BpfCoreRelo = extern struct {
insn_off: u32,
type_id: u32,
access_str_off: u32,
kind: u32, // enum bpf_core_relo_kind
};- Validation: Check ELF magic, endianness (must match host).
- Section Scan:
.BTF: Parse intoobj.btf..BTF.ext: Parse intoobj.btf_ext..maps: Identify BTF-defined maps.SHT_REL/SHT_RELA: Collect standard relocations for instruction patching.- Kconfig: Attempt to read
/proc/config.gz(gunzip required) to populate.kconfigmap for externs.
Maps are defined as global variables in the .maps section.
- Iterate symbols in
.maps. - Get
btf_type(DATAVAR -> STRUCT). - Parse members:
type,max_entries,key,value,map_flags,pinning. - Store in
obj.maps.
Handling SHT_REL / SHT_RELA sections.
R_BPF_64_64: 64-bit absolute address. Used for map pointers (LD_IMM64).R_BPF_64_32: 32-bit absolute address. Used for subprogram calls (call #offset).
When a BPF instruction references a map, it must be patched with the map's file descriptor after creation.
Target Instruction: BPF_LD_IMM64 (consists of two 64-bit instructions).
- Pseudo Map FD:
insn[0].src_reg=BPF_PSEUDO_MAP_FD(1).insn[0].imm=map_fd.
- Pseudo Map Value (Pointer to inside a map value):
insn[0].src_reg=BPF_PSEUDO_MAP_VALUE(2).insn[0].imm=map_fd.insn[1].imm=offset.
- Parse Spec: Convert
access_str_off("0:1:2") toBpfCoreSpec. - Find Candidates: Match local type name against kernel BTF types.
- Recursion (
bpf_core_types_are_compat):- Traverse type graphs simultaneously.
- Skip
CONST/VOLATILE/TYPEDEF. - Allow "fuzzy" matches (e.g., struct fields reordered, integer size changes).
- Calc Result:
BYTE_OFFSET: Accumulate offsets of matched fields.TYPE_SIZE: Get size of target type.
- Patch: Overwrite
insn.immwith result.
Verifier Logs:
If BPF_PROG_LOAD fails with EACCES or EINVAL:
- Allocate a log buffer (e.g., 64KB).
- Retry syscall with
log_level = 1andlog_bufset. - If
ENOSPC(buffer too small), double size and retry (up to limit). - Return error with log content attached.
- Define
extern structs for all syscalls. - Implement
sys_bpfwrapper. - Implement
libbpf_strlcpyand error helpers.
- BTF Parser: Headers, Type Graph, String Table.
- BTF.ext Parser: Func Info, Line Info, CO-RE Relos.
- Helpers:
skip_mods_and_typedefs,resolve_size.
- ELF Reader: Headers, Sections, Symbols (using native Zig or libelf).
- Kconfig Parser: Gzip decompressor + key/value parser.
- Map Parser:
.mapssection toBpfMapstructs.
- CO-RE Logic: Spec parser, type compatibility check, instruction patching.
- Map Fixups:
LD_IMM64patching withBPF_PSEUDO_MAP_FD. - Subprog Fixups:
callinstruction relative offset calculation.
-
bpf_object__open: Orchestrate parsing. -
bpf_object__load: Create maps, load programs, check verifier logs. -
bpf_object__attach: Netlink/Tracepoint attachment helpers.