OpenParable
Skip to content
← Back to skills

Libreqos Lqos Sys Ebpf

Development
libreqos-lqos-sys-ebpf

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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:

  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.