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