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