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