0001 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002
0003 ================
0004 bpftool-gen
0005 ================
0006 -------------------------------------------------------------------------------
0007 tool for BPF code-generation
0008 -------------------------------------------------------------------------------
0009
0010 :Manual section: 8
0011
0012 .. include:: substitutions.rst
0013
0014 SYNOPSIS
0015 ========
0016
0017 **bpftool** [*OPTIONS*] **gen** *COMMAND*
0018
0019 *OPTIONS* := { |COMMON_OPTIONS| | { **-L** | **--use-loader** } }
0020
0021 *COMMAND* := { **object** | **skeleton** | **help** }
0022
0023 GEN COMMANDS
0024 =============
0025
0026 | **bpftool** **gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...]
0027 | **bpftool** **gen skeleton** *FILE* [**name** *OBJECT_NAME*]
0028 | **bpftool** **gen subskeleton** *FILE* [**name** *OBJECT_NAME*]
0029 | **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...]
0030 | **bpftool** **gen help**
0031
0032 DESCRIPTION
0033 ===========
0034 **bpftool gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...]
0035 Statically link (combine) together one or more *INPUT_FILE*'s
0036 into a single resulting *OUTPUT_FILE*. All the files involved
0037 are BPF ELF object files.
0038
0039 The rules of BPF static linking are mostly the same as for
0040 user-space object files, but in addition to combining data
0041 and instruction sections, .BTF and .BTF.ext (if present in
0042 any of the input files) data are combined together. .BTF
0043 data is deduplicated, so all the common types across
0044 *INPUT_FILE*'s will only be represented once in the resulting
0045 BTF information.
0046
0047 BPF static linking allows to partition BPF source code into
0048 individually compiled files that are then linked into
0049 a single resulting BPF object file, which can be used to
0050 generated BPF skeleton (with **gen skeleton** command) or
0051 passed directly into **libbpf** (using **bpf_object__open()**
0052 family of APIs).
0053
0054 **bpftool gen skeleton** *FILE*
0055 Generate BPF skeleton C header file for a given *FILE*.
0056
0057 BPF skeleton is an alternative interface to existing libbpf
0058 APIs for working with BPF objects. Skeleton code is intended
0059 to significantly shorten and simplify code to load and work
0060 with BPF programs from userspace side. Generated code is
0061 tailored to specific input BPF object *FILE*, reflecting its
0062 structure by listing out available maps, program, variables,
0063 etc. Skeleton eliminates the need to lookup mentioned
0064 components by name. Instead, if skeleton instantiation
0065 succeeds, they are populated in skeleton structure as valid
0066 libbpf types (e.g., **struct bpf_map** pointer) and can be
0067 passed to existing generic libbpf APIs.
0068
0069 In addition to simple and reliable access to maps and
0070 programs, skeleton provides a storage for BPF links (**struct
0071 bpf_link**) for each BPF program within BPF object. When
0072 requested, supported BPF programs will be automatically
0073 attached and resulting BPF links stored for further use by
0074 user in pre-allocated fields in skeleton struct. For BPF
0075 programs that can't be automatically attached by libbpf,
0076 user can attach them manually, but store resulting BPF link
0077 in per-program link field. All such set up links will be
0078 automatically destroyed on BPF skeleton destruction. This
0079 eliminates the need for users to manage links manually and
0080 rely on libbpf support to detach programs and free up
0081 resources.
0082
0083 Another facility provided by BPF skeleton is an interface to
0084 global variables of all supported kinds: mutable, read-only,
0085 as well as extern ones. This interface allows to pre-setup
0086 initial values of variables before BPF object is loaded and
0087 verified by kernel. For non-read-only variables, the same
0088 interface can be used to fetch values of global variables on
0089 userspace side, even if they are modified by BPF code.
0090
0091 During skeleton generation, contents of source BPF object
0092 *FILE* is embedded within generated code and is thus not
0093 necessary to keep around. This ensures skeleton and BPF
0094 object file are matching 1-to-1 and always stay in sync.
0095 Generated code is dual-licensed under LGPL-2.1 and
0096 BSD-2-Clause licenses.
0097
0098 It is a design goal and guarantee that skeleton interfaces
0099 are interoperable with generic libbpf APIs. User should
0100 always be able to use skeleton API to create and load BPF
0101 object, and later use libbpf APIs to keep working with
0102 specific maps, programs, etc.
0103
0104 As part of skeleton, few custom functions are generated.
0105 Each of them is prefixed with object name. Object name can
0106 either be derived from object file name, i.e., if BPF object
0107 file name is **example.o**, BPF object name will be
0108 **example**. Object name can be also specified explicitly
0109 through **name** *OBJECT_NAME* parameter. The following
0110 custom functions are provided (assuming **example** as
0111 the object name):
0112
0113 - **example__open** and **example__open_opts**.
0114 These functions are used to instantiate skeleton. It
0115 corresponds to libbpf's **bpf_object__open**\ () API.
0116 **_opts** variants accepts extra **bpf_object_open_opts**
0117 options.
0118
0119 - **example__load**.
0120 This function creates maps, loads and verifies BPF
0121 programs, initializes global data maps. It corresponds to
0122 libppf's **bpf_object__load**\ () API.
0123
0124 - **example__open_and_load** combines **example__open** and
0125 **example__load** invocations in one commonly used
0126 operation.
0127
0128 - **example__attach** and **example__detach**
0129 This pair of functions allow to attach and detach,
0130 correspondingly, already loaded BPF object. Only BPF
0131 programs of types supported by libbpf for auto-attachment
0132 will be auto-attached and their corresponding BPF links
0133 instantiated. For other BPF programs, user can manually
0134 create a BPF link and assign it to corresponding fields in
0135 skeleton struct. **example__detach** will detach both
0136 links created automatically, as well as those populated by
0137 user manually.
0138
0139 - **example__destroy**
0140 Detach and unload BPF programs, free up all the resources
0141 used by skeleton and BPF object.
0142
0143 If BPF object has global variables, corresponding structs
0144 with memory layout corresponding to global data data section
0145 layout will be created. Currently supported ones are: *.data*,
0146 *.bss*, *.rodata*, and *.kconfig* structs/data sections.
0147 These data sections/structs can be used to set up initial
0148 values of variables, if set before **example__load**.
0149 Afterwards, if target kernel supports memory-mapped BPF
0150 arrays, same structs can be used to fetch and update
0151 (non-read-only) data from userspace, with same simplicity
0152 as for BPF side.
0153
0154 **bpftool gen subskeleton** *FILE*
0155 Generate BPF subskeleton C header file for a given *FILE*.
0156
0157 Subskeletons are similar to skeletons, except they do not own
0158 the corresponding maps, programs, or global variables. They
0159 require that the object file used to generate them is already
0160 loaded into a *bpf_object* by some other means.
0161
0162 This functionality is useful when a library is included into a
0163 larger BPF program. A subskeleton for the library would have
0164 access to all objects and globals defined in it, without
0165 having to know about the larger program.
0166
0167 Consequently, there are only two functions defined
0168 for subskeletons:
0169
0170 - **example__open(bpf_object\*)**
0171 Instantiates a subskeleton from an already opened (but not
0172 necessarily loaded) **bpf_object**.
0173
0174 - **example__destroy()**
0175 Frees the storage for the subskeleton but *does not* unload
0176 any BPF programs or maps.
0177
0178 **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...]
0179 Generate a minimum BTF file as *OUTPUT*, derived from a given
0180 *INPUT* BTF file, containing all needed BTF types so one, or
0181 more, given eBPF objects CO-RE relocations may be satisfied.
0182
0183 When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF,
0184 libbpf, when loading an eBPF object, has to rely on external
0185 BTF files to be able to calculate CO-RE relocations.
0186
0187 Usually, an external BTF file is built from existing kernel
0188 DWARF data using pahole. It contains all the types used by
0189 its respective kernel image and, because of that, is big.
0190
0191 The min_core_btf feature builds smaller BTF files, customized
0192 to one or multiple eBPF objects, so they can be distributed
0193 together with an eBPF CO-RE based application, turning the
0194 application portable to different kernel versions.
0195
0196 Check examples bellow for more information how to use it.
0197
0198 **bpftool gen help**
0199 Print short help message.
0200
0201 OPTIONS
0202 =======
0203 .. include:: common_options.rst
0204
0205 -L, --use-loader
0206 For skeletons, generate a "light" skeleton (also known as "loader"
0207 skeleton). A light skeleton contains a loader eBPF program. It does
0208 not use the majority of the libbpf infrastructure, and does not need
0209 libelf.
0210
0211 EXAMPLES
0212 ========
0213 **$ cat example1.bpf.c**
0214
0215 ::
0216
0217 #include <stdbool.h>
0218 #include <linux/ptrace.h>
0219 #include <linux/bpf.h>
0220 #include <bpf/bpf_helpers.h>
0221
0222 const volatile int param1 = 42;
0223 bool global_flag = true;
0224 struct { int x; } data = {};
0225
0226 SEC("raw_tp/sys_enter")
0227 int handle_sys_enter(struct pt_regs *ctx)
0228 {
0229 static long my_static_var;
0230 if (global_flag)
0231 my_static_var++;
0232 else
0233 data.x += param1;
0234 return 0;
0235 }
0236
0237 **$ cat example2.bpf.c**
0238
0239 ::
0240
0241 #include <linux/ptrace.h>
0242 #include <linux/bpf.h>
0243 #include <bpf/bpf_helpers.h>
0244
0245 struct {
0246 __uint(type, BPF_MAP_TYPE_HASH);
0247 __uint(max_entries, 128);
0248 __type(key, int);
0249 __type(value, long);
0250 } my_map SEC(".maps");
0251
0252 SEC("raw_tp/sys_exit")
0253 int handle_sys_exit(struct pt_regs *ctx)
0254 {
0255 int zero = 0;
0256 bpf_map_lookup_elem(&my_map, &zero);
0257 return 0;
0258 }
0259
0260 This is example BPF application with two BPF programs and a mix of BPF maps
0261 and global variables. Source code is split across two source code files.
0262
0263 **$ clang -target bpf -g example1.bpf.c -o example1.bpf.o**
0264
0265 **$ clang -target bpf -g example2.bpf.c -o example2.bpf.o**
0266
0267 **$ bpftool gen object example.bpf.o example1.bpf.o example2.bpf.o**
0268
0269 This set of commands compiles *example1.bpf.c* and *example2.bpf.c*
0270 individually and then statically links respective object files into the final
0271 BPF ELF object file *example.bpf.o*.
0272
0273 **$ bpftool gen skeleton example.bpf.o name example | tee example.skel.h**
0274
0275 ::
0276
0277 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
0278
0279 /* THIS FILE IS AUTOGENERATED! */
0280 #ifndef __EXAMPLE_SKEL_H__
0281 #define __EXAMPLE_SKEL_H__
0282
0283 #include <stdlib.h>
0284 #include <bpf/libbpf.h>
0285
0286 struct example {
0287 struct bpf_object_skeleton *skeleton;
0288 struct bpf_object *obj;
0289 struct {
0290 struct bpf_map *rodata;
0291 struct bpf_map *data;
0292 struct bpf_map *bss;
0293 struct bpf_map *my_map;
0294 } maps;
0295 struct {
0296 struct bpf_program *handle_sys_enter;
0297 struct bpf_program *handle_sys_exit;
0298 } progs;
0299 struct {
0300 struct bpf_link *handle_sys_enter;
0301 struct bpf_link *handle_sys_exit;
0302 } links;
0303 struct example__bss {
0304 struct {
0305 int x;
0306 } data;
0307 } *bss;
0308 struct example__data {
0309 _Bool global_flag;
0310 long int handle_sys_enter_my_static_var;
0311 } *data;
0312 struct example__rodata {
0313 int param1;
0314 } *rodata;
0315 };
0316
0317 static void example__destroy(struct example *obj);
0318 static inline struct example *example__open_opts(
0319 const struct bpf_object_open_opts *opts);
0320 static inline struct example *example__open();
0321 static inline int example__load(struct example *obj);
0322 static inline struct example *example__open_and_load();
0323 static inline int example__attach(struct example *obj);
0324 static inline void example__detach(struct example *obj);
0325
0326 #endif /* __EXAMPLE_SKEL_H__ */
0327
0328 **$ cat example.c**
0329
0330 ::
0331
0332 #include "example.skel.h"
0333
0334 int main()
0335 {
0336 struct example *skel;
0337 int err = 0;
0338
0339 skel = example__open();
0340 if (!skel)
0341 goto cleanup;
0342
0343 skel->rodata->param1 = 128;
0344
0345 err = example__load(skel);
0346 if (err)
0347 goto cleanup;
0348
0349 err = example__attach(skel);
0350 if (err)
0351 goto cleanup;
0352
0353 /* all libbpf APIs are usable */
0354 printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
0355 printf("sys_enter prog FD: %d\n",
0356 bpf_program__fd(skel->progs.handle_sys_enter));
0357
0358 /* detach and re-attach sys_exit program */
0359 bpf_link__destroy(skel->links.handle_sys_exit);
0360 skel->links.handle_sys_exit =
0361 bpf_program__attach(skel->progs.handle_sys_exit);
0362
0363 printf("my_static_var: %ld\n",
0364 skel->bss->handle_sys_enter_my_static_var);
0365
0366 cleanup:
0367 example__destroy(skel);
0368 return err;
0369 }
0370
0371 **# ./example**
0372
0373 ::
0374
0375 my_map name: my_map
0376 sys_enter prog FD: 8
0377 my_static_var: 7
0378
0379 This is a stripped-out version of skeleton generated for above example code.
0380
0381 min_core_btf
0382 ------------
0383
0384 **$ bpftool btf dump file 5.4.0-example.btf format raw**
0385
0386 ::
0387
0388 [1] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
0389 [2] CONST '(anon)' type_id=1
0390 [3] VOLATILE '(anon)' type_id=1
0391 [4] ARRAY '(anon)' type_id=1 index_type_id=21 nr_elems=2
0392 [5] PTR '(anon)' type_id=8
0393 [6] CONST '(anon)' type_id=5
0394 [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=(none)
0395 [8] CONST '(anon)' type_id=7
0396 [9] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
0397 <long output>
0398
0399 **$ bpftool btf dump file one.bpf.o format raw**
0400
0401 ::
0402
0403 [1] PTR '(anon)' type_id=2
0404 [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=4
0405 'ent' type_id=3 bits_offset=0
0406 'id' type_id=7 bits_offset=64
0407 'args' type_id=9 bits_offset=128
0408 '__data' type_id=12 bits_offset=512
0409 [3] STRUCT 'trace_entry' size=8 vlen=4
0410 'type' type_id=4 bits_offset=0
0411 'flags' type_id=5 bits_offset=16
0412 'preempt_count' type_id=5 bits_offset=24
0413 <long output>
0414
0415 **$ bpftool gen min_core_btf 5.4.0-example.btf 5.4.0-smaller.btf one.bpf.o**
0416
0417 **$ bpftool btf dump file 5.4.0-smaller.btf format raw**
0418
0419 ::
0420
0421 [1] TYPEDEF 'pid_t' type_id=6
0422 [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=1
0423 'args' type_id=4 bits_offset=128
0424 [3] STRUCT 'task_struct' size=9216 vlen=2
0425 'pid' type_id=1 bits_offset=17920
0426 'real_parent' type_id=7 bits_offset=18048
0427 [4] ARRAY '(anon)' type_id=5 index_type_id=8 nr_elems=6
0428 [5] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
0429 [6] TYPEDEF '__kernel_pid_t' type_id=8
0430 [7] PTR '(anon)' type_id=3
0431 [8] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
0432 <end>
0433
0434 Now, the "5.4.0-smaller.btf" file may be used by libbpf as an external BTF file
0435 when loading the "one.bpf.o" object into the "5.4.0-example" kernel. Note that
0436 the generated BTF file won't allow other eBPF objects to be loaded, just the
0437 ones given to min_core_btf.
0438
0439 ::
0440
0441 LIBBPF_OPTS(bpf_object_open_opts, opts, .btf_custom_path = "5.4.0-smaller.btf");
0442 struct bpf_object *obj;
0443
0444 obj = bpf_object__open_file("one.bpf.o", &opts);
0445
0446 ...
