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)
309