1Useful links 2------------ 3 4- [BPF Portability and CO-RE](https://facebookmicrosites.github.io/bpf/blog/2020/02/19/bpf-portability-and-co-re.html) 5- [HOWTO: BCC to libbpf conversion](https://facebookmicrosites.github.io/bpf/blog/2020/02/20/bcc-to-libbpf-howto-guide.html) 6- [Tips & tricks for writing libbpf-tools](https://en.pingcap.com/blog/tips-and-tricks-for-writing-linux-bpf-applications-with-libbpf) 7 8Building 9------- 10 11To build libbpf-based tools, simply run `make`. This will build all the listed 12tools/applications. All the build artifacts, by default, go into .output 13subdirectory to keep source code and build artifacts completely separate. The 14only exception is resulting tool binaries, which are put in a current 15directory. `make clean` will clean up all the build artifacts, including 16generated binaries. 17 18Given that the libbpf package might not be available across wide variety of 19distributions, all libbpf-based tools are linked statically against a version 20of libbpf that BCC links against (from submodule under src/cc/libbpf). This 21results in binaries with minimal amount of dependencies (libc, libelf, and 22libz are linked dynamically, though, given their widespread availability). 23If your build fails because the libbpf submodule is outdated, try running `git 24submodule update --init --recursive`. 25 26Tools are expected to follow a simple naming convention: 27 - <tool>.c contains userspace C code of a tool. 28 - <tool>.bpf.c contains BPF C code, which gets compiled into BPF ELF file. 29 This ELF file is used to generate BPF skeleton <tool>.skel.h, which is 30 subsequently is included from <tool>.c. 31 - <tool>.h can optionally contain any types and constants, shared by both 32 BPF and userspace sides of a tool. 33 34For such cases, simply adding <tool> name to Makefile's APPS variable will 35ensure this tool is built alongside others. 36 37For more complicated applications, some extra Makefile rules might need to be 38created. For such cases, it is advised to put application into a dedicated 39subdirectory and link it from main Makefile. 40 41vmlinux.h generation 42------------------- 43 44vmlinux.h contains all kernel types, both exported and internal-only. BPF 45CO-RE-based applications are expected to include this file in their BPF 46program C source code to avoid dependency on kernel headers package. 47 48For more reproducible builds, vmlinux.h header file is pre-generated and 49checked in along the other sources. This is done to avoid dependency on 50specific user/build server's kernel configuration, because vmlinux.h 51generation depends on having a kernel with BTF type information built-in 52(which is enabled by `CONFIG_DEBUG_INFO_BTF=y` Kconfig option See below). 53 54vmlinux.h is generated from upstream Linux version at particular minor 55version tag. E.g., `vmlinux_505.h` is generated from v5.5 tag. Exact set of 56types available in compiled kernel depends on configuration used to compile 57it. To generate present vmlinux.h header, default configuration was used, with 58only extra `CONFIG_DEBUG_INFO_BTF=y` option enabled. 59 60Given different kernel version can have incompatible type definitions, it 61might be important to use vmlinux.h of a specific kernel version as a "base" 62version of header. To that extent, all vmlinux.h headers are versioned by 63appending <MAJOR><MINOR> suffix to a file name. There is always a symbolic 64link vmlinux.h, that points to whichever version is deemed to be default 65(usually, latest). 66 67bpftool 68------- 69 70bpftool is a universal tool used for inspection of BPF resources, as well as 71providing various extra BPF-related facilities, like code-generation of BPF 72program skeletons. The latter functionality is heavily used by these tools to 73load and interact with BPF programs. 74 75Given bpftool package can't yet be expected to be available widely across many 76distributions, bpftool binary is checked in into BCC repository in bin/ 77subdirectory. Once bpftool package is more widely available, this can be 78changed in favor of using pre-packaged version of bpftool. 79 80 81Re-compiling your Kernel with CONFIG_DEBUG_INFO_BTF=y 82----------------------------------------------------- 83libbpf probes to see if your sys fs exports the file `/sys/kernel/btf/vmlinux` (from Kernel 5.5+) or if you have the ELF version in your system [`code`](https://github.com/libbpf/libbpf/blob/master/src/btf.c) 84Please note the ELF file could exist without the BTF info in it. Your Kconfig should contain the options below 85 861. Compile options 87```code 88CONFIG_DEBUG_INFO_BTF=y 89CONFIG_DEBUG_INFO=y 90``` 912. Also, make sure that you have pahole 1.13 (or preferably 1.16+) during the 92kernel build (it comes from dwarves package). Without it, BTF won't be 93generated, and on older kernels you'd get only warning, but still would 94build kernel successfully 95 96Running in kernels without CONFIG_DEBUG_INFO_BTF=y 97-------------------------------------------------- 98 99It's possible to run some tools in kernels that don't expose 100`/sys/kernel/btf/vmlinux`. For those cases, 101[BTFGen](https://lore.kernel.org/bpf/[email protected]) 102and [BTFHub](https://github.com/aquasecurity/btfhub) can be used to 103generate small BTF files for the most popular Linux distributions that 104are shipped with the tools in order to provide the needed information to 105perform the CO-RE relocations when loading the eBPF programs. 106 107If you haven't cloned the 108[btfhub-archive](https://github.com/aquasecurity/btfhub) repository, you 109can run make and it'll clone it for you into the `$HOME/.local/share` 110directory: 111 112```bash 113make ENABLE_MIN_CORE_BTFS=1 -j$(nproc) 114``` 115 116If you have a local copy of such repository, you can pass it's location 117to avoid cloning it again: 118 119```bash 120make ENABLE_MIN_CORE_BTFS=1 BTF_HUB_ARCHIVE=<path_to_btfhub-archive> -j$(nproc) 121``` 122