471 lines · plain
1.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)2 3================4bpftool-gen5================6-------------------------------------------------------------------------------7tool for BPF code-generation8-------------------------------------------------------------------------------9 10:Manual section: 811 12.. include:: substitutions.rst13 14SYNOPSIS15========16 17**bpftool** [*OPTIONS*] **gen** *COMMAND*18 19*OPTIONS* := { |COMMON_OPTIONS| | { **-L** | **--use-loader** } }20 21*COMMAND* := { **object** | **skeleton** | **help** }22 23GEN COMMANDS24=============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 32DESCRIPTION33===========34bpftool gen object *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...]35 Statically link (combine) together one or more *INPUT_FILE*'s into a single36 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-space39 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 combined41 together. .BTF data is deduplicated, so all the common types across42 *INPUT_FILE*'s will only be represented once in the resulting BTF43 information.44 45 BPF static linking allows to partition BPF source code into individually46 compiled files that are then linked into a single resulting BPF object47 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 for55 working with BPF objects. Skeleton code is intended to significantly56 shorten and simplify code to load and work with BPF programs from userspace57 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 skeleton61 structure as valid libbpf types (e.g., **struct bpf_map** pointer) and can62 be passed to existing generic libbpf APIs.63 64 In addition to simple and reliable access to maps and programs, skeleton65 provides a storage for BPF links (**struct bpf_link**) for each BPF program66 within BPF object. When requested, supported BPF programs will be67 automatically attached and resulting BPF links stored for further use by68 user in pre-allocated fields in skeleton struct. For BPF programs that69 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 up71 links will be automatically destroyed on BPF skeleton destruction. This72 eliminates the need for users to manage links manually and rely on libbpf73 support to detach programs and free up resources.74 75 Another facility provided by BPF skeleton is an interface to global76 variables of all supported kinds: mutable, read-only, as well as extern77 ones. This interface allows to pre-setup initial values of variables before78 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 on80 userspace side, even if they are modified by BPF code.81 82 During skeleton generation, contents of source BPF object *FILE* is83 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 always85 stay in sync. Generated code is dual-licensed under LGPL-2.1 and86 BSD-2-Clause licenses.87 88 It is a design goal and guarantee that skeleton interfaces are89 interoperable with generic libbpf APIs. User should always be able to use90 skeleton API to create and load BPF object, and later use libbpf APIs to91 keep working with specific maps, programs, etc.92 93 As part of skeleton, few custom functions are generated. Each of them is94 prefixed with object name. Object name can either be derived from object95 file name, i.e., if BPF object file name is **example.o**, BPF object name96 will be **example**. Object name can be also specified explicitly through97 **name** *OBJECT_NAME* parameter. The following custom functions are98 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 to102 libbpf's **bpf_object__open**\ () API. **_opts** variants accepts extra103 **bpf_object_open_opts** options.104 105 - **example__load**.106 This function creates maps, loads and verifies BPF programs, initializes107 global data maps. It corresponds to libbpf's **bpf_object__load**\ ()108 API.109 110 - **example__open_and_load** combines **example__open** and111 **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 libbpf116 for auto-attachment will be auto-attached and their corresponding BPF117 links instantiated. For other BPF programs, user can manually create a118 BPF link and assign it to corresponding fields in skeleton struct.119 **example__detach** will detach both links created automatically, as well120 as those populated by user manually.121 122 - **example__destroy**.123 Detach and unload BPF programs, free up all the resources used by124 skeleton and BPF object.125 126 If BPF object has global variables, corresponding structs with memory127 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 up130 initial values of variables, if set before **example__load**. Afterwards,131 if target kernel supports memory-mapped BPF arrays, same structs can be132 used to fetch and update (non-read-only) data from userspace, with same133 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 the139 corresponding maps, programs, or global variables. They require that the140 object file used to generate them is already loaded into a *bpf_object* by141 some other means.142 143 This functionality is useful when a library is included into a larger BPF144 program. A subskeleton for the library would have access to all objects and145 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 necessarily151 loaded) **bpf_object**.152 153 - **example__destroy()**.154 Frees the storage for the subskeleton but *does not* unload any BPF155 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* BTF159 file, containing all needed BTF types so one, or more, given eBPF objects160 CO-RE relocations may be satisfied.161 162 When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF, libbpf, when163 loading an eBPF object, has to rely on external BTF files to be able to164 calculate CO-RE relocations.165 166 Usually, an external BTF file is built from existing kernel DWARF data167 using pahole. It contains all the types used by its respective kernel image168 and, because of that, is big.169 170 The min_core_btf feature builds smaller BTF files, customized to one or171 multiple eBPF objects, so they can be distributed together with an eBPF172 CO-RE based application, turning the application portable to different173 kernel versions.174 175 Check examples below for more information on how to use it.176 177bpftool gen help178 Print short help message.179 180OPTIONS181=======182.. include:: common_options.rst183 184-L, --use-loader185 For skeletons, generate a "light" skeleton (also known as "loader"186 skeleton). A light skeleton contains a loader eBPF program. It does not use187 the majority of the libbpf infrastructure, and does not need libelf.188 189EXAMPLES190========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 else211 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 BPF266maps and global variables. Source code is split across three source code267files.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* and278*example3.bpf.c* individually and then statically links respective object279files 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: 17399 my_map name: my_map400 sys_enter prog FD: 8401 my_static_var: 7402 403This is a stripped-out version of skeleton generated for above example code.404 405min_core_btf406------------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=1414 [3] VOLATILE '(anon)' type_id=1415 [4] ARRAY '(anon)' type_id=1 index_type_id=21 nr_elems=2416 [5] PTR '(anon)' type_id=8417 [6] CONST '(anon)' type_id=5418 [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=(none)419 [8] CONST '(anon)' type_id=7420 [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=2428 [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=4429 'ent' type_id=3 bits_offset=0430 'id' type_id=7 bits_offset=64431 'args' type_id=9 bits_offset=128432 '__data' type_id=12 bits_offset=512433 [3] STRUCT 'trace_entry' size=8 vlen=4434 'type' type_id=4 bits_offset=0435 'flags' type_id=5 bits_offset=16436 'preempt_count' type_id=5 bits_offset=24437 <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=6446 [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=1447 'args' type_id=4 bits_offset=128448 [3] STRUCT 'task_struct' size=9216 vlen=2449 'pid' type_id=1 bits_offset=17920450 'real_parent' type_id=7 bits_offset=18048451 [4] ARRAY '(anon)' type_id=5 index_type_id=8 nr_elems=6452 [5] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)453 [6] TYPEDEF '__kernel_pid_t' type_id=8454 [7] PTR '(anon)' type_id=3455 [8] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED456 <end>457 458Now, the "5.4.0-smaller.btf" file may be used by libbpf as an external BTF file459when loading the "one.bpf.o" object into the "5.4.0-example" kernel. Note that460the generated BTF file won't allow other eBPF objects to be loaded, just the461ones 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