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 }] }
12 COMMAND := { skeleton | **help }
14
16 bpftool gen skeleton FILE
17 bpftool gen help
18
21 bpftool gen skeleton FILE
22 Generate BPF skeleton C header file for a given FILE.
23 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 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 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 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 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 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 · 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 · 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 · example__open_and_load combines example__open and exam‐
86 ple__load invocations in one commonly used operation.
87 · 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 · example__destroy Detach and unload BPF programs, free up
99 all the resources used by skeleton and BPF object.
100 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 bpftool gen help
112 Print short help message.
113
115 -h, --help
116 Print short generic help message (similar to bpftool help).
117 -V, --version
119 Print version number (similar to bpftool version).
120 -j, --json
122 Generate JSON output. For commands that cannot produce JSON,
123 this option has no effect.
124 -p, --pretty
126 Generate human-readable JSON output. Implies -j.
127 -d, --debug
129 Print all logs available from libbpf, including debug-level
130 information.
131
133 $ cat example.c
134 #include <stdbool.h>
136 #include <linux/ptrace.h>
137 #include <linux/bpf.h>
138 #include "bpf_helpers.h"
139 const volatile int param1 = 42;
141 bool global_flag = true;
142 struct { int x; } data = {};
143 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 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 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 This is example BPF application with two BPF programs and a mix of BPF
171 maps and global variables.
172 $ bpftool gen skeleton example.o
174 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
176 /* THIS FILE IS AUTOGENERATED! */
178 #ifndef __EXAMPLE_SKEL_H__
179 #define __EXAMPLE_SKEL_H__
180 #include <stdlib.h>
182 #include <bpf/libbpf.h>
183 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 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 #endif /* __EXAMPLE_SKEL_H__ */
225 $ cat example_user.c
227 #include "example.skel.h"
229 int main()
231 {
232 struct example *skel;
233 int err = 0;
234 skel = example__open();
236 if (!skel)
237 goto cleanup;
238 skel->rodata->param1 = 128;
240 err = example__load(skel);
242 if (err)
243 goto cleanup;
244 err = example__attach(skel);
246 if (err)
247 goto cleanup;
248 /* 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 /* 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 printf("my_static_var: %ld\n",
260 skel->bss->handle_sys_enter_my_static_var);
261 cleanup:
263 example__destroy(skel);
264 return err;
265 }
266 # ./example_user
268 my_map name: my_map
270 sys_enter prog FD: 8
271 my_static_var: 7
272 This is a stripped-out version of skeleton generated for above example
274 code.
275
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 BPFTOOL-GEN(8)