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