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