While BTFhub main repository contains documentation, tooling and examples on how to use the BTF files, the BTF files exist in the BTFhub-Archive repository.
BTF is one of the things that make eBPF portable.
Before CO-RE existed, eBPF developers had to compile one eBPF object per supported kernel. This made eBPF toolkits, such as iovisor/bcc, to rely on runtime compilations.
With CO-RE, the same eBPF object can be loaded into multiple different kernels. The libbpf loader will allow CO-RE by arranging needed infrastructure for a given eBPF object, such as eBPF maps creation, code relocation, eBPF probes, links and their attachments, etc.
The eBPF Type Format (BTF) is a data format to store debug information about eBPF objects OR about the kernels they will be loaded into.
The idea is this: Both, the eBPF object AND the target kernel, have BTF information available, usually embedded into their ELF files. The libbpf loader uses the embedded BTF information to calculate needed changes (relocations, map creations, probe attachments, ...) for an eBPF object to be loaded and have its programs executed in any kernel, without modifications to the object.
Unfortunately the BTF format wasn't always available and, because of missing kernel support, or because of the lack of userland tools, capable of understanding the BTF format, distributions release(ed) kernels without the embedded BTF information.
That is why BTFhub exists: to provide BTF information for Linux distributions released kernels that don't have embedded BTF information. Instead of recompiling your eBPF code to each existing Linux kernel that does not support BTF information, your code will be relocated - by libbpf - according to available BTF information from the BTFhub files.
After libbpf started supporting external (raw) BTF files, we're able to feed libbpf with this external BTF file for a kernel you want to run your eBPF code into. Each kernel needs its own BTF file.
Note: You won't need BTFhub if you're willing to support your eBPF CO-RE application only in the latest kernels. Now, if you are willing to support ALL released kernels, including some Long Term Support Linux distribution versions, then you may need to use BTFhub.
This is a list of existing distributions and their current status on eBPF and BTF support.
-
This is a code example of how you should use BTFhub to add support to legacy kernels to your eBPF project. The uncompressed full BTF files, from the BTFhub-Archive repository, should feed libbpf used by your eBPF project, just like showed in this C example or this Go example.
-
You may use the BTFgen tool to create smaller BTF files, so you can embed them into your eBPF application and make it support all kernels supported by BTFhub.
- How to use Pahole to generate BTF information
- BTF Generator Internals
- more references to come...