mirror of
https://github.com/caiwx86/small-packages.git
synced 2026-07-28 01:11:21 +08:00
118 lines
4.2 KiB
Markdown
118 lines
4.2 KiB
Markdown
# 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)
|