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** } | [ { **-S** | **--sign** } {**-k** <private_key.pem>} **-i** <certificate.x509> ] } 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 libbpf'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 below for more information on 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 189-S, --sign 190 For skeletons, generate a signed skeleton. This option must be used with 191 **-k** and **-i**. Using this flag implicitly enables **--use-loader**. 192 193-k <private_key.pem> 194 Path to the private key file in PEM format, required for signing. 195 196-i <certificate.x509> 197 Path to the X.509 certificate file in PEM or DER format, required for 198 signing. 199 200EXAMPLES 201======== 202**$ cat example1.bpf.c** 203 204:: 205 206 #include <stdbool.h> 207 #include <linux/ptrace.h> 208 #include <linux/bpf.h> 209 #include <bpf/bpf_helpers.h> 210 211 const volatile int param1 = 42; 212 bool global_flag = true; 213 struct { int x; } data = {}; 214 215 SEC("raw_tp/sys_enter") 216 int handle_sys_enter(struct pt_regs *ctx) 217 { 218 static long my_static_var; 219 if (global_flag) 220 my_static_var++; 221 else 222 data.x += param1; 223 return 0; 224 } 225 226**$ cat example2.bpf.c** 227 228:: 229 230 #include <linux/ptrace.h> 231 #include <linux/bpf.h> 232 #include <bpf/bpf_helpers.h> 233 234 struct { 235 __uint(type, BPF_MAP_TYPE_HASH); 236 __uint(max_entries, 128); 237 __type(key, int); 238 __type(value, long); 239 } my_map SEC(".maps"); 240 241 SEC("raw_tp/sys_exit") 242 int handle_sys_exit(struct pt_regs *ctx) 243 { 244 int zero = 0; 245 bpf_map_lookup_elem(&my_map, &zero); 246 return 0; 247 } 248 249**$ cat example3.bpf.c** 250 251:: 252 253 #include <linux/ptrace.h> 254 #include <linux/bpf.h> 255 #include <bpf/bpf_helpers.h> 256 /* This header file is provided by the bpf_testmod module. */ 257 #include "bpf_testmod.h" 258 259 int test_2_result = 0; 260 261 /* bpf_Testmod.ko calls this function, passing a "4" 262 * and testmod_map->data. 263 */ 264 SEC("struct_ops/test_2") 265 void BPF_PROG(test_2, int a, int b) 266 { 267 test_2_result = a + b; 268 } 269 270 SEC(".struct_ops") 271 struct bpf_testmod_ops testmod_map = { 272 .test_2 = (void *)test_2, 273 .data = 0x1, 274 }; 275 276This is example BPF application with three BPF programs and a mix of BPF 277maps and global variables. Source code is split across three source code 278files. 279 280**$ clang --target=bpf -g example1.bpf.c -o example1.bpf.o** 281 282**$ clang --target=bpf -g example2.bpf.c -o example2.bpf.o** 283 284**$ clang --target=bpf -g example3.bpf.c -o example3.bpf.o** 285 286**$ bpftool gen object example.bpf.o example1.bpf.o example2.bpf.o example3.bpf.o** 287 288This set of commands compiles *example1.bpf.c*, *example2.bpf.c* and 289*example3.bpf.c* individually and then statically links respective object 290files into the final BPF ELF object file *example.bpf.o*. 291 292**$ bpftool gen skeleton example.bpf.o name example | tee example.skel.h** 293 294:: 295 296 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ 297 298 /* THIS FILE IS AUTOGENERATED! */ 299 #ifndef __EXAMPLE_SKEL_H__ 300 #define __EXAMPLE_SKEL_H__ 301 302 #include <stdlib.h> 303 #include <bpf/libbpf.h> 304 305 struct example { 306 struct bpf_object_skeleton *skeleton; 307 struct bpf_object *obj; 308 struct { 309 struct bpf_map *rodata; 310 struct bpf_map *data; 311 struct bpf_map *bss; 312 struct bpf_map *my_map; 313 struct bpf_map *testmod_map; 314 } maps; 315 struct { 316 struct example__testmod_map__bpf_testmod_ops { 317 const struct bpf_program *test_1; 318 const struct bpf_program *test_2; 319 int data; 320 } *testmod_map; 321 } struct_ops; 322 struct { 323 struct bpf_program *handle_sys_enter; 324 struct bpf_program *handle_sys_exit; 325 } progs; 326 struct { 327 struct bpf_link *handle_sys_enter; 328 struct bpf_link *handle_sys_exit; 329 } links; 330 struct example__bss { 331 struct { 332 int x; 333 } data; 334 int test_2_result; 335 } *bss; 336 struct example__data { 337 _Bool global_flag; 338 long int handle_sys_enter_my_static_var; 339 } *data; 340 struct example__rodata { 341 int param1; 342 } *rodata; 343 }; 344 345 static void example__destroy(struct example *obj); 346 static inline struct example *example__open_opts( 347 const struct bpf_object_open_opts *opts); 348 static inline struct example *example__open(); 349 static inline int example__load(struct example *obj); 350 static inline struct example *example__open_and_load(); 351 static inline int example__attach(struct example *obj); 352 static inline void example__detach(struct example *obj); 353 354 #endif /* __EXAMPLE_SKEL_H__ */ 355 356**$ cat example.c** 357 358:: 359 360 #include "example.skel.h" 361 362 int main() 363 { 364 struct example *skel; 365 int err = 0; 366 367 skel = example__open(); 368 if (!skel) 369 goto cleanup; 370 371 skel->rodata->param1 = 128; 372 373 /* Change the value through the pointer of shadow type */ 374 skel->struct_ops.testmod_map->data = 13; 375 376 err = example__load(skel); 377 if (err) 378 goto cleanup; 379 380 /* The result of the function test_2() */ 381 printf("test_2_result: %d\n", skel->bss->test_2_result); 382 383 err = example__attach(skel); 384 if (err) 385 goto cleanup; 386 387 /* all libbpf APIs are usable */ 388 printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map)); 389 printf("sys_enter prog FD: %d\n", 390 bpf_program__fd(skel->progs.handle_sys_enter)); 391 392 /* detach and re-attach sys_exit program */ 393 bpf_link__destroy(skel->links.handle_sys_exit); 394 skel->links.handle_sys_exit = 395 bpf_program__attach(skel->progs.handle_sys_exit); 396 397 printf("my_static_var: %ld\n", 398 skel->bss->handle_sys_enter_my_static_var); 399 400 cleanup: 401 example__destroy(skel); 402 return err; 403 } 404 405**# ./example** 406 407:: 408 409 test_2_result: 17 410 my_map name: my_map 411 sys_enter prog FD: 8 412 my_static_var: 7 413 414This is a stripped-out version of skeleton generated for above example code. 415 416min_core_btf 417------------ 418 419**$ bpftool btf dump file 5.4.0-example.btf format raw** 420 421:: 422 423 [1] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none) 424 [2] CONST '(anon)' type_id=1 425 [3] VOLATILE '(anon)' type_id=1 426 [4] ARRAY '(anon)' type_id=1 index_type_id=21 nr_elems=2 427 [5] PTR '(anon)' type_id=8 428 [6] CONST '(anon)' type_id=5 429 [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=(none) 430 [8] CONST '(anon)' type_id=7 431 [9] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none) 432 <long output> 433 434**$ bpftool btf dump file one.bpf.o format raw** 435 436:: 437 438 [1] PTR '(anon)' type_id=2 439 [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=4 440 'ent' type_id=3 bits_offset=0 441 'id' type_id=7 bits_offset=64 442 'args' type_id=9 bits_offset=128 443 '__data' type_id=12 bits_offset=512 444 [3] STRUCT 'trace_entry' size=8 vlen=4 445 'type' type_id=4 bits_offset=0 446 'flags' type_id=5 bits_offset=16 447 'preempt_count' type_id=5 bits_offset=24 448 <long output> 449 450**$ bpftool gen min_core_btf 5.4.0-example.btf 5.4.0-smaller.btf one.bpf.o** 451 452**$ bpftool btf dump file 5.4.0-smaller.btf format raw** 453 454:: 455 456 [1] TYPEDEF 'pid_t' type_id=6 457 [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=1 458 'args' type_id=4 bits_offset=128 459 [3] STRUCT 'task_struct' size=9216 vlen=2 460 'pid' type_id=1 bits_offset=17920 461 'real_parent' type_id=7 bits_offset=18048 462 [4] ARRAY '(anon)' type_id=5 index_type_id=8 nr_elems=6 463 [5] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none) 464 [6] TYPEDEF '__kernel_pid_t' type_id=8 465 [7] PTR '(anon)' type_id=3 466 [8] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED 467 <end> 468 469Now, the "5.4.0-smaller.btf" file may be used by libbpf as an external BTF file 470when loading the "one.bpf.o" object into the "5.4.0-example" kernel. Note that 471the generated BTF file won't allow other eBPF objects to be loaded, just the 472ones given to min_core_btf. 473 474:: 475 476 LIBBPF_OPTS(bpf_object_open_opts, opts, .btf_custom_path = "5.4.0-smaller.btf"); 477 struct bpf_object *obj; 478 479 obj = bpf_object__open_file("one.bpf.o", &opts); 480 481 ... 482