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