Skip to content

Instantly share code, notes, and snippets.

@binarycraft007
Last active January 21, 2026 09:00
Show Gist options
  • Select an option

  • Save binarycraft007/cceb0e87748d0c4d70d559715ea16ca0 to your computer and use it in GitHub Desktop.

Select an option

Save binarycraft007/cceb0e87748d0c4d70d559715ea16ca0 to your computer and use it in GitHub Desktop.
port libbpf to zig

libbpf to Zig Porting Specification

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.

1. Architecture & Layering

The library is organized into distinct, interdependent layers:

  1. sys (Syscalls): Strictly mirrors uapi/linux/bpf.h. No logic, just definitions and direct kernel calls.
  2. btf (Type System): Handles parsing and navigation of .BTF and .BTF.ext data.
  3. elf (Object Parsing): Generic ELF reader tailored for BPF object files.
  4. relo (Relocation Engine): Implements CO-RE logic, map relocations, and subprogram fixups.
  5. obj (High-Level API): Manages BpfObject, BpfProgram, and BpfMap lifecycles.

2. Syscall Layer (bpf.zig)

2.1. Syscall Payloads

Zig must use extern struct to match the kernel's binary layout for union bpf_attr.

BPF_MAP_CREATE Payload

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,
};

BPF_PROG_LOAD Payload

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,
};

3. BTF & .BTF.ext (btf.zig)

3.1. .BTF.ext Binary Layout

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:

  1. rec_size (u32): Size of a single record in this subsection.
  2. List of BtfExtInfoSec structures.
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
};

4. ELF & Object Parsing (obj.zig)

4.1. Loading Sequence (bpf_object__open)

  1. Validation: Check ELF magic, endianness (must match host).
  2. Section Scan:
    • .BTF: Parse into obj.btf.
    • .BTF.ext: Parse into obj.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 .kconfig map for externs.

4.2. Map Discovery (.maps)

Maps are defined as global variables in the .maps section.

  1. Iterate symbols in .maps.
  2. Get btf_type (DATAVAR -> STRUCT).
  3. Parse members: type, max_entries, key, value, map_flags, pinning.
  4. Store in obj.maps.

5. Relocation & Patching (relo.zig)

5.1. Standard ELF Relocations

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).

5.2. Instruction Fixups (Map FDs)

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.

5.3. CO-RE Algorithm

  1. Parse Spec: Convert access_str_off ("0:1:2") to BpfCoreSpec.
  2. Find Candidates: Match local type name against kernel BTF types.
  3. 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).
  4. Calc Result:
    • BYTE_OFFSET: Accumulate offsets of matched fields.
    • TYPE_SIZE: Get size of target type.
  5. Patch: Overwrite insn.imm with result.

6. Error Handling Strategy

Verifier Logs: If BPF_PROG_LOAD fails with EACCES or EINVAL:

  1. Allocate a log buffer (e.g., 64KB).
  2. Retry syscall with log_level = 1 and log_buf set.
  3. If ENOSPC (buffer too small), double size and retry (up to limit).
  4. Return error with log content attached.

7. Implementation Roadmap

Phase 1: Core Primitives

  • Define extern structs for all syscalls.
  • Implement sys_bpf wrapper.
  • Implement libbpf_strlcpy and error helpers.

Phase 2: BTF Engine

  • BTF Parser: Headers, Type Graph, String Table.
  • BTF.ext Parser: Func Info, Line Info, CO-RE Relos.
  • Helpers: skip_mods_and_typedefs, resolve_size.

Phase 3: Object Loading

  • ELF Reader: Headers, Sections, Symbols (using native Zig or libelf).
  • Kconfig Parser: Gzip decompressor + key/value parser.
  • Map Parser: .maps section to BpfMap structs.

Phase 4: Relocation & Fixups

  • CO-RE Logic: Spec parser, type compatibility check, instruction patching.
  • Map Fixups: LD_IMM64 patching with BPF_PSEUDO_MAP_FD.
  • Subprog Fixups: call instruction relative offset calculation.

Phase 5: Lifecycle Management

  • bpf_object__open: Orchestrate parsing.
  • bpf_object__load: Create maps, load programs, check verifier logs.
  • bpf_object__attach: Netlink/Tracepoint attachment helpers.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment