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 .extern structs/data sections. These
117		  data sections/structs can be used to set up initial values of
118		  variables, if set before **example__load**. Afterwards, if
119		  target kernel supports memory-mapped BPF arrays, same
120		  structs can be used to fetch and update (non-read-only)
121		  data from userspace, with same simplicity as for BPF side.
122
123	**bpftool gen help**
124		  Print short help message.
125
126OPTIONS
127=======
128	-h, --help
129		  Print short generic help message (similar to **bpftool help**).
130
131	-V, --version
132		  Print version number (similar to **bpftool version**).
133
134	-j, --json
135		  Generate JSON output. For commands that cannot produce JSON,
136		  this option has no effect.
137
138	-p, --pretty
139		  Generate human-readable JSON output. Implies **-j**.
140
141	-d, --debug
142		  Print all logs available from libbpf, including debug-level
143		  information.
144
145EXAMPLES
146========
147**$ cat example.c**
148::
149
150  #include <stdbool.h>
151  #include <linux/ptrace.h>
152  #include <linux/bpf.h>
153  #include "bpf_helpers.h"
154
155  const volatile int param1 = 42;
156  bool global_flag = true;
157  struct { int x; } data = {};
158
159  struct {
160  	__uint(type, BPF_MAP_TYPE_HASH);
161  	__uint(max_entries, 128);
162  	__type(key, int);
163  	__type(value, long);
164  } my_map SEC(".maps");
165
166  SEC("raw_tp/sys_enter")
167  int handle_sys_enter(struct pt_regs *ctx)
168  {
169  	static long my_static_var;
170  	if (global_flag)
171  		my_static_var++;
172  	else
173  		data.x += param1;
174  	return 0;
175  }
176
177  SEC("raw_tp/sys_exit")
178  int handle_sys_exit(struct pt_regs *ctx)
179  {
180  	int zero = 0;
181  	bpf_map_lookup_elem(&my_map, &zero);
182  	return 0;
183  }
184
185This is example BPF application with two BPF programs and a mix of BPF maps
186and global variables.
187
188**$ bpftool gen skeleton example.o**
189::
190
191  /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
192
193  /* THIS FILE IS AUTOGENERATED! */
194  #ifndef __EXAMPLE_SKEL_H__
195  #define __EXAMPLE_SKEL_H__
196
197  #include <stdlib.h>
198  #include <libbpf.h>
199
200  struct example {
201  	struct bpf_object_skeleton *skeleton;
202  	struct bpf_object *obj;
203  	struct {
204  		struct bpf_map *rodata;
205  		struct bpf_map *data;
206  		struct bpf_map *bss;
207  		struct bpf_map *my_map;
208  	} maps;
209  	struct {
210  		struct bpf_program *handle_sys_enter;
211  		struct bpf_program *handle_sys_exit;
212  	} progs;
213  	struct {
214  		struct bpf_link *handle_sys_enter;
215  		struct bpf_link *handle_sys_exit;
216  	} links;
217  	struct example__bss {
218  		struct {
219  			int x;
220  		} data;
221  	} *bss;
222  	struct example__data {
223  		_Bool global_flag;
224  		long int handle_sys_enter_my_static_var;
225  	} *data;
226  	struct example__rodata {
227  		int param1;
228  	} *rodata;
229  };
230
231  static void example__destroy(struct example *obj);
232  static inline struct example *example__open_opts(
233                const struct bpf_object_open_opts *opts);
234  static inline struct example *example__open();
235  static inline int example__load(struct example *obj);
236  static inline struct example *example__open_and_load();
237  static inline int example__attach(struct example *obj);
238  static inline void example__detach(struct example *obj);
239
240  #endif /* __EXAMPLE_SKEL_H__ */
241
242**$ cat example_user.c**
243::
244
245  #include "example.skel.h"
246
247  int main()
248  {
249  	struct example *skel;
250  	int err = 0;
251
252  	skel = example__open();
253  	if (!skel)
254  		goto cleanup;
255
256  	skel->rodata->param1 = 128;
257
258  	err = example__load(skel);
259  	if (err)
260  		goto cleanup;
261
262  	err = example__attach(skel);
263  	if (err)
264  		goto cleanup;
265
266  	/* all libbpf APIs are usable */
267  	printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
268  	printf("sys_enter prog FD: %d\n",
269  	       bpf_program__fd(skel->progs.handle_sys_enter));
270
271  	/* detach and re-attach sys_exit program */
272  	bpf_link__destroy(skel->links.handle_sys_exit);
273  	skel->links.handle_sys_exit =
274  		bpf_program__attach(skel->progs.handle_sys_exit);
275
276  	printf("my_static_var: %ld\n",
277  	       skel->bss->handle_sys_enter_my_static_var);
278
279  cleanup:
280  	example__destroy(skel);
281  	return err;
282  }
283
284**# ./example_user**
285::
286
287  my_map name: my_map
288  sys_enter prog FD: 8
289  my_static_var: 7
290
291This is a stripped-out version of skeleton generated for above example code.
292
293SEE ALSO
294========
295	**bpf**\ (2),
296	**bpf-helpers**\ (7),
297	**bpftool**\ (8),
298	**bpftool-map**\ (8),
299	**bpftool-prog**\ (8),
300	**bpftool-cgroup**\ (8),
301	**bpftool-feature**\ (8),
302	**bpftool-net**\ (8),
303	**bpftool-perf**\ (8),
304	**bpftool-btf**\ (8)
305