cwx/small-packages
1
0 Fork 0
mirror of https://github.com/caiwx86/small-packages.git synced 2026-11-14 04:07:56 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

update 2026-10-19 17:31:01

Browse Source
This commit is contained in:
action committed 2026-10-19 17:31:01 +08:00
1 parent 6604b3420d
commit 313fe55d56
38 files changed
+982 -1508
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

vmlinux-btf/README.md
+17 -92
View File
@@ -1,117 +1,42 @@
# 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.
OpenWrt package that generates a detached BTF (`vmlinux`) file from kernel headers and `.config`, enabling CO-RE (Compile Once – Run Everywhere) eBPF programs on OpenWrt without rebuilding or replacing the running kernel.
---
## Overview
## How It Works
Official OpenWrt release kernels typically omit `CONFIG_DEBUG_INFO_BTF=y`. Without kernel BTF, modern eBPF tools that rely on CO-RE (such as `libbpf`-based loaders) cannot resolve kernel type layouts.
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.
Rather than recompiling the entire kernel tree, this package compiles lightweight stub sources (`src/shadow_btf_*.c`) against the prepared target kernel headers (`$(LINUX_DIR)`) using the target configuration and toolchain. `pahole` then extracts the detached BTF blob from the linked object.
This approach keeps the main kernel tree completely untouched — BTF information is generated entirely in the shadow build.
## Requirements
---
## 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`.
---
- OpenWrt buildroot or SDK environment.
- Host `pahole` >= 1.22 (from the `dwarves` package).
## Building
Add this package to your OpenWrt build configuration:
### In OpenWrt SDK
```bash
# From the OpenWrt build root
make menuconfig
# Navigate to: Kernel → vmlinux-btf
# Select with <M> or <*>
git clone https://github.com/QiuSimons/vmlinux-btf.git package/vmlinux-btf
make package/vmlinux-btf/compile V=s
```
Or build the IPK directly:
### In OpenWrt Buildroot
Select `vmlinux-btf` under `Kernel` in `make menuconfig`, then build:
```bash
make package/vmlinux-btf/{clean,compile} V=s
make package/vmlinux-btf/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` |
- `/usr/lib/debug/boot/vmlinux`: Detached BTF file.
- `/usr/lib/debug/boot/vmlinux-<release>`: Symlink targeting `vmlinux` (linked to `uname -r` on target installation).
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.
---
Standard loaders such as `libbpf` look for BTF at `/usr/lib/debug/boot/vmlinux-$(uname -r)` and `/usr/lib/debug/boot/vmlinux` by default.
## 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)
GPL-3.0-or-later