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