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
152  #include <stdbool.h>
153  #include <linux/ptrace.h>
154  #include <linux/bpf.h>
155  #include "bpf_helpers.h"
156
157  const volatile int param1 = 42;
158  bool global_flag = true;
159  struct { int x; } data = {};
160
161  struct {
162  	__uint(type, BPF_MAP_TYPE_HASH);
163  	__uint(max_entries, 128);
164  	__type(key, int);
165  	__type(value, long);
166  } my_map SEC(".maps");
167
168  SEC("raw_tp/sys_enter")
169  int handle_sys_enter(struct pt_regs *ctx)
170  {
171  	static long my_static_var;
172  	if (global_flag)
173  		my_static_var++;
174  	else
175  		data.x += param1;
176  	return 0;
177  }
178
179  SEC("raw_tp/sys_exit")
180  int handle_sys_exit(struct pt_regs *ctx)
181  {
182  	int zero = 0;
183  	bpf_map_lookup_elem(&my_map, &zero);
184  	return 0;
185  }
186
187This is example BPF application with two BPF programs and a mix of BPF maps
188and global variables.
189
190**$ bpftool gen skeleton example.o**
191
192::
193
194  /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
195
196  /* THIS FILE IS AUTOGENERATED! */
197  #ifndef __EXAMPLE_SKEL_H__
198  #define __EXAMPLE_SKEL_H__
199
200  #include <stdlib.h>
201  #include <bpf/libbpf.h>
202
203  struct example {
204  	struct bpf_object_skeleton *skeleton;
205  	struct bpf_object *obj;
206  	struct {
207  		struct bpf_map *rodata;
208  		struct bpf_map *data;
209  		struct bpf_map *bss;
210  		struct bpf_map *my_map;
211  	} maps;
212  	struct {
213  		struct bpf_program *handle_sys_enter;
214  		struct bpf_program *handle_sys_exit;
215  	} progs;
216  	struct {
217  		struct bpf_link *handle_sys_enter;
218  		struct bpf_link *handle_sys_exit;
219  	} links;
220  	struct example__bss {
221  		struct {
222  			int x;
223  		} data;
224  	} *bss;
225  	struct example__data {
226  		_Bool global_flag;
227  		long int handle_sys_enter_my_static_var;
228  	} *data;
229  	struct example__rodata {
230  		int param1;
231  	} *rodata;
232  };
233
234  static void example__destroy(struct example *obj);
235  static inline struct example *example__open_opts(
236                const struct bpf_object_open_opts *opts);
237  static inline struct example *example__open();
238  static inline int example__load(struct example *obj);
239  static inline struct example *example__open_and_load();
240  static inline int example__attach(struct example *obj);
241  static inline void example__detach(struct example *obj);
242
243  #endif /* __EXAMPLE_SKEL_H__ */
244
245**$ cat example_user.c**
246
247::
248
249  #include "example.skel.h"
250
251  int main()
252  {
253  	struct example *skel;
254  	int err = 0;
255
256  	skel = example__open();
257  	if (!skel)
258  		goto cleanup;
259
260  	skel->rodata->param1 = 128;
261
262  	err = example__load(skel);
263  	if (err)
264  		goto cleanup;
265
266  	err = example__attach(skel);
267  	if (err)
268  		goto cleanup;
269
270  	/* all libbpf APIs are usable */
271  	printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
272  	printf("sys_enter prog FD: %d\n",
273  	       bpf_program__fd(skel->progs.handle_sys_enter));
274
275  	/* detach and re-attach sys_exit program */
276  	bpf_link__destroy(skel->links.handle_sys_exit);
277  	skel->links.handle_sys_exit =
278  		bpf_program__attach(skel->progs.handle_sys_exit);
279
280  	printf("my_static_var: %ld\n",
281  	       skel->bss->handle_sys_enter_my_static_var);
282
283  cleanup:
284  	example__destroy(skel);
285  	return err;
286  }
287
288**# ./example_user**
289
290::
291
292  my_map name: my_map
293  sys_enter prog FD: 8
294  my_static_var: 7
295
296This is a stripped-out version of skeleton generated for above example code.
297
298SEE ALSO
299========
300	**bpf**\ (2),
301	**bpf-helpers**\ (7),
302	**bpftool**\ (8),
303	**bpftool-btf**\ (8),
304	**bpftool-cgroup**\ (8),
305	**bpftool-feature**\ (8),
306	**bpftool-iter**\ (8),
307	**bpftool-link**\ (8),
308	**bpftool-map**\ (8),
309	**bpftool-net**\ (8),
310	**bpftool-perf**\ (8),
311	**bpftool-prog**\ (8),
312	**bpftool-struct_ops**\ (8)
313