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 |
13 { -L | --use-loader } }
14 COMMAND := { object | skeleton | help }
16
18 bpftool gen object OUTPUT_FILE INPUT_FILE [INPUT_FILE...]
19 bpftool gen skeleton FILE [name OBJECT_NAME]
20 bpftool gen help
21
24 bpftool gen object OUTPUT_FILE INPUT_FILE [INPUT_FILE...]
25 Statically link (combine) together one or more INPUT_FILE's
26 into a single resulting OUTPUT_FILE. All the files involved
27 are BPF ELF object files.
28 The rules of BPF static linking are mostly the same as for
30 user-space object files, but in addition to combining data
31 and instruction sections, .BTF and .BTF.ext (if present in
32 any of the input files) data are combined together. .BTF data
33 is deduplicated, so all the common types across INPUT_FILE's
34 will only be represented once in the resulting BTF informa‐
35 tion.
36 BPF static linking allows to partition BPF source code into
38 individually compiled files that are then linked into a sin‐
39 gle resulting BPF object file, which can be used to generated
40 BPF skeleton (with gen skeleton command) or passed directly
41 into libbpf (using bpf_object__open() family of APIs).
42 bpftool gen skeleton FILE
44 Generate BPF skeleton C header file for a given FILE.
45 BPF skeleton is an alternative interface to existing libbpf
47 APIs for working with BPF objects. Skeleton code is intended
48 to significantly shorten and simplify code to load and work
49 with BPF programs from userspace side. Generated code is tai‐
50 lored to specific input BPF object FILE, reflecting its
51 structure by listing out available maps, program, variables,
52 etc. Skeleton eliminates the need to lookup mentioned compo‐
53 nents by name. Instead, if skeleton instantiation succeeds,
54 they are populated in skeleton structure as valid libbpf
55 types (e.g., struct bpf_map pointer) and can be passed to ex‐
56 isting generic libbpf APIs.
57 In addition to simple and reliable access to maps and pro‐
59 grams, skeleton provides a storage for BPF links (struct
60 bpf_link) for each BPF program within BPF object. When re‐
61 quested, supported BPF programs will be automatically at‐
62 tached and resulting BPF links stored for further use by user
63 in pre-allocated fields in skeleton struct. For BPF programs
64 that can't be automatically attached by libbpf, user can at‐
65 tach them manually, but store resulting BPF link in per-pro‐
66 gram link field. All such set up links will be automatically
67 destroyed on BPF skeleton destruction. This eliminates the
68 need for users to manage links manually and rely on libbpf
69 support to detach programs and free up resources.
70 Another facility provided by BPF skeleton is an interface to
72 global variables of all supported kinds: mutable, read-only,
73 as well as extern ones. This interface allows to pre-setup
74 initial values of variables before BPF object is loaded and
75 verified by kernel. For non-read-only variables, the same in‐
76 terface can be used to fetch values of global variables on
77 userspace side, even if they are modified by BPF code.
78 During skeleton generation, contents of source BPF object
80 FILE is embedded within generated code and is thus not neces‐
81 sary to keep around. This ensures skeleton and BPF object
82 file are matching 1-to-1 and always stay in sync. Generated
83 code is dual-licensed under LGPL-2.1 and BSD-2-Clause li‐
84 censes.
85 It is a design goal and guarantee that skeleton interfaces
87 are interoperable with generic libbpf APIs. User should al‐
88 ways be able to use skeleton API to create and load BPF ob‐
89 ject, and later use libbpf APIs to keep working with specific
90 maps, programs, etc.
91 As part of skeleton, few custom functions are generated.
93 Each of them is prefixed with object name. Object name can
94 either be derived from object file name, i.e., if BPF object
95 file name is example.o, BPF object name will be example. Ob‐
96 ject name can be also specified explicitly through name OB‐
97 JECT_NAME parameter. The following custom functions are pro‐
98 vided (assuming example as the object name):
99 • example__open and example__open_opts. These functions are
101 used to instantiate skeleton. It corresponds to libbpf's
102 bpf_object__open() API. _opts variants accepts extra
103 bpf_object_open_opts options.
104 • example__load. This function creates maps, loads and veri‐
106 fies BPF programs, initializes global data maps. It corre‐
107 sponds to libppf's bpf_object__load() API.
108 • example__open_and_load combines example__open and exam‐
110 ple__load invocations in one commonly used operation.
111 • example__attach and example__detach This pair of functions
113 allow to attach and detach, correspondingly, already loaded
114 BPF object. Only BPF programs of types supported by libbpf
115 for auto-attachment will be auto-attached and their corre‐
116 sponding BPF links instantiated. For other BPF programs,
117 user can manually create a BPF link and assign it to corre‐
118 sponding fields in skeleton struct. example__detach will
119 detach both links created automatically, as well as those
120 populated by user manually.
121 • example__destroy Detach and unload BPF programs, free up
123 all the resources used by skeleton and BPF object.
124 If BPF object has global variables, corresponding structs
126 with memory layout corresponding to global data data section
127 layout will be created. Currently supported ones are: .data,
128 .bss, .rodata, and .kconfig structs/data sections. These
129 data sections/structs can be used to set up initial values of
130 variables, if set before example__load. Afterwards, if tar‐
131 get kernel supports memory-mapped BPF arrays, same structs
132 can be used to fetch and update (non-read-only) data from
133 userspace, with same simplicity as for BPF side.
134 bpftool gen help
136 Print short help message.
137
139 -h, --help
140 Print short help message (similar to bpftool help).
141 -V, --version
143 Print version number (similar to bpftool version), and op‐
144 tional features that were included when bpftool was compiled.
145 Optional features include linking against libbfd to provide
146 the disassembler for JIT-ted programs (bpftool prog dump
147 jited) and usage of BPF skeletons (some features like bpftool
148 prog profile or showing pids associated to BPF objects may
149 rely on it).
150 -j, --json
152 Generate JSON output. For commands that cannot produce JSON,
153 this option has no effect.
154 -p, --pretty
156 Generate human-readable JSON output. Implies -j.
157 -d, --debug
159 Print all logs available, even debug-level information. This
160 includes logs from libbpf as well as from the verifier, when
161 attempting to load programs.
162 -L, --use-loader
164 For skeletons, generate a "light" skeleton (also known as
165 "loader" skeleton). A light skeleton contains a loader eBPF
166 program. It does not use the majority of the libbpf infra‐
167 structure, and does not need libelf.
168
170 $ cat example1.bpf.c
171 #include <stdbool.h>
173 #include <linux/ptrace.h>
174 #include <linux/bpf.h>
175 #include <bpf/bpf_helpers.h>
176 const volatile int param1 = 42;
178 bool global_flag = true;
179 struct { int x; } data = {};
180 SEC("raw_tp/sys_enter")
182 int handle_sys_enter(struct pt_regs *ctx)
183 {
184 static long my_static_var;
185 if (global_flag)
186 my_static_var++;
187 else
188 data.x += param1;
189 return 0;
190 }
191 $ cat example2.bpf.c
193 #include <linux/ptrace.h>
195 #include <linux/bpf.h>
196 #include <bpf/bpf_helpers.h>
197 struct {
199 __uint(type, BPF_MAP_TYPE_HASH);
200 __uint(max_entries, 128);
201 __type(key, int);
202 __type(value, long);
203 } my_map SEC(".maps");
204 SEC("raw_tp/sys_exit")
206 int handle_sys_exit(struct pt_regs *ctx)
207 {
208 int zero = 0;
209 bpf_map_lookup_elem(&my_map, &zero);
210 return 0;
211 }
212 This is example BPF application with two BPF programs and a mix of BPF
214 maps and global variables. Source code is split across two source code
215 files.
216 $ clang -target bpf -g example1.bpf.c -o example1.bpf.o $ clang -target
218 bpf -g example2.bpf.c -o example2.bpf.o $ bpftool gen object exam‐
219 ple.bpf.o example1.bpf.o example2.bpf.o
220 This set of commands compiles example1.bpf.c and example2.bpf.c indi‐
222 vidually and then statically links respective object files into the fi‐
223 nal BPF ELF object file example.bpf.o.
224 $ bpftool gen skeleton example.bpf.o name example | tee example.skel.h
226 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
228 /* THIS FILE IS AUTOGENERATED! */
230 #ifndef __EXAMPLE_SKEL_H__
231 #define __EXAMPLE_SKEL_H__
232 #include <stdlib.h>
234 #include <bpf/libbpf.h>
235 struct example {
237 struct bpf_object_skeleton *skeleton;
238 struct bpf_object *obj;
239 struct {
240 struct bpf_map *rodata;
241 struct bpf_map *data;
242 struct bpf_map *bss;
243 struct bpf_map *my_map;
244 } maps;
245 struct {
246 struct bpf_program *handle_sys_enter;
247 struct bpf_program *handle_sys_exit;
248 } progs;
249 struct {
250 struct bpf_link *handle_sys_enter;
251 struct bpf_link *handle_sys_exit;
252 } links;
253 struct example__bss {
254 struct {
255 int x;
256 } data;
257 } *bss;
258 struct example__data {
259 _Bool global_flag;
260 long int handle_sys_enter_my_static_var;
261 } *data;
262 struct example__rodata {
263 int param1;
264 } *rodata;
265 };
266 static void example__destroy(struct example *obj);
268 static inline struct example *example__open_opts(
269 const struct bpf_object_open_opts *opts);
270 static inline struct example *example__open();
271 static inline int example__load(struct example *obj);
272 static inline struct example *example__open_and_load();
273 static inline int example__attach(struct example *obj);
274 static inline void example__detach(struct example *obj);
275 #endif /* __EXAMPLE_SKEL_H__ */
277 $ cat example.c
279 #include "example.skel.h"
281 int main()
283 {
284 struct example *skel;
285 int err = 0;
286 skel = example__open();
288 if (!skel)
289 goto cleanup;
290 skel->rodata->param1 = 128;
292 err = example__load(skel);
294 if (err)
295 goto cleanup;
296 err = example__attach(skel);
298 if (err)
299 goto cleanup;
300 /* all libbpf APIs are usable */
302 printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
303 printf("sys_enter prog FD: %d\n",
304 bpf_program__fd(skel->progs.handle_sys_enter));
305 /* detach and re-attach sys_exit program */
307 bpf_link__destroy(skel->links.handle_sys_exit);
308 skel->links.handle_sys_exit =
309 bpf_program__attach(skel->progs.handle_sys_exit);
310 printf("my_static_var: %ld\n",
312 skel->bss->handle_sys_enter_my_static_var);
313 cleanup:
315 example__destroy(skel);
316 return err;
317 }
318 # ./example
320 my_map name: my_map
322 sys_enter prog FD: 8
323 my_static_var: 7
324 This is a stripped-out version of skeleton generated for above example
326 code.
327
329 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
330 bpftool-cgroup(8), bpftool-feature(8), bpftool-iter(8),
331 bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8),
332 bpftool-prog(8), bpftool-struct_ops(8)
333 BPFTOOL-GEN(8)