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