Loading...
1================
2bpftool-gen
3================
4-------------------------------------------------------------------------------
5tool for BPF code-generation
6-------------------------------------------------------------------------------
7
8:Manual section: 8
9
10SYNOPSIS
11========
12
13 **bpftool** [*OPTIONS*] **gen** *COMMAND*
14
15 *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
16
17 *COMMAND* := { **skeleton** | **help** }
18
19GEN COMMANDS
20=============
21
22| **bpftool** **gen skeleton** *FILE*
23| **bpftool** **gen help**
24
25DESCRIPTION
26===========
27 **bpftool gen skeleton** *FILE*
28 Generate BPF skeleton C header file for a given *FILE*.
29
30 BPF skeleton is an alternative interface to existing libbpf
31 APIs for working with BPF objects. Skeleton code is intended
32 to significantly shorten and simplify code to load and work
33 with BPF programs from userspace side. Generated code is
34 tailored to specific input BPF object *FILE*, reflecting its
35 structure by listing out available maps, program, variables,
36 etc. Skeleton eliminates the need to lookup mentioned
37 components by name. Instead, if skeleton instantiation
38 succeeds, they are populated in skeleton structure as valid
39 libbpf types (e.g., **struct bpf_map** pointer) and can be
40 passed to existing generic libbpf APIs.
41
42 In addition to simple and reliable access to maps and
43 programs, skeleton provides a storage for BPF links (**struct
44 bpf_link**) for each BPF program within BPF object. When
45 requested, supported BPF programs will be automatically
46 attached and resulting BPF links stored for further use by
47 user in pre-allocated fields in skeleton struct. For BPF
48 programs that can't be automatically attached by libbpf,
49 user can attach them manually, but store resulting BPF link
50 in per-program link field. All such set up links will be
51 automatically destroyed on BPF skeleton destruction. This
52 eliminates the need for users to manage links manually and
53 rely on libbpf support to detach programs and free up
54 resources.
55
56 Another facility provided by BPF skeleton is an interface to
57 global variables of all supported kinds: mutable, read-only,
58 as well as extern ones. This interface allows to pre-setup
59 initial values of variables before BPF object is loaded and
60 verified by kernel. For non-read-only variables, the same
61 interface can be used to fetch values of global variables on
62 userspace side, even if they are modified by BPF code.
63
64 During skeleton generation, contents of source BPF object
65 *FILE* is embedded within generated code and is thus not
66 necessary to keep around. This ensures skeleton and BPF
67 object file are matching 1-to-1 and always stay in sync.
68 Generated code is dual-licensed under LGPL-2.1 and
69 BSD-2-Clause licenses.
70
71 It is a design goal and guarantee that skeleton interfaces
72 are interoperable with generic libbpf APIs. User should
73 always be able to use skeleton API to create and load BPF
74 object, and later use libbpf APIs to keep working with
75 specific maps, programs, etc.
76
77 As part of skeleton, few custom functions are generated.
78 Each of them is prefixed with object name, derived from
79 object file name. I.e., if BPF object file name is
80 **example.o**, BPF object name will be **example**. The
81 following custom functions are provided in such case:
82
83 - **example__open** and **example__open_opts**.
84 These functions are used to instantiate skeleton. It
85 corresponds to libbpf's **bpf_object__open**\ () API.
86 **_opts** variants accepts extra **bpf_object_open_opts**
87 options.
88
89 - **example__load**.
90 This function creates maps, loads and verifies BPF
91 programs, initializes global data maps. It corresponds to
92 libppf's **bpf_object__load**\ () API.
93
94 - **example__open_and_load** combines **example__open** and
95 **example__load** invocations in one commonly used
96 operation.
97
98 - **example__attach** and **example__detach**
99 This pair of functions allow to attach and detach,
100 correspondingly, already loaded BPF object. Only BPF
101 programs of types supported by libbpf for auto-attachment
102 will be auto-attached and their corresponding BPF links
103 instantiated. For other BPF programs, user can manually
104 create a BPF link and assign it to corresponding fields in
105 skeleton struct. **example__detach** will detach both
106 links created automatically, as well as those populated by
107 user manually.
108
109 - **example__destroy**
110 Detach and unload BPF programs, free up all the resources
111 used by skeleton and BPF object.
112
113 If BPF object has global variables, corresponding structs
114 with memory layout corresponding to global data data section
115 layout will be created. Currently supported ones are: *.data*,
116 *.bss*, *.rodata*, and *.kconfig* structs/data sections.
117 These data sections/structs can be used to set up initial
118 values of variables, if set before **example__load**.
119 Afterwards, if target kernel supports memory-mapped BPF
120 arrays, same structs can be used to fetch and update
121 (non-read-only) data from userspace, with same simplicity
122 as for BPF side.
123
124 **bpftool gen help**
125 Print short help message.
126
127OPTIONS
128=======
129 -h, --help
130 Print short generic help message (similar to **bpftool help**).
131
132 -V, --version
133 Print version number (similar to **bpftool version**).
134
135 -j, --json
136 Generate JSON output. For commands that cannot produce JSON,
137 this option has no effect.
138
139 -p, --pretty
140 Generate human-readable JSON output. Implies **-j**.
141
142 -d, --debug
143 Print all logs available from libbpf, including debug-level
144 information.
145
146EXAMPLES
147========
148**$ cat example.c**
149::
150
151 #include <stdbool.h>
152 #include <linux/ptrace.h>
153 #include <linux/bpf.h>
154 #include "bpf_helpers.h"
155
156 const volatile int param1 = 42;
157 bool global_flag = true;
158 struct { int x; } data = {};
159
160 struct {
161 __uint(type, BPF_MAP_TYPE_HASH);
162 __uint(max_entries, 128);
163 __type(key, int);
164 __type(value, long);
165 } my_map SEC(".maps");
166
167 SEC("raw_tp/sys_enter")
168 int handle_sys_enter(struct pt_regs *ctx)
169 {
170 static long my_static_var;
171 if (global_flag)
172 my_static_var++;
173 else
174 data.x += param1;
175 return 0;
176 }
177
178 SEC("raw_tp/sys_exit")
179 int handle_sys_exit(struct pt_regs *ctx)
180 {
181 int zero = 0;
182 bpf_map_lookup_elem(&my_map, &zero);
183 return 0;
184 }
185
186This is example BPF application with two BPF programs and a mix of BPF maps
187and global variables.
188
189**$ bpftool gen skeleton example.o**
190::
191
192 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
193
194 /* THIS FILE IS AUTOGENERATED! */
195 #ifndef __EXAMPLE_SKEL_H__
196 #define __EXAMPLE_SKEL_H__
197
198 #include <stdlib.h>
199 #include <bpf/libbpf.h>
200
201 struct example {
202 struct bpf_object_skeleton *skeleton;
203 struct bpf_object *obj;
204 struct {
205 struct bpf_map *rodata;
206 struct bpf_map *data;
207 struct bpf_map *bss;
208 struct bpf_map *my_map;
209 } maps;
210 struct {
211 struct bpf_program *handle_sys_enter;
212 struct bpf_program *handle_sys_exit;
213 } progs;
214 struct {
215 struct bpf_link *handle_sys_enter;
216 struct bpf_link *handle_sys_exit;
217 } links;
218 struct example__bss {
219 struct {
220 int x;
221 } data;
222 } *bss;
223 struct example__data {
224 _Bool global_flag;
225 long int handle_sys_enter_my_static_var;
226 } *data;
227 struct example__rodata {
228 int param1;
229 } *rodata;
230 };
231
232 static void example__destroy(struct example *obj);
233 static inline struct example *example__open_opts(
234 const struct bpf_object_open_opts *opts);
235 static inline struct example *example__open();
236 static inline int example__load(struct example *obj);
237 static inline struct example *example__open_and_load();
238 static inline int example__attach(struct example *obj);
239 static inline void example__detach(struct example *obj);
240
241 #endif /* __EXAMPLE_SKEL_H__ */
242
243**$ cat example_user.c**
244::
245
246 #include "example.skel.h"
247
248 int main()
249 {
250 struct example *skel;
251 int err = 0;
252
253 skel = example__open();
254 if (!skel)
255 goto cleanup;
256
257 skel->rodata->param1 = 128;
258
259 err = example__load(skel);
260 if (err)
261 goto cleanup;
262
263 err = example__attach(skel);
264 if (err)
265 goto cleanup;
266
267 /* all libbpf APIs are usable */
268 printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
269 printf("sys_enter prog FD: %d\n",
270 bpf_program__fd(skel->progs.handle_sys_enter));
271
272 /* detach and re-attach sys_exit program */
273 bpf_link__destroy(skel->links.handle_sys_exit);
274 skel->links.handle_sys_exit =
275 bpf_program__attach(skel->progs.handle_sys_exit);
276
277 printf("my_static_var: %ld\n",
278 skel->bss->handle_sys_enter_my_static_var);
279
280 cleanup:
281 example__destroy(skel);
282 return err;
283 }
284
285**# ./example_user**
286::
287
288 my_map name: my_map
289 sys_enter prog FD: 8
290 my_static_var: 7
291
292This is a stripped-out version of skeleton generated for above example code.
293
294SEE ALSO
295========
296 **bpf**\ (2),
297 **bpf-helpers**\ (7),
298 **bpftool**\ (8),
299 **bpftool-btf**\ (8),
300 **bpftool-cgroup**\ (8),
301 **bpftool-feature**\ (8),
302 **bpftool-iter**\ (8),
303 **bpftool-link**\ (8),
304 **bpftool-map**\ (8),
305 **bpftool-net**\ (8),
306 **bpftool-perf**\ (8),
307 **bpftool-prog**\ (8),
308 **bpftool-struct_ops**\ (8)