1BPFTOOL-GEN(8)                                                  BPFTOOL-GEN(8)
2
3
4

NAME

6       bpftool-gen - tool for BPF code-generation
7

SYNOPSIS

9          bpftool [OPTIONS] gen COMMAND
10
11          OPTIONS  := { { -j | --json } [{ -p | --pretty }] | { -d | --debug }
12          | { -l | --legacy } | { -L | --use-loader } }
13
14          COMMAND := { object | skeleton | help }
15

GEN COMMANDS

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
23

DESCRIPTION

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
30                 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
38                 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
44          bpftool gen skeleton FILE
45                 Generate BPF skeleton C header file for a given FILE.
46
47                 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
59                 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
72                 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
80                 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
87                 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
93                 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
101example__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
106example__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
110example__open_and_load  combines  example__open  and  exam‐
111                   ple__load invocations in one commonly used operation.
112
113example__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
123example__destroy Detach and unload BPF  programs,  free  up
124                   all the resources used by skeleton and BPF object.
125
126                 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
136          bpftool gen subskeleton FILE
137                 Generate BPF subskeleton C header file for a given FILE.
138
139                 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
144                 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
149                 Consequently,  there  are only two functions defined for sub‐
150                 skeletons:
151
152example__open(bpf_object*) Instantiates a subskeleton  from
153                   an already opened (but not necessarily loaded) bpf_object.
154
155example__destroy()  Frees  the  storage for the subskeleton
156                   but does not unload any BPF programs or maps.
157
158          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
163                 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
167                 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
171                 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
176                 Check examples bellow for more information how to use it.
177
178          bpftool gen help
179                 Print short help message.
180

OPTIONS

182          -h, --help
183                 Print short help message (similar to bpftool help).
184
185          -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
195          -j, --json
196                 Generate JSON output. For commands that cannot produce  JSON,
197                 this option has no effect.
198
199          -p, --pretty
200                 Generate human-readable JSON output. Implies -j.
201
202          -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
207          -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
213                 See
214                 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
215                 for details.
216
217          -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

EXAMPLES

224       $ cat example1.bpf.c
225
226          #include <stdbool.h>
227          #include <linux/ptrace.h>
228          #include <linux/bpf.h>
229          #include <bpf/bpf_helpers.h>
230
231          const volatile int param1 = 42;
232          bool global_flag = true;
233          struct { int x; } data = {};
234
235          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
246       $ cat example2.bpf.c
247
248          #include <linux/ptrace.h>
249          #include <linux/bpf.h>
250          #include <bpf/bpf_helpers.h>
251
252          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
259          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
267       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
271       $ clang -target bpf -g example1.bpf.c -o example1.bpf.o
272
273       $ clang -target bpf -g example2.bpf.c -o example2.bpf.o
274
275       $ bpftool gen object example.bpf.o example1.bpf.o example2.bpf.o
276
277       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
281       $ bpftool gen skeleton example.bpf.o name example | tee example.skel.h
282
283          /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
284
285          /* THIS FILE IS AUTOGENERATED! */
286          #ifndef __EXAMPLE_SKEL_H__
287          #define __EXAMPLE_SKEL_H__
288
289          #include <stdlib.h>
290          #include <bpf/libbpf.h>
291
292          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
323          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
332          #endif /* __EXAMPLE_SKEL_H__ */
333
334       $ cat example.c
335
336          #include "example.skel.h"
337
338          int main()
339          {
340                struct example *skel;
341                int err = 0;
342
343                skel = example__open();
344                if (!skel)
345                        goto cleanup;
346
347                skel->rodata->param1 = 128;
348
349                err = example__load(skel);
350                if (err)
351                        goto cleanup;
352
353                err = example__attach(skel);
354                if (err)
355                        goto cleanup;
356
357                /* 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
362                /* 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
367                printf("my_static_var: %ld\n",
368                       skel->bss->handle_sys_enter_my_static_var);
369
370          cleanup:
371                example__destroy(skel);
372                return err;
373          }
374
375       # ./example
376
377          my_map name: my_map
378          sys_enter prog FD: 8
379          my_static_var: 7
380
381       This  is a stripped-out version of skeleton generated for above example
382       code.
383
384   min_core_btf
385       $ bpftool btf dump file 5.4.0-example.btf format raw
386
387          [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
398       $ bpftool btf dump file one.bpf.o format raw
399
400          [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
412       $  bpftool   gen   min_core_btf   5.4.0-example.btf   5.4.0-smaller.btf
413       one.bpf.o
414
415       $ bpftool btf dump file 5.4.0-smaller.btf format raw
416
417          [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
430       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
435          LIBBPF_OPTS(bpf_object_open_opts, opts, .btf_custom_path = "5.4.0-smaller.btf");
436          struct bpf_object *obj;
437
438          obj = bpf_object__open_file("one.bpf.o", &opts);
439
440          ...
441

SEE ALSO

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
448
449
450
451                                                                BPFTOOL-GEN(8)
Impressum