bpftool-gen(8)

💖 NAME 💖

bpftool-gen — a tool for BPF code-generation ✨ (yeah, this is bpftool-gen(8), straight out of the System Manager's Manual, hiii bestie 💅)

---

✨ SYNOPSIS ✨

bpftool [OPTIONS] gen COMMAND

OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug } | {
-L | --use-loader } | [ { -S | --sign } {-k <private_key.pem>} -i
<certificate.x509> ] }

COMMAND := { object | skeleton | help }

---

🎀 GEN COMMANDS 🎀

bpftool gen object OUTPUT_FILE INPUT_FILE [INPUT_FILE...]
bpftool gen skeleton FILE [name OBJECT_NAME]
bpftool gen subskeleton FILE [name OBJECT_NAME]
bpftool gen min_core_btf INPUT OUTPUT OBJECT [OBJECT...]
bpftool gen help

---

🦋 DESCRIPTION 🦋

bpftool gen object OUTPUT_FILE INPUT_FILE [INPUT_FILE...]

okay so this one statically links (like, combines) one or more INPUT_FILEs together into a single resulting OUTPUT_FILE. Every single file involved here is a BPF ELF object file. 🧚

The rules of BPF static linking are mostly the same as for user-space object files, but on top of combining data and instruction sections, .BTF and .BTF.ext data (if present in any of the input files) get combined together too. And .BTF data is deduplicated, so all the common types across INPUT_FILEs are literally only represented once in the resulting BTF information. Efficient queen 💅

BPF static linking lets you partition BPF source code into individually compiled files, and then link those into a single resulting BPF object file. That file can be used to generate a BPF skeleton (with the gen skeleton command) or passed directly into libbpf (using the bpf_object__open() family of APIs). 🤝

---

bpftool gen skeleton FILE

Generate a BPF skeleton C header file for a given FILE. 🎀

A BPF skeleton is an alternative interface to the existing libbpf APIs for working with BPF objects. The skeleton code is intended to significantly shorten and simplify the code you write to load and work with BPF programs from the userspace side. The generated code is tailored to the specific input BPF object FILE, reflecting its structure by listing out the available maps, program, variables, etc. Skeleton eliminates the need to look up all those mentioned components by name — instead, if skeleton instantiation succeeds, they're populated in the skeleton structure as valid libbpf types (e.g., struct bpf_map pointer) and can be passed to existing generic libbpf APIs. obsessed fr 🫶

And on top of simple, reliable access to maps and programs, the skeleton also provides storage for BPF links (struct bpf_link) for each BPF program within the BPF object. When requested, supported BPF programs get automatically attached, and the resulting BPF links get stored for further use by the user in pre-allocated fields in the skeleton struct. For BPF programs that libbpf can't automatically attach, the user can attach them manually — but they should store the resulting BPF link in the per-program link field. All such set up links get automatically destroyed on BPF skeleton destruction. Which eliminates the need for users to manage links manually and rely on libbpf support to detach programs and free up resources. no cap ✨

Another facility the BPF skeleton provides is an interface to global variables of all supported kinds: mutable, read-only, and extern ones too. This interface allows you to pre-setup initial values of variables before the BPF object is loaded and verified by the kernel. And for non-read-only variables, the same interface can be used to fetch values of global variables on the userspace side — even if they're modified by BPF code. 👑

During skeleton generation, the contents of the source BPF object FILE is embedded within the generated code, so it's not necessary to keep it around. This ensures the skeleton and the BPF object file are matching 1-to-1 and always stay in sync. The generated code is dual-licensed under LGPL-2.1 and BSD-2-Clause licenses. 📜

It is a design goal and a guarantee that skeleton interfaces are interoperable with generic libbpf APIs. You should always be able to use the skeleton API to create and load a BPF object, and later use libbpf APIs to keep working with specific maps, programs, etc. 💖

As part of the skeleton, a few custom functions are generated. Each of them is prefixed with the object name. The object name can either be derived from the object file name — like, if the BPF object file name is example.o, the BPF object name will be example — or it can be specified explicitly through the name OBJECT_NAME parameter. The following custom functions are provided (assuming example as the object name):

• example__open and example__open_opts. These functions are used to instantiate the skeleton. It corresponds to libbpf's bpf_object__open() API. The _opts variant accepts extra bpf_object_open_opts options.
• example__load. This function creates maps, loads and verifies BPF programs, and initializes global data maps. It corresponds to libbpf's bpf_object__load() API.
• example__open_and_load — combines example__open and example__load invocations in one commonly used operation.
• example__attach and example__detach. This pair of functions lets you attach and detach, correspondingly, an already loaded BPF object. Only BPF programs of types supported by libbpf for auto-attachment will be auto-attached and their corresponding BPF links instantiated. For other BPF programs, the user can manually create a BPF link and assign it to the corresponding fields in the skeleton struct. example__detach will detach both links created automatically, as well as those populated by the user manually.
• example__destroy. Detach and unload BPF programs, free up all the resources used by the skeleton and the BPF object.

If the BPF object has global variables, corresponding structs with memory layout corresponding to the global data data section layout will be created. Currently supported ones are: .data, .bss, .rodata, and .kconfig structs/data sections. These data sections/structs can be used to set up initial values of variables, if set before example__load. Afterwards, if the target kernel supports memory-mapped BPF arrays, the same structs can be used to fetch and update (non-read-only) data from userspace, with the same simplicity as for the BPF side. 🌈

---

bpftool gen subskeleton FILE

Generate a BPF subskeleton C header file for a given FILE. 🌸

Subskeletons are similar to skeletons, except they do not own the corresponding maps, programs, or global variables. They require that the object file used to generate them is already loaded into a bpf_object by some other means. 🙈

This functionality is useful when a library is included into a larger BPF program. A subskeleton for the library would have access to all objects and globals defined in it, without having to know about the larger program. 💜

Consequently, there are only two functions defined for subskeletons:

• example__open(bpf_object*). Instantiates a subskeleton from an already opened (but not necessarily loaded) bpf_object.
• example__destroy(). Frees the storage for the subskeleton but does not unload any BPF programs or maps.

---

bpftool gen min_core_btf INPUT OUTPUT OBJECT [OBJECT...]

Generate a minimum BTF file as OUTPUT, derived from a given INPUT BTF file, containing all needed BTF types so one, or more, given eBPF objects' CO-RE relocations may be satisfied. 🔥

When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF, libbpf, when loading an eBPF object, has to rely on external BTF files to be able to calculate CO-RE relocations. 😭

Usually, an external BTF file is built from existing kernel DWARF data using pahole. It contains all the types used by its respective kernel image and, because of that, is big. 💀

The min_core_btf feature builds smaller BTF files, customized to one or multiple eBPF objects, so they can be distributed together with an eBPF CO-RE based application — turning the application portable to different kernel versions. 🦋

Check the examples below for more information on how to use it.

---

bpftool gen help

Print short help message. 🎀

---

💅 OPTIONS 💅

• -h, --help — Print short help message (similar to bpftool help).
• -V, --version — Print bpftool's version number (similar to bpftool version), the number of the libbpf version in use, and optional features that were included when bpftool was compiled. Optional features include linking against LLVM or libbfd to provide the disassembler for JIT-ted programs (bpftool prog dump jited) and usage of BPF skeletons (some features like bpftool prog profile or showing pids associated to BPF objects may rely on it). ✨
• -j, --json — Generate JSON output. For commands that cannot produce JSON, this option has no effect.
• -p, --pretty — Generate human-readable JSON output. Implies -j.
• -d, --debug — Print all logs available, even debug-level information. This includes logs from libbpf as well as from the verifier, when attempting to load programs. 🐛
• -L, --use-loader — For skeletons, generate a "light" skeleton (also known as a "loader" skeleton). A light skeleton contains a loader eBPF program. It does not use the majority of the libbpf infrastructure, and does not need libelf. 🧚
• -S, --sign — For skeletons, generate a signed skeleton. This option must be used with -k and -i. Using this flag implicitly enables --use-loader. 🔏
• -k <private_key.pem> — Path to the private key file in PEM format, required for signing.
• -i <certificate.x509> — Path to the X.509 certificate file in PEM or DER format, required for signing.

🎀 EXAMPLES 🎀

ok so this is the part where it all comes together, bestie. grab a snack, we're building a whole BPF app from scratch ✨

first up, our three little source files. look at them. precious.

$ cat example1.bpf.c

   #include <stdbool.h>
   #include <linux/ptrace.h>
   #include <linux/bpf.h>
   #include <bpf/bpf_helpers.h>

   const volatile int param1 = 42;
   bool global_flag = true;
   struct { int x; } data = {};

   SEC("raw_tp/sys_enter")
   int handle_sys_enter(struct pt_regs *ctx)
   {
         static long my_static_var;
         if (global_flag)
                 my_static_var++;
         else
                 data.x += param1;
         return 0;
   }

$ cat example2.bpf.c

   #include <linux/ptrace.h>
   #include <linux/bpf.h>
   #include <bpf/bpf_helpers.h>

   struct {
         __uint(type, BPF_MAP_TYPE_HASH);
         __uint(max_entries, 128);
         __type(key, int);
         __type(value, long);
   } my_map SEC(".maps");

   SEC("raw_tp/sys_exit")
   int handle_sys_exit(struct pt_regs *ctx)
   {
         int zero = 0;
         bpf_map_lookup_elem(&my_map, &zero);
         return 0;
   }

$ cat example3.bpf.c

   #include <linux/ptrace.h>
   #include <linux/bpf.h>
   #include <bpf/bpf_helpers.h>
   /* This header file is provided by the bpf_testmod module. */
   #include "bpf_testmod.h"

   int test_2_result = 0;

   /* bpf_Testmod.ko calls this function, passing a "4"
    * and testmod_map->data.
    */
   SEC("struct_ops/test_2")
   void BPF_PROG(test_2, int a, int b)
   {
         test_2_result = a + b;
   }

   SEC(".struct_ops")
   struct bpf_testmod_ops testmod_map = {
         .test_2 = (void *)test_2,
         .data = 0x1,
   };

so this is an example BPF application with three BPF programs plus a lil mix of BPF maps AND global variables. and the source code is split across three separate source code files, because we're organized like that 💅

compile each one, no cap:

$ clang --target=bpf -g example1.bpf.c -o example1.bpf.o

$ clang --target=bpf -g example2.bpf.c -o example2.bpf.o

$ clang --target=bpf -g example3.bpf.c -o example3.bpf.o

$ bpftool gen object example.bpf.o example1.bpf.o example2.bpf.o example3.bpf.o

okay so this whole lil command stack compiles example1.bpf.c, example2.bpf.c and example3.bpf.c one by one, and then statically links those respective object files together into the final BPF ELF object file example.bpf.o. iconic behavior honestly ✨

now the moment we've all been waiting for — the skeleton:

$ bpftool gen skeleton example.bpf.o name example | tee example.skel.h

   /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */

   /* THIS FILE IS AUTOGENERATED! */
   #ifndef __EXAMPLE_SKEL_H__
   #define __EXAMPLE_SKEL_H__

   #include <stdlib.h>
   #include <bpf/libbpf.h>

   struct example {
         struct bpf_object_skeleton *skeleton;
         struct bpf_object *obj;
         struct {
                 struct bpf_map *rodata;
                 struct bpf_map *data;
                 struct bpf_map *bss;
                 struct bpf_map *my_map;
                 struct bpf_map *testmod_map;
         } maps;
         struct {
                 struct example__testmod_map__bpf_testmod_ops {
                         const struct bpf_program *test_1;
                         const struct bpf_program *test_2;
                         int data;
                 } *testmod_map;
         } struct_ops;
         struct {
                 struct bpf_program *handle_sys_enter;
                 struct bpf_program *handle_sys_exit;
         } progs;
         struct {
                 struct bpf_link *handle_sys_enter;
                 struct bpf_link *handle_sys_exit;
         } links;
         struct example__bss {
                 struct {
                         int x;
                 } data;
                 int test_2_result;
         } *bss;
         struct example__data {
                 _Bool global_flag;
                 long int handle_sys_enter_my_static_var;
         } *data;
         struct example__rodata {
                 int param1;
         } *rodata;
   };

   static void example__destroy(struct example *obj);
   static inline struct example *example__open_opts(
                 const struct bpf_object_open_opts *opts);
   static inline struct example *example__open();
   static inline int example__load(struct example *obj);
   static inline struct example *example__open_and_load();
   static inline int example__attach(struct example *obj);
   static inline void example__detach(struct example *obj);

   #endif /* __EXAMPLE_SKEL_H__ */

and here's how you actually use that gorgeous thing:

$ cat example.c

   #include "example.skel.h"

   int main()
   {
         struct example *skel;
         int err = 0;

         skel = example__open();
         if (!skel)
                 goto cleanup;

         skel->rodata->param1 = 128;

         /* Change the value through the pointer of shadow type */
         skel->struct_ops.testmod_map->data = 13;

         err = example__load(skel);
         if (err)
                 goto cleanup;

         /* The result of the function test_2() */
         printf("test_2_result: %d\n", skel->bss->test_2_result);

         err = example__attach(skel);
         if (err)
                 goto cleanup;

         /* all libbpf APIs are usable */
         printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
         printf("sys_enter prog FD: %d\n",
                bpf_program__fd(skel->progs.handle_sys_enter));

         /* detach and re-attach sys_exit program */
         bpf_link__destroy(skel->links.handle_sys_exit);
         skel->links.handle_sys_exit =
                 bpf_program__attach(skel->progs.handle_sys_exit);

         printf("my_static_var: %ld\n",
                skel->bss->handle_sys_enter_my_static_var);

   cleanup:
         example__destroy(skel);
         return err;
   }

run it and watch the magic happen 🦋

# ./example

   test_2_result: 17
   my_map name: my_map
   sys_enter prog FD: 8
   my_static_var: 7

and that's the whole thing working, periodt. what you just saw is a stripped-out version of the skeleton generated for the example code above — like not every single line made the highlight reel, you know? 🙈

---

🌸 min_core_btf 🌸

ok this one is my favorite lowkey. let's start by dumping a big ol' BTF file:

$ bpftool btf dump file 5.4.0-example.btf format raw

   [1] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
   [2] CONST '(anon)' type_id=1
   [3] VOLATILE '(anon)' type_id=1
   [4] ARRAY '(anon)' type_id=1 index_type_id=21 nr_elems=2
   [5] PTR '(anon)' type_id=8
   [6] CONST '(anon)' type_id=5
   [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=(none)
   [8] CONST '(anon)' type_id=7
   [9] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
   <long output>

and then dump the object file too:

$ bpftool btf dump file one.bpf.o format raw

   [1] PTR '(anon)' type_id=2
   [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=4
         'ent' type_id=3 bits_offset=0
         'id' type_id=7 bits_offset=64
         'args' type_id=9 bits_offset=128
         '__data' type_id=12 bits_offset=512
   [3] STRUCT 'trace_entry' size=8 vlen=4
         'type' type_id=4 bits_offset=0
         'flags' type_id=5 bits_offset=16
         'preempt_count' type_id=5 bits_offset=24
   <long output>

now ✨smush✨ it down to just the parts you actually need:

$ bpftool gen min_core_btf 5.4.0-example.btf 5.4.0-smaller.btf one.bpf.o

and look how tiny and cute the result is:

$ bpftool btf dump file 5.4.0-smaller.btf format raw

   [1] TYPEDEF 'pid_t' type_id=6
   [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=1
         'args' type_id=4 bits_offset=128
   [3] STRUCT 'task_struct' size=9216 vlen=2
         'pid' type_id=1 bits_offset=17920
         'real_parent' type_id=7 bits_offset=18048
   [4] ARRAY '(anon)' type_id=5 index_type_id=8 nr_elems=6
   [5] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
   [6] TYPEDEF '__kernel_pid_t' type_id=8
   [7] PTR '(anon)' type_id=3
   [8] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
   <end>

so now the 5.4.0-smaller.btf file can be used by libbpf as an external BTF file when it loads the one.bpf.o object into the 5.4.0-example kernel 💜

okay bestie, important lil caveat so you don't get got: the generated BTF file will NOT let other eBPF objects load. just the ones you gave to min_core_btf. it's exclusive like that 💅

here's what that looks like in code:

LIBBPF_OPTS(bpf_object_open_opts, opts, .btf_custom_path = "5.4.0-smaller.btf");
struct bpf_object *obj;

obj = bpf_object__open_file("one.bpf.o", &opts);

...

---

👑 SEE ALSO 👑

go read these too, they're all icons in their own right 🫶

• bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8), bpftool-cgroup(8), bpftool-feature(8), bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-prog(8), bpftool-struct_ops(8), bpftool-token(8)

---

and that's a wrap on bpftool-gen(8), bestie!! 💖 this whole page comes straight from the bpftool source, and you'll find it filed under section 8 of the manual pages — bpftool-gen(8), as the footer so modestly reminds us. go forth and gen some skeletons, you ate fr fr ✨🎀