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 }] }
12
13          COMMAND := { skeleton | **help }
14

GEN COMMANDS

16       bpftool gen skeleton FILE
17       bpftool gen help
18
19

DESCRIPTION

21          bpftool gen skeleton FILE
22                 Generate BPF skeleton C header file for a given FILE.
23
24                 BPF  skeleton  is an alternative interface to existing libbpf
25                 APIs for working with BPF objects. Skeleton code is  intended
26                 to  significantly  shorten and simplify code to load and work
27                 with BPF programs from userspace side. Generated code is tai‐
28                 lored  to  specific  input  BPF  object  FILE, reflecting its
29                 structure by listing out available maps, program,  variables,
30                 etc.  Skeleton eliminates the need to lookup mentioned compo‐
31                 nents by name. Instead, if skeleton  instantiation  succeeds,
32                 they  are  populated  in  skeleton  structure as valid libbpf
33                 types (e.g., struct bpf_map pointer) and  can  be  passed  to
34                 existing generic libbpf APIs.
35
36                 In  addition  to  simple and reliable access to maps and pro‐
37                 grams, skeleton provides a  storage  for  BPF  links  (struct
38                 bpf_link)  for  each  BPF  program  within  BPF  object. When
39                 requested,  supported  BPF  programs  will  be  automatically
40                 attached  and  resulting  BPF links stored for further use by
41                 user in pre-allocated fields in skeleton struct. For BPF pro‐
42                 grams  that  can't  be automatically attached by libbpf, user
43                 can attach them manually, but store  resulting  BPF  link  in
44                 per-program  link  field. All such set up links will be auto‐
45                 matically destroyed on BPF skeleton destruction. This  elimi‐
46                 nates the need for users to manage links manually and rely on
47                 libbpf support to detach programs and free up resources.
48
49                 Another facility provided by BPF skeleton is an interface  to
50                 global  variables of all supported kinds: mutable, read-only,
51                 as well as extern ones. This interface  allows  to  pre-setup
52                 initial  values  of variables before BPF object is loaded and
53                 verified by kernel. For  non-read-only  variables,  the  same
54                 interface  can be used to fetch values of global variables on
55                 userspace side, even if they are modified by BPF code.
56
57                 During skeleton generation, contents  of  source  BPF  object
58                 FILE is embedded within generated code and is thus not neces‐
59                 sary to keep around. This ensures  skeleton  and  BPF  object
60                 file  are matching 1-to-1 and always stay in sync.  Generated
61                 code  is  dual-licensed  under  LGPL-2.1   and   BSD-2-Clause
62                 licenses.
63
64                 It  is  a  design goal and guarantee that skeleton interfaces
65                 are interoperable  with  generic  libbpf  APIs.  User  should
66                 always  be  able  to  use skeleton API to create and load BPF
67                 object, and later use libbpf APIs to keep working  with  spe‐
68                 cific maps, programs, etc.
69
70                 As  part  of  skeleton,  few  custom functions are generated.
71                 Each of them is  prefixed  with  object  name,  derived  from
72                 object file name. I.e., if BPF object file name is example.o,
73                 BPF object name will be example. The following  custom  func‐
74                 tions are provided in such case:
75
76                 · example__open  and example__open_opts.  These functions are
77                   used to instantiate skeleton. It  corresponds  to  libbpf's
78                   bpf_object__open()   API.   _opts  variants  accepts  extra
79                   bpf_object_open_opts options.
80
81                 · example__load.  This function creates maps, loads and veri‐
82                   fies  BPF programs, initializes global data maps. It corre‐
83                   sponds to libppf's bpf_object__load API.
84
85                 · example__open_and_load  combines  example__open  and  exam‐
86                   ple__load invocations in one commonly used operation.
87
88                 · example__attach  and example__detach This pair of functions
89                   allow to attach and detach, correspondingly, already loaded
90                   BPF  object. Only BPF programs of types supported by libbpf
91                   for auto-attachment will be auto-attached and their  corre‐
92                   sponding  BPF  links  instantiated. For other BPF programs,
93                   user can manually create a BPF link and assign it to corre‐
94                   sponding  fields  in  skeleton struct. example__detach will
95                   detach both links created automatically, as well  as  those
96                   populated by user manually.
97
98                 · example__destroy  Detach  and  unload BPF programs, free up
99                   all the resources used by skeleton and BPF object.
100
101                 If BPF object has  global  variables,  corresponding  structs
102                 with  memory layout corresponding to global data data section
103                 layout will be created. Currently supported ones are:  .data,
104                 .bss,  .rodata,  and  .kconfig  structs/data sections.  These
105                 data sections/structs can be used to set up initial values of
106                 variables,  if set before example__load.  Afterwards, if tar‐
107                 get kernel supports memory-mapped BPF  arrays,  same  structs
108                 can  be  used  to  fetch and update (non-read-only) data from
109                 userspace, with same simplicity as for BPF side.
110
111          bpftool gen help
112                 Print short help message.
113

OPTIONS

115          -h, --help
116                 Print short generic help message (similar to bpftool help).
117
118          -V, --version
119                 Print version number (similar to bpftool version).
120
121          -j, --json
122                 Generate JSON output. For commands that cannot produce  JSON,
123                 this option has no effect.
124
125          -p, --pretty
126                 Generate human-readable JSON output. Implies -j.
127
128          -d, --debug
129                 Print  all  logs available from libbpf, including debug-level
130                 information.
131

EXAMPLES

133       $ cat example.c
134
135          #include <stdbool.h>
136          #include <linux/ptrace.h>
137          #include <linux/bpf.h>
138          #include "bpf_helpers.h"
139
140          const volatile int param1 = 42;
141          bool global_flag = true;
142          struct { int x; } data = {};
143
144          struct {
145                __uint(type, BPF_MAP_TYPE_HASH);
146                __uint(max_entries, 128);
147                __type(key, int);
148                __type(value, long);
149          } my_map SEC(".maps");
150
151          SEC("raw_tp/sys_enter")
152          int handle_sys_enter(struct pt_regs *ctx)
153          {
154                static long my_static_var;
155                if (global_flag)
156                        my_static_var++;
157                else
158                        data.x += param1;
159                return 0;
160          }
161
162          SEC("raw_tp/sys_exit")
163          int handle_sys_exit(struct pt_regs *ctx)
164          {
165                int zero = 0;
166                bpf_map_lookup_elem(&my_map, &zero);
167                return 0;
168          }
169
170       This is example BPF application with two BPF programs and a mix of  BPF
171       maps and global variables.
172
173       $ bpftool gen skeleton example.o
174
175          /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
176
177          /* THIS FILE IS AUTOGENERATED! */
178          #ifndef __EXAMPLE_SKEL_H__
179          #define __EXAMPLE_SKEL_H__
180
181          #include <stdlib.h>
182          #include <bpf/libbpf.h>
183
184          struct example {
185                struct bpf_object_skeleton *skeleton;
186                struct bpf_object *obj;
187                struct {
188                        struct bpf_map *rodata;
189                        struct bpf_map *data;
190                        struct bpf_map *bss;
191                        struct bpf_map *my_map;
192                } maps;
193                struct {
194                        struct bpf_program *handle_sys_enter;
195                        struct bpf_program *handle_sys_exit;
196                } progs;
197                struct {
198                        struct bpf_link *handle_sys_enter;
199                        struct bpf_link *handle_sys_exit;
200                } links;
201                struct example__bss {
202                        struct {
203                                int x;
204                        } data;
205                } *bss;
206                struct example__data {
207                        _Bool global_flag;
208                        long int handle_sys_enter_my_static_var;
209                } *data;
210                struct example__rodata {
211                        int param1;
212                } *rodata;
213          };
214
215          static void example__destroy(struct example *obj);
216          static inline struct example *example__open_opts(
217                        const struct bpf_object_open_opts *opts);
218          static inline struct example *example__open();
219          static inline int example__load(struct example *obj);
220          static inline struct example *example__open_and_load();
221          static inline int example__attach(struct example *obj);
222          static inline void example__detach(struct example *obj);
223
224          #endif /* __EXAMPLE_SKEL_H__ */
225
226       $ cat example_user.c
227
228          #include "example.skel.h"
229
230          int main()
231          {
232                struct example *skel;
233                int err = 0;
234
235                skel = example__open();
236                if (!skel)
237                        goto cleanup;
238
239                skel->rodata->param1 = 128;
240
241                err = example__load(skel);
242                if (err)
243                        goto cleanup;
244
245                err = example__attach(skel);
246                if (err)
247                        goto cleanup;
248
249                /* all libbpf APIs are usable */
250                printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
251                printf("sys_enter prog FD: %d\n",
252                       bpf_program__fd(skel->progs.handle_sys_enter));
253
254                /* detach and re-attach sys_exit program */
255                bpf_link__destroy(skel->links.handle_sys_exit);
256                skel->links.handle_sys_exit =
257                        bpf_program__attach(skel->progs.handle_sys_exit);
258
259                printf("my_static_var: %ld\n",
260                       skel->bss->handle_sys_enter_my_static_var);
261
262          cleanup:
263                example__destroy(skel);
264                return err;
265          }
266
267       # ./example_user
268
269          my_map name: my_map
270          sys_enter prog FD: 8
271          my_static_var: 7
272
273       This  is a stripped-out version of skeleton generated for above example
274       code.
275

SEE ALSO

277          bpf(2), bpf-helpers(7), bpftool(8), bpftool-map(8), bpftool-prog(8),
278          bpftool-cgroup(8),        bpftool-feature(8),        bpftool-net(8),
279          bpftool-perf(8), bpftool-btf(8)
280
281
282
283
284                                                                BPFTOOL-GEN(8)
Impressum