Libreqos Lqos Sys Ebpf
Developmentlibreqos-lqos-sys-ebpfLibreqos Lqos Sys Ebpf is an Agent Skill for development published in the LibreQoE/LibreQoS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/LibreQoE/LibreQoS/blob/HEAD/.agents/skills/libreqos-lqos-sys-ebpf/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/libreqos-lqos-sys-ebpf, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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:
- Compile
src/bpf/lqos_kern.cto LLVM IR withclang - Convert LLVM IR to a BPF object with
llc - Generate
lqos_kern_skel.hwithbpftool gen skeleton - Compile
src/bpf/wrapper.c - Archive the wrapper into a small static library
- Run
bindgenonwrapper.h - 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.cfunction signatures- Skeleton-exposed program or map names
- Pinned-map ABI expectations in
lqos_kernel.rs
Required Checklist
- Edit only source files under
src/rust/lqos_sys/. - If a BPF-side struct changes, update the Rust mirror type in the same change.
- Update or preserve size assertions for Rust mirror types.
- Review pinned-map ABI cleanup in
src/rust/lqos_sys/src/lqos_kernel.rs. - Run
cargo check -p lqos_sys. - Run relevant tests for touched Rust mirror types and map readers.
- If runtime attach/detach behavior changed, state clearly whether live root validation was performed.
Mirror Types To Check
src/rust/lqos_sys/src/throughput.rssrc/rust/lqos_sys/src/flowbee_data.rssrc/rust/lqos_sys/src/ip_mapping/ip_hash_data.rssrc/rust/lqos_sys/src/ip_mapping/ip_hash_key.rs
Safety Rules
- Do not edit
OUT_DIRfiles. - 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, orbpftoolmissing 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.rstreats stderr fromclangandllcas fatal.- Pinned map compatibility cleanup already exists for several maps in
lqos_kernel.rs; extend it when introducing new ABI-sensitive pinned maps.