small-packages/vmlinux-btf

vmlinux-btf

An OpenWrt package that builds a BTF-enabled vmlinux in a shadow kernel tree and installs it as a standalone file, enabling CO-RE (Compile Once – Run Everywhere) eBPF programs to run on OpenWrt without tainting or modifying the main kernel build.

---

How It Works

1. Downloads the upstream Linux kernel source that matches the current OpenWrt build environment.
2. Extracts it into an isolated shadow-kernel directory inside the build tree.
3. Applies the same generic and platform-specific patches that the main kernel receives, in the same order.
4. Copies the main kernel's .config as a baseline, then enables the full set of BTF and BPF-related options on top of it.
5. Compiles vmlinux with full DWARF debug info.
6. Uses pahole to extract a detached BTF blob from the resulting vmlinux.
7. Installs the blob to /usr/lib/debug/boot/vmlinux on the target device.

This approach keeps the main kernel tree completely untouched — BTF information is generated entirely in the shadow build.

---

Host Build Dependencies

The following tools must be present on the host machine running the OpenWrt build system before compiling this package.

Required by the OpenWrt build system itself

These are standard OpenWrt build prerequisites. If your environment already builds OpenWrt successfully, these should already be present.

Tool	Purpose
gcc / binutils	Cross-compilation toolchain
make	Build orchestration
xz-utils	Decompression of kernel source tarball (xzcat)
tar	Extraction of kernel source
bc	Kernel version arithmetic during prepare
flex, bison	Kernel parser generation
libssl-dev	Kernel certificate handling
libelf-dev	ELF binary manipulation, required by kernel build
python3	Kernel build scripts

Install on Debian/Ubuntu:

sudo apt install build-essential libssl-dev libelf-dev \
    bc flex bison python3 xz-utils tar

Install on Fedora/RHEL:

sudo dnf install gcc binutils openssl-devel elfutils-libelf-devel \
    bc flex bison python3 xz tar

---

Required specifically by this package

dwarves (provides pahole)

pahole is used to extract the detached BTF blob from the compiled vmlinux. This is the only tool required by this package that is not a standard OpenWrt build dependency.

Install on Debian/Ubuntu:

sudo apt install dwarves

Install on Fedora/RHEL:

sudo dnf install dwarves

Note: A host pahole version of 1.16 or newer is required for --btf_encode_detached support. The version bundled with the OpenWrt dwarves/host feed satisfies this requirement. If you install pahole manually from your system package manager, verify the version with pahole --version.

---

Building

Add this package to your OpenWrt build configuration:

# From the OpenWrt build root
make menuconfig
# Navigate to: Kernel → vmlinux-btf
# Select with <M> or <*>

make package/vmlinux-btf/compile V=s

Or build the IPK directly:

make package/vmlinux-btf/{clean,compile} V=s

---

Installed Files

Path	Description
/usr/lib/debug/boot/vmlinux	Detached BTF blob
/usr/lib/debug/boot/vmlinux-<kernel-version>	Symlink created by postinst

The symlink is created at install time using the running kernel version (uname -r) and removed automatically on package removal.

---

Notes

• Build time is significant. This package compiles a complete kernel from source. Expect 20–60 minutes depending on your hardware and target architecture.
• Kernel version must match. The shadow kernel is built from the same source version as the OpenWrt target kernel ($(LINUX_VERSION)). Installing this package on a device running a different kernel version will likely result in BTF type mismatches and broken CO-RE lookups.
• Architecture-specific JIT support (HAVE_EBPF_JIT) is set automatically by the kernel build system based on the target architecture and does not need to be configured manually.

---

License

GPL-3.0-or-later — see https://www.gnu.org/licenses/gpl-3.0.html