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