update 2026-09-24 16:56:26

vmlinux-btf/README.md

@@ -0,0 +1,117 @@
+# 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:
+```bash
+sudo apt install build-essential libssl-dev libelf-dev \
+    bc flex bison python3 xz-utils tar
+```
+
+Install on Fedora/RHEL:
+```bash
+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:
+```bash
+sudo apt install dwarves
+```
+
+Install on Fedora/RHEL:
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+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](https://www.gnu.org/licenses/gpl-3.0.html)