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