libreqos-lqos-sys-ebpf

name	libreqos-lqos-sys-ebpf
description	Shared LibreQoS workflow for lqos_sys eBPF, C wrapper, bindgen, and pinned-map ABI work. Use when changing src/rust/lqos_sys/build.rs, src/rust/lqos_sys/src/bpf/**, wrapper.c or wrapper.h, lqos_sys Rust mirror structs, or XDP/TC attachment and map ABI behavior.

LibreQoS lqos_sys eBPF Workflow

Use this skill for lqos_sys BPF/FFI work.

Scope

• Source of truth lives under src/rust/lqos_sys/.
• eBPF/C code lives under src/rust/lqos_sys/src/bpf/.
• Rust includes generated bindings from OUT_DIR; do not edit generated artifacts directly.

Build Pipeline

build.rs orchestrates this pipeline:

1. Compile src/bpf/lqos_kern.c to LLVM IR with clang
2. Convert LLVM IR to a BPF object with llc
3. Generate lqos_kern_skel.h with bpftool gen skeleton
4. Compile src/bpf/wrapper.c
5. Archive the wrapper into a small static library
6. Run bindgen on wrapper.h
7. Include generated bindings from OUT_DIR/bindings.rs

When changing any part of that chain, treat the whole chain as one linked surface.

High-Risk Changes

• BPF map key/value structs
• Shared constants such as sizing limits
• wrapper.h / wrapper.c function signatures
• Skeleton-exposed program or map names
• Pinned-map ABI expectations in lqos_kernel.rs

Required Checklist

1. Edit only source files under src/rust/lqos_sys/.
2. If a BPF-side struct changes, update the Rust mirror type in the same change.
3. Update or preserve size assertions for Rust mirror types.
4. Review pinned-map ABI cleanup in src/rust/lqos_sys/src/lqos_kernel.rs.
5. Run cargo check -p lqos_sys.
6. Run relevant tests for touched Rust mirror types and map readers.
7. If runtime attach/detach behavior changed, state clearly whether live root validation was performed.

Mirror Types To Check

• src/rust/lqos_sys/src/throughput.rs
• src/rust/lqos_sys/src/flowbee_data.rs
• src/rust/lqos_sys/src/ip_mapping/ip_hash_data.rs
• src/rust/lqos_sys/src/ip_mapping/ip_hash_key.rs

Safety Rules

• Do not edit OUT_DIR files.
• Do not assume a Rust-only change is safe if it reads a BPF map with a mirrored struct layout.
• Do not run live XDP/TC attach-detach or pinned-map cleanup without explicit user approval; this can disrupt networking on the host.
• Be careful with verifier-sensitive patterns in BPF code: bounds checks, scratch maps for large structs, and hot-path allocation avoidance are intentional.

Common Failure Modes

• clang, llc, or bpftool missing from the host
• Skeleton generation succeeding but wrapper/bindgen drifting
• Rust mirror struct sizes no longer matching BPF-side layouts
• Stale pinned maps silently reusing an incompatible ABI

Notes

• build.rs treats stderr from clang and llc as fatal.
• Pinned map compatibility cleanup already exists for several maps in lqos_kernel.rs; extend it when introducing new ABI-sensitive pinned maps.