1BPFTOOL-GEN(8) BPFTOOL-GEN(8)
2
6 bpftool-gen - tool for BPF code-generation
7
9 bpftool [OPTIONS] gen COMMAND
10 OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug }
12 | { -l | --legacy } | { -L | --use-loader } }
13 COMMAND := { object | skeleton | help }
15
17 bpftool gen object OUTPUT_FILE INPUT_FILE [INPUT_FILE...]
18 bpftool gen skeleton FILE [name OBJECT_NAME]
19 bpftool gen subskeleton FILE [name OBJECT_NAME]
20 bpftool gen min_core_btf INPUT OUTPUT OBJECT [OBJECT...]
21 bpftool gen help
22
25 bpftool gen object OUTPUT_FILE INPUT_FILE [INPUT_FILE...]
26 Statically link (combine) together one or more INPUT_FILE's
27 into a single resulting OUTPUT_FILE. All the files involved
28 are BPF ELF object files.
29 The rules of BPF static linking are mostly the same as for
31 user-space object files, but in addition to combining data
32 and instruction sections, .BTF and .BTF.ext (if present in
33 any of the input files) data are combined together. .BTF data
34 is deduplicated, so all the common types across INPUT_FILE's
35 will only be represented once in the resulting BTF informa‐
36 tion.
37 BPF static linking allows to partition BPF source code into
39 individually compiled files that are then linked into a sin‐
40 gle resulting BPF object file, which can be used to generated
41 BPF skeleton (with gen skeleton command) or passed directly
42 into libbpf (using bpf_object__open() family of APIs).
43 bpftool gen skeleton FILE
45 Generate BPF skeleton C header file for a given FILE.
46 BPF skeleton is an alternative interface to existing libbpf
48 APIs for working with BPF objects. Skeleton code is intended
49 to significantly shorten and simplify code to load and work
50 with BPF programs from userspace side. Generated code is tai‐
51 lored to specific input BPF object FILE, reflecting its
52 structure by listing out available maps, program, variables,
53 etc. Skeleton eliminates the need to lookup mentioned compo‐
54 nents by name. Instead, if skeleton instantiation succeeds,
55 they are populated in skeleton structure as valid libbpf
56 types (e.g., struct bpf_map pointer) and can be passed to ex‐
57 isting generic libbpf APIs.
58 In addition to simple and reliable access to maps and pro‐
60 grams, skeleton provides a storage for BPF links (struct
61 bpf_link) for each BPF program within BPF object. When re‐
62 quested, supported BPF programs will be automatically at‐
63 tached and resulting BPF links stored for further use by user
64 in pre-allocated fields in skeleton struct. For BPF programs
65 that can't be automatically attached by libbpf, user can at‐
66 tach them manually, but store resulting BPF link in per-pro‐
67 gram link field. All such set up links will be automatically
68 destroyed on BPF skeleton destruction. This eliminates the
69 need for users to manage links manually and rely on libbpf
70 support to detach programs and free up resources.
71 Another facility provided by BPF skeleton is an interface to
73 global variables of all supported kinds: mutable, read-only,
74 as well as extern ones. This interface allows to pre-setup
75 initial values of variables before BPF object is loaded and
76 verified by kernel. For non-read-only variables, the same in‐
77 terface can be used to fetch values of global variables on
78 userspace side, even if they are modified by BPF code.
79 During skeleton generation, contents of source BPF object
81 FILE is embedded within generated code and is thus not neces‐
82 sary to keep around. This ensures skeleton and BPF object
83 file are matching 1-to-1 and always stay in sync. Generated
84 code is dual-licensed under LGPL-2.1 and BSD-2-Clause li‐
85 censes.
86 It is a design goal and guarantee that skeleton interfaces
88 are interoperable with generic libbpf APIs. User should al‐
89 ways be able to use skeleton API to create and load BPF ob‐
90 ject, and later use libbpf APIs to keep working with specific
91 maps, programs, etc.
92 As part of skeleton, few custom functions are generated.
94 Each of them is prefixed with object name. Object name can
95 either be derived from object file name, i.e., if BPF object
96 file name is example.o, BPF object name will be example. Ob‐
97 ject name can be also specified explicitly through name OB‐
98 JECT_NAME parameter. The following custom functions are pro‐
99 vided (assuming example as the object name):
100 • example__open and example__open_opts. These functions are
102 used to instantiate skeleton. It corresponds to libbpf's
103 bpf_object__open() API. _opts variants accepts extra
104 bpf_object_open_opts options.
105 • example__load. This function creates maps, loads and veri‐
107 fies BPF programs, initializes global data maps. It corre‐
108 sponds to libppf's bpf_object__load() API.
109 • example__open_and_load combines example__open and exam‐
111 ple__load invocations in one commonly used operation.
112 • example__attach and example__detach This pair of functions
114 allow to attach and detach, correspondingly, already loaded
115 BPF object. Only BPF programs of types supported by libbpf
116 for auto-attachment will be auto-attached and their corre‐
117 sponding BPF links instantiated. For other BPF programs,
118 user can manually create a BPF link and assign it to corre‐
119 sponding fields in skeleton struct. example__detach will
120 detach both links created automatically, as well as those
121 populated by user manually.
122 • example__destroy Detach and unload BPF programs, free up
124 all the resources used by skeleton and BPF object.
125 If BPF object has global variables, corresponding structs
127 with memory layout corresponding to global data data section
128 layout will be created. Currently supported ones are: .data,
129 .bss, .rodata, and .kconfig structs/data sections. These
130 data sections/structs can be used to set up initial values of
131 variables, if set before example__load. Afterwards, if tar‐
132 get kernel supports memory-mapped BPF arrays, same structs
133 can be used to fetch and update (non-read-only) data from
134 userspace, with same simplicity as for BPF side.
135 bpftool gen subskeleton FILE
137 Generate BPF subskeleton C header file for a given FILE.
138 Subskeletons are similar to skeletons, except they do not own
140 the corresponding maps, programs, or global variables. They
141 require that the object file used to generate them is already
142 loaded into a bpf_object by some other means.
143 This functionality is useful when a library is included into
145 a larger BPF program. A subskeleton for the library would
146 have access to all objects and globals defined in it, without
147 having to know about the larger program.
148 Consequently, there are only two functions defined for sub‐
150 skeletons:
151 • example__open(bpf_object*) Instantiates a subskeleton from
153 an already opened (but not necessarily loaded) bpf_object.
154 • example__destroy() Frees the storage for the subskeleton
156 but does not unload any BPF programs or maps.
157 bpftool gen min_core_btf INPUT OUTPUT OBJECT [OBJECT...]
159 Generate a minimum BTF file as OUTPUT, derived from a given
160 INPUT BTF file, containing all needed BTF types so one, or
161 more, given eBPF objects CO-RE relocations may be satisfied.
162 When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF,
164 libbpf, when loading an eBPF object, has to rely on external
165 BTF files to be able to calculate CO-RE relocations.
166 Usually, an external BTF file is built from existing kernel
168 DWARF data using pahole. It contains all the types used by
169 its respective kernel image and, because of that, is big.
170 The min_core_btf feature builds smaller BTF files, customized
172 to one or multiple eBPF objects, so they can be distributed
173 together with an eBPF CO-RE based application, turning the
174 application portable to different kernel versions.
175 Check examples bellow for more information how to use it.
177 bpftool gen help
179 Print short help message.
180
182 -h, --help
183 Print short help message (similar to bpftool help).
184 -V, --version
186 Print bpftool's version number (similar to bpftool version),
187 the number of the libbpf version in use, and optional fea‐
188 tures that were included when bpftool was compiled. Optional
189 features include linking against libbfd to provide the disas‐
190 sembler for JIT-ted programs (bpftool prog dump jited) and
191 usage of BPF skeletons (some features like bpftool prog pro‐
192 file or showing pids associated to BPF objects may rely on
193 it).
194 -j, --json
196 Generate JSON output. For commands that cannot produce JSON,
197 this option has no effect.
198 -p, --pretty
200 Generate human-readable JSON output. Implies -j.
201 -d, --debug
203 Print all logs available, even debug-level information. This
204 includes logs from libbpf as well as from the verifier, when
205 attempting to load programs.
206 -l, --legacy
208 Use legacy libbpf mode which has more relaxed BPF program re‐
209 quirements. By default, bpftool has more strict requirements
210 about section names, changes pinning logic and doesn't sup‐
211 port some of the older non-BTF map declarations.
212 See
214 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
215 for details.
216 -L, --use-loader
218 For skeletons, generate a "light" skeleton (also known as
219 "loader" skeleton). A light skeleton contains a loader eBPF
220 program. It does not use the majority of the libbpf infra‐
221 structure, and does not need libelf.
222
224 $ cat example1.bpf.c
225 #include <stdbool.h>
227 #include <linux/ptrace.h>
228 #include <linux/bpf.h>
229 #include <bpf/bpf_helpers.h>
230 const volatile int param1 = 42;
232 bool global_flag = true;
233 struct { int x; } data = {};
234 SEC("raw_tp/sys_enter")
236 int handle_sys_enter(struct pt_regs *ctx)
237 {
238 static long my_static_var;
239 if (global_flag)
240 my_static_var++;
241 else
242 data.x += param1;
243 return 0;
244 }
245 $ cat example2.bpf.c
247 #include <linux/ptrace.h>
249 #include <linux/bpf.h>
250 #include <bpf/bpf_helpers.h>
251 struct {
253 __uint(type, BPF_MAP_TYPE_HASH);
254 __uint(max_entries, 128);
255 __type(key, int);
256 __type(value, long);
257 } my_map SEC(".maps");
258 SEC("raw_tp/sys_exit")
260 int handle_sys_exit(struct pt_regs *ctx)
261 {
262 int zero = 0;
263 bpf_map_lookup_elem(&my_map, &zero);
264 return 0;
265 }
266 This is example BPF application with two BPF programs and a mix of BPF
268 maps and global variables. Source code is split across two source code
269 files.
270 $ clang -target bpf -g example1.bpf.c -o example1.bpf.o
272 $ clang -target bpf -g example2.bpf.c -o example2.bpf.o
274 $ bpftool gen object example.bpf.o example1.bpf.o example2.bpf.o
276 This set of commands compiles example1.bpf.c and example2.bpf.c indi‐
278 vidually and then statically links respective object files into the fi‐
279 nal BPF ELF object file example.bpf.o.
280 $ bpftool gen skeleton example.bpf.o name example | tee example.skel.h
282 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
284 /* THIS FILE IS AUTOGENERATED! */
286 #ifndef __EXAMPLE_SKEL_H__
287 #define __EXAMPLE_SKEL_H__
288 #include <stdlib.h>
290 #include <bpf/libbpf.h>
291 struct example {
293 struct bpf_object_skeleton *skeleton;
294 struct bpf_object *obj;
295 struct {
296 struct bpf_map *rodata;
297 struct bpf_map *data;
298 struct bpf_map *bss;
299 struct bpf_map *my_map;
300 } maps;
301 struct {
302 struct bpf_program *handle_sys_enter;
303 struct bpf_program *handle_sys_exit;
304 } progs;
305 struct {
306 struct bpf_link *handle_sys_enter;
307 struct bpf_link *handle_sys_exit;
308 } links;
309 struct example__bss {
310 struct {
311 int x;
312 } data;
313 } *bss;
314 struct example__data {
315 _Bool global_flag;
316 long int handle_sys_enter_my_static_var;
317 } *data;
318 struct example__rodata {
319 int param1;
320 } *rodata;
321 };
322 static void example__destroy(struct example *obj);
324 static inline struct example *example__open_opts(
325 const struct bpf_object_open_opts *opts);
326 static inline struct example *example__open();
327 static inline int example__load(struct example *obj);
328 static inline struct example *example__open_and_load();
329 static inline int example__attach(struct example *obj);
330 static inline void example__detach(struct example *obj);
331 #endif /* __EXAMPLE_SKEL_H__ */
333 $ cat example.c
335 #include "example.skel.h"
337 int main()
339 {
340 struct example *skel;
341 int err = 0;
342 skel = example__open();
344 if (!skel)
345 goto cleanup;
346 skel->rodata->param1 = 128;
348 err = example__load(skel);
350 if (err)
351 goto cleanup;
352 err = example__attach(skel);
354 if (err)
355 goto cleanup;
356 /* all libbpf APIs are usable */
358 printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
359 printf("sys_enter prog FD: %d\n",
360 bpf_program__fd(skel->progs.handle_sys_enter));
361 /* detach and re-attach sys_exit program */
363 bpf_link__destroy(skel->links.handle_sys_exit);
364 skel->links.handle_sys_exit =
365 bpf_program__attach(skel->progs.handle_sys_exit);
366 printf("my_static_var: %ld\n",
368 skel->bss->handle_sys_enter_my_static_var);
369 cleanup:
371 example__destroy(skel);
372 return err;
373 }
374 # ./example
376 my_map name: my_map
378 sys_enter prog FD: 8
379 my_static_var: 7
380 This is a stripped-out version of skeleton generated for above example
382 code.
383 min_core_btf
385 $ bpftool btf dump file 5.4.0-example.btf format raw
386 [1] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
388 [2] CONST '(anon)' type_id=1
389 [3] VOLATILE '(anon)' type_id=1
390 [4] ARRAY '(anon)' type_id=1 index_type_id=21 nr_elems=2
391 [5] PTR '(anon)' type_id=8
392 [6] CONST '(anon)' type_id=5
393 [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=(none)
394 [8] CONST '(anon)' type_id=7
395 [9] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
396 <long output>
397 $ bpftool btf dump file one.bpf.o format raw
399 [1] PTR '(anon)' type_id=2
401 [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=4
402 'ent' type_id=3 bits_offset=0
403 'id' type_id=7 bits_offset=64
404 'args' type_id=9 bits_offset=128
405 '__data' type_id=12 bits_offset=512
406 [3] STRUCT 'trace_entry' size=8 vlen=4
407 'type' type_id=4 bits_offset=0
408 'flags' type_id=5 bits_offset=16
409 'preempt_count' type_id=5 bits_offset=24
410 <long output>
411 $ bpftool gen min_core_btf 5.4.0-example.btf 5.4.0-smaller.btf
413 one.bpf.o
414 $ bpftool btf dump file 5.4.0-smaller.btf format raw
416 [1] TYPEDEF 'pid_t' type_id=6
418 [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=1
419 'args' type_id=4 bits_offset=128
420 [3] STRUCT 'task_struct' size=9216 vlen=2
421 'pid' type_id=1 bits_offset=17920
422 'real_parent' type_id=7 bits_offset=18048
423 [4] ARRAY '(anon)' type_id=5 index_type_id=8 nr_elems=6
424 [5] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
425 [6] TYPEDEF '__kernel_pid_t' type_id=8
426 [7] PTR '(anon)' type_id=3
427 [8] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
428 <end>
429 Now, the "5.4.0-smaller.btf" file may be used by libbpf as an external
431 BTF file when loading the "one.bpf.o" object into the "5.4.0-example"
432 kernel. Note that the generated BTF file won't allow other eBPF objects
433 to be loaded, just the ones given to min_core_btf.
434 LIBBPF_OPTS(bpf_object_open_opts, opts, .btf_custom_path = "5.4.0-smaller.btf");
436 struct bpf_object *obj;
437 obj = bpf_object__open_file("one.bpf.o", &opts);
439 ...
441
443 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
444 bpftool-cgroup(8), bpftool-feature(8), bpftool-iter(8),
445 bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8),
446 bpftool-prog(8), bpftool-struct_ops(8)
447 BPFTOOL-GEN(8)