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 help message (similar to bpftool help).
117 -V, --version
119 Print version number (similar to bpftool version), and
120 optional features that were included when bpftool was com‐
121 piled. Optional features include linking against libbfd to
122 provide the disassembler for JIT-ted programs (bpftool prog
123 dump jited) and usage of BPF skeletons (some features like
124 bpftool prog profile or showing pids associated to BPF
125 objects may rely on it).
126 -j, --json
128 Generate JSON output. For commands that cannot produce JSON,
129 this option has no effect.
130 -p, --pretty
132 Generate human-readable JSON output. Implies -j.
133 -d, --debug
135 Print all logs available, even debug-level information. This
136 includes logs from libbpf as well as from the verifier, when
137 attempting to load programs.
138
140 $ cat example.c
141 #include <stdbool.h>
143 #include <linux/ptrace.h>
144 #include <linux/bpf.h>
145 #include "bpf_helpers.h"
146 const volatile int param1 = 42;
148 bool global_flag = true;
149 struct { int x; } data = {};
150 struct {
152 __uint(type, BPF_MAP_TYPE_HASH);
153 __uint(max_entries, 128);
154 __type(key, int);
155 __type(value, long);
156 } my_map SEC(".maps");
157 SEC("raw_tp/sys_enter")
159 int handle_sys_enter(struct pt_regs *ctx)
160 {
161 static long my_static_var;
162 if (global_flag)
163 my_static_var++;
164 else
165 data.x += param1;
166 return 0;
167 }
168 SEC("raw_tp/sys_exit")
170 int handle_sys_exit(struct pt_regs *ctx)
171 {
172 int zero = 0;
173 bpf_map_lookup_elem(&my_map, &zero);
174 return 0;
175 }
176 This is example BPF application with two BPF programs and a mix of BPF
178 maps and global variables.
179 $ bpftool gen skeleton example.o
181 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
183 /* THIS FILE IS AUTOGENERATED! */
185 #ifndef __EXAMPLE_SKEL_H__
186 #define __EXAMPLE_SKEL_H__
187 #include <stdlib.h>
189 #include <bpf/libbpf.h>
190 struct example {
192 struct bpf_object_skeleton *skeleton;
193 struct bpf_object *obj;
194 struct {
195 struct bpf_map *rodata;
196 struct bpf_map *data;
197 struct bpf_map *bss;
198 struct bpf_map *my_map;
199 } maps;
200 struct {
201 struct bpf_program *handle_sys_enter;
202 struct bpf_program *handle_sys_exit;
203 } progs;
204 struct {
205 struct bpf_link *handle_sys_enter;
206 struct bpf_link *handle_sys_exit;
207 } links;
208 struct example__bss {
209 struct {
210 int x;
211 } data;
212 } *bss;
213 struct example__data {
214 _Bool global_flag;
215 long int handle_sys_enter_my_static_var;
216 } *data;
217 struct example__rodata {
218 int param1;
219 } *rodata;
220 };
221 static void example__destroy(struct example *obj);
223 static inline struct example *example__open_opts(
224 const struct bpf_object_open_opts *opts);
225 static inline struct example *example__open();
226 static inline int example__load(struct example *obj);
227 static inline struct example *example__open_and_load();
228 static inline int example__attach(struct example *obj);
229 static inline void example__detach(struct example *obj);
230 #endif /* __EXAMPLE_SKEL_H__ */
232 $ cat example_user.c
234 #include "example.skel.h"
236 int main()
238 {
239 struct example *skel;
240 int err = 0;
241 skel = example__open();
243 if (!skel)
244 goto cleanup;
245 skel->rodata->param1 = 128;
247 err = example__load(skel);
249 if (err)
250 goto cleanup;
251 err = example__attach(skel);
253 if (err)
254 goto cleanup;
255 /* all libbpf APIs are usable */
257 printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
258 printf("sys_enter prog FD: %d\n",
259 bpf_program__fd(skel->progs.handle_sys_enter));
260 /* detach and re-attach sys_exit program */
262 bpf_link__destroy(skel->links.handle_sys_exit);
263 skel->links.handle_sys_exit =
264 bpf_program__attach(skel->progs.handle_sys_exit);
265 printf("my_static_var: %ld\n",
267 skel->bss->handle_sys_enter_my_static_var);
268 cleanup:
270 example__destroy(skel);
271 return err;
272 }
273 # ./example_user
275 my_map name: my_map
277 sys_enter prog FD: 8
278 my_static_var: 7
279 This is a stripped-out version of skeleton generated for above example
281 code.
282
284 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
285 bpftool-cgroup(8), bpftool-feature(8), bpftool-iter(8),
286 bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8),
287 bpftool-prog(8), bpftool-struct_ops(8)
288 BPFTOOL-GEN(8)