1cb21ac58SAndrii Nakryiko================ 2cb21ac58SAndrii Nakryikobpftool-gen 3cb21ac58SAndrii Nakryiko================ 4cb21ac58SAndrii Nakryiko------------------------------------------------------------------------------- 5cb21ac58SAndrii Nakryikotool for BPF code-generation 6cb21ac58SAndrii Nakryiko------------------------------------------------------------------------------- 7cb21ac58SAndrii Nakryiko 8cb21ac58SAndrii Nakryiko:Manual section: 8 9cb21ac58SAndrii Nakryiko 10cb21ac58SAndrii NakryikoSYNOPSIS 11cb21ac58SAndrii Nakryiko======== 12cb21ac58SAndrii Nakryiko 13cb21ac58SAndrii Nakryiko **bpftool** [*OPTIONS*] **gen** *COMMAND* 14cb21ac58SAndrii Nakryiko 15cb21ac58SAndrii Nakryiko *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } 16cb21ac58SAndrii Nakryiko 17*d80b2fcbSAndrii Nakryiko *COMMAND* := { **object** | **skeleton** | **help** } 18cb21ac58SAndrii Nakryiko 19cb21ac58SAndrii NakryikoGEN COMMANDS 20cb21ac58SAndrii Nakryiko============= 21cb21ac58SAndrii Nakryiko 22*d80b2fcbSAndrii Nakryiko| **bpftool** **gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...] 23c4122665SAndrii Nakryiko| **bpftool** **gen skeleton** *FILE* [**name** *OBJECT_NAME*] 24cb21ac58SAndrii Nakryiko| **bpftool** **gen help** 25cb21ac58SAndrii Nakryiko 26cb21ac58SAndrii NakryikoDESCRIPTION 27cb21ac58SAndrii Nakryiko=========== 28*d80b2fcbSAndrii Nakryiko **bpftool gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...] 29*d80b2fcbSAndrii Nakryiko Statically link (combine) together one or more *INPUT_FILE*'s 30*d80b2fcbSAndrii Nakryiko into a single resulting *OUTPUT_FILE*. All the files involved 31*d80b2fcbSAndrii Nakryiko are BPF ELF object files. 32*d80b2fcbSAndrii Nakryiko 33*d80b2fcbSAndrii Nakryiko The rules of BPF static linking are mostly the same as for 34*d80b2fcbSAndrii Nakryiko user-space object files, but in addition to combining data 35*d80b2fcbSAndrii Nakryiko and instruction sections, .BTF and .BTF.ext (if present in 36*d80b2fcbSAndrii Nakryiko any of the input files) data are combined together. .BTF 37*d80b2fcbSAndrii Nakryiko data is deduplicated, so all the common types across 38*d80b2fcbSAndrii Nakryiko *INPUT_FILE*'s will only be represented once in the resulting 39*d80b2fcbSAndrii Nakryiko BTF information. 40*d80b2fcbSAndrii Nakryiko 41*d80b2fcbSAndrii Nakryiko BPF static linking allows to partition BPF source code into 42*d80b2fcbSAndrii Nakryiko individually compiled files that are then linked into 43*d80b2fcbSAndrii Nakryiko a single resulting BPF object file, which can be used to 44*d80b2fcbSAndrii Nakryiko generated BPF skeleton (with **gen skeleton** command) or 45*d80b2fcbSAndrii Nakryiko passed directly into **libbpf** (using **bpf_object__open()** 46*d80b2fcbSAndrii Nakryiko family of APIs). 47*d80b2fcbSAndrii Nakryiko 48cb21ac58SAndrii Nakryiko **bpftool gen skeleton** *FILE* 49cb21ac58SAndrii Nakryiko Generate BPF skeleton C header file for a given *FILE*. 50cb21ac58SAndrii Nakryiko 51cb21ac58SAndrii Nakryiko BPF skeleton is an alternative interface to existing libbpf 52cb21ac58SAndrii Nakryiko APIs for working with BPF objects. Skeleton code is intended 53cb21ac58SAndrii Nakryiko to significantly shorten and simplify code to load and work 54cb21ac58SAndrii Nakryiko with BPF programs from userspace side. Generated code is 55cb21ac58SAndrii Nakryiko tailored to specific input BPF object *FILE*, reflecting its 56cb21ac58SAndrii Nakryiko structure by listing out available maps, program, variables, 57cb21ac58SAndrii Nakryiko etc. Skeleton eliminates the need to lookup mentioned 58cb21ac58SAndrii Nakryiko components by name. Instead, if skeleton instantiation 59cb21ac58SAndrii Nakryiko succeeds, they are populated in skeleton structure as valid 60c8caa0bbSQuentin Monnet libbpf types (e.g., **struct bpf_map** pointer) and can be 61cb21ac58SAndrii Nakryiko passed to existing generic libbpf APIs. 62cb21ac58SAndrii Nakryiko 63cb21ac58SAndrii Nakryiko In addition to simple and reliable access to maps and 64c8caa0bbSQuentin Monnet programs, skeleton provides a storage for BPF links (**struct 65c8caa0bbSQuentin Monnet bpf_link**) for each BPF program within BPF object. When 66cb21ac58SAndrii Nakryiko requested, supported BPF programs will be automatically 67cb21ac58SAndrii Nakryiko attached and resulting BPF links stored for further use by 68cb21ac58SAndrii Nakryiko user in pre-allocated fields in skeleton struct. For BPF 69cb21ac58SAndrii Nakryiko programs that can't be automatically attached by libbpf, 70cb21ac58SAndrii Nakryiko user can attach them manually, but store resulting BPF link 71cb21ac58SAndrii Nakryiko in per-program link field. All such set up links will be 72cb21ac58SAndrii Nakryiko automatically destroyed on BPF skeleton destruction. This 73cb21ac58SAndrii Nakryiko eliminates the need for users to manage links manually and 74cb21ac58SAndrii Nakryiko rely on libbpf support to detach programs and free up 75cb21ac58SAndrii Nakryiko resources. 76cb21ac58SAndrii Nakryiko 77cb21ac58SAndrii Nakryiko Another facility provided by BPF skeleton is an interface to 78cb21ac58SAndrii Nakryiko global variables of all supported kinds: mutable, read-only, 79cb21ac58SAndrii Nakryiko as well as extern ones. This interface allows to pre-setup 80cb21ac58SAndrii Nakryiko initial values of variables before BPF object is loaded and 81cb21ac58SAndrii Nakryiko verified by kernel. For non-read-only variables, the same 82cb21ac58SAndrii Nakryiko interface can be used to fetch values of global variables on 83cb21ac58SAndrii Nakryiko userspace side, even if they are modified by BPF code. 84cb21ac58SAndrii Nakryiko 85cb21ac58SAndrii Nakryiko During skeleton generation, contents of source BPF object 86cb21ac58SAndrii Nakryiko *FILE* is embedded within generated code and is thus not 87cb21ac58SAndrii Nakryiko necessary to keep around. This ensures skeleton and BPF 88cb21ac58SAndrii Nakryiko object file are matching 1-to-1 and always stay in sync. 89cb21ac58SAndrii Nakryiko Generated code is dual-licensed under LGPL-2.1 and 90cb21ac58SAndrii Nakryiko BSD-2-Clause licenses. 91cb21ac58SAndrii Nakryiko 92cb21ac58SAndrii Nakryiko It is a design goal and guarantee that skeleton interfaces 93cb21ac58SAndrii Nakryiko are interoperable with generic libbpf APIs. User should 94cb21ac58SAndrii Nakryiko always be able to use skeleton API to create and load BPF 95cb21ac58SAndrii Nakryiko object, and later use libbpf APIs to keep working with 96cb21ac58SAndrii Nakryiko specific maps, programs, etc. 97cb21ac58SAndrii Nakryiko 98cb21ac58SAndrii Nakryiko As part of skeleton, few custom functions are generated. 99c4122665SAndrii Nakryiko Each of them is prefixed with object name. Object name can 100c4122665SAndrii Nakryiko either be derived from object file name, i.e., if BPF object 101c4122665SAndrii Nakryiko file name is **example.o**, BPF object name will be 102c4122665SAndrii Nakryiko **example**. Object name can be also specified explicitly 103c4122665SAndrii Nakryiko through **name** *OBJECT_NAME* parameter. The following 104c4122665SAndrii Nakryiko custom functions are provided (assuming **example** as 105c4122665SAndrii Nakryiko the object name): 106cb21ac58SAndrii Nakryiko 107cb21ac58SAndrii Nakryiko - **example__open** and **example__open_opts**. 108cb21ac58SAndrii Nakryiko These functions are used to instantiate skeleton. It 109c8caa0bbSQuentin Monnet corresponds to libbpf's **bpf_object__open**\ () API. 110cb21ac58SAndrii Nakryiko **_opts** variants accepts extra **bpf_object_open_opts** 111cb21ac58SAndrii Nakryiko options. 112cb21ac58SAndrii Nakryiko 113cb21ac58SAndrii Nakryiko - **example__load**. 114cb21ac58SAndrii Nakryiko This function creates maps, loads and verifies BPF 115cb21ac58SAndrii Nakryiko programs, initializes global data maps. It corresponds to 116c8caa0bbSQuentin Monnet libppf's **bpf_object__load**\ () API. 117cb21ac58SAndrii Nakryiko 118cb21ac58SAndrii Nakryiko - **example__open_and_load** combines **example__open** and 119cb21ac58SAndrii Nakryiko **example__load** invocations in one commonly used 120cb21ac58SAndrii Nakryiko operation. 121cb21ac58SAndrii Nakryiko 122cb21ac58SAndrii Nakryiko - **example__attach** and **example__detach** 123cb21ac58SAndrii Nakryiko This pair of functions allow to attach and detach, 124cb21ac58SAndrii Nakryiko correspondingly, already loaded BPF object. Only BPF 125cb21ac58SAndrii Nakryiko programs of types supported by libbpf for auto-attachment 126cb21ac58SAndrii Nakryiko will be auto-attached and their corresponding BPF links 127cb21ac58SAndrii Nakryiko instantiated. For other BPF programs, user can manually 128cb21ac58SAndrii Nakryiko create a BPF link and assign it to corresponding fields in 129cb21ac58SAndrii Nakryiko skeleton struct. **example__detach** will detach both 130cb21ac58SAndrii Nakryiko links created automatically, as well as those populated by 131cb21ac58SAndrii Nakryiko user manually. 132cb21ac58SAndrii Nakryiko 133cb21ac58SAndrii Nakryiko - **example__destroy** 134cb21ac58SAndrii Nakryiko Detach and unload BPF programs, free up all the resources 135cb21ac58SAndrii Nakryiko used by skeleton and BPF object. 136cb21ac58SAndrii Nakryiko 137cb21ac58SAndrii Nakryiko If BPF object has global variables, corresponding structs 138cb21ac58SAndrii Nakryiko with memory layout corresponding to global data data section 139dacce641SAndrii Nakryiko layout will be created. Currently supported ones are: *.data*, 140dacce641SAndrii Nakryiko *.bss*, *.rodata*, and *.kconfig* structs/data sections. 141dacce641SAndrii Nakryiko These data sections/structs can be used to set up initial 142dacce641SAndrii Nakryiko values of variables, if set before **example__load**. 143dacce641SAndrii Nakryiko Afterwards, if target kernel supports memory-mapped BPF 144dacce641SAndrii Nakryiko arrays, same structs can be used to fetch and update 145dacce641SAndrii Nakryiko (non-read-only) data from userspace, with same simplicity 146dacce641SAndrii Nakryiko as for BPF side. 147cb21ac58SAndrii Nakryiko 148cb21ac58SAndrii Nakryiko **bpftool gen help** 149cb21ac58SAndrii Nakryiko Print short help message. 150cb21ac58SAndrii Nakryiko 151cb21ac58SAndrii NakryikoOPTIONS 152cb21ac58SAndrii Nakryiko======= 153f28ef96dSQuentin Monnet .. include:: common_options.rst 154cb21ac58SAndrii Nakryiko 155cb21ac58SAndrii NakryikoEXAMPLES 156cb21ac58SAndrii Nakryiko======== 157*d80b2fcbSAndrii Nakryiko**$ cat example1.bpf.c** 15816f3ddfbSQuentin Monnet 159cb21ac58SAndrii Nakryiko:: 160cb21ac58SAndrii Nakryiko 161cb21ac58SAndrii Nakryiko #include <stdbool.h> 162cb21ac58SAndrii Nakryiko #include <linux/ptrace.h> 163cb21ac58SAndrii Nakryiko #include <linux/bpf.h> 164*d80b2fcbSAndrii Nakryiko #include <bpf/bpf_helpers.h> 165cb21ac58SAndrii Nakryiko 166cb21ac58SAndrii Nakryiko const volatile int param1 = 42; 167cb21ac58SAndrii Nakryiko bool global_flag = true; 168cb21ac58SAndrii Nakryiko struct { int x; } data = {}; 169cb21ac58SAndrii Nakryiko 170cb21ac58SAndrii Nakryiko SEC("raw_tp/sys_enter") 171cb21ac58SAndrii Nakryiko int handle_sys_enter(struct pt_regs *ctx) 172cb21ac58SAndrii Nakryiko { 173cb21ac58SAndrii Nakryiko static long my_static_var; 174cb21ac58SAndrii Nakryiko if (global_flag) 175cb21ac58SAndrii Nakryiko my_static_var++; 176cb21ac58SAndrii Nakryiko else 177cb21ac58SAndrii Nakryiko data.x += param1; 178cb21ac58SAndrii Nakryiko return 0; 179cb21ac58SAndrii Nakryiko } 180cb21ac58SAndrii Nakryiko 181*d80b2fcbSAndrii Nakryiko**$ cat example2.bpf.c** 182*d80b2fcbSAndrii Nakryiko 183*d80b2fcbSAndrii Nakryiko:: 184*d80b2fcbSAndrii Nakryiko 185*d80b2fcbSAndrii Nakryiko #include <linux/ptrace.h> 186*d80b2fcbSAndrii Nakryiko #include <linux/bpf.h> 187*d80b2fcbSAndrii Nakryiko #include <bpf/bpf_helpers.h> 188*d80b2fcbSAndrii Nakryiko 189*d80b2fcbSAndrii Nakryiko struct { 190*d80b2fcbSAndrii Nakryiko __uint(type, BPF_MAP_TYPE_HASH); 191*d80b2fcbSAndrii Nakryiko __uint(max_entries, 128); 192*d80b2fcbSAndrii Nakryiko __type(key, int); 193*d80b2fcbSAndrii Nakryiko __type(value, long); 194*d80b2fcbSAndrii Nakryiko } my_map SEC(".maps"); 195*d80b2fcbSAndrii Nakryiko 196cb21ac58SAndrii Nakryiko SEC("raw_tp/sys_exit") 197cb21ac58SAndrii Nakryiko int handle_sys_exit(struct pt_regs *ctx) 198cb21ac58SAndrii Nakryiko { 199cb21ac58SAndrii Nakryiko int zero = 0; 200cb21ac58SAndrii Nakryiko bpf_map_lookup_elem(&my_map, &zero); 201cb21ac58SAndrii Nakryiko return 0; 202cb21ac58SAndrii Nakryiko } 203cb21ac58SAndrii Nakryiko 204cb21ac58SAndrii NakryikoThis is example BPF application with two BPF programs and a mix of BPF maps 205*d80b2fcbSAndrii Nakryikoand global variables. Source code is split across two source code files. 206cb21ac58SAndrii Nakryiko 207*d80b2fcbSAndrii Nakryiko**$ clang -target bpf -g example1.bpf.c -o example1.bpf.o** 208*d80b2fcbSAndrii Nakryiko**$ clang -target bpf -g example2.bpf.c -o example2.bpf.o** 209*d80b2fcbSAndrii Nakryiko**$ bpftool gen object example.bpf.o example1.bpf.o example2.bpf.o** 210*d80b2fcbSAndrii Nakryiko 211*d80b2fcbSAndrii NakryikoThis set of commands compiles *example1.bpf.c* and *example2.bpf.c* 212*d80b2fcbSAndrii Nakryikoindividually and then statically links respective object files into the final 213*d80b2fcbSAndrii NakryikoBPF ELF object file *example.bpf.o*. 214*d80b2fcbSAndrii Nakryiko 215*d80b2fcbSAndrii Nakryiko**$ bpftool gen skeleton example.bpf.o name example | tee example.skel.h** 21616f3ddfbSQuentin Monnet 217cb21ac58SAndrii Nakryiko:: 218cb21ac58SAndrii Nakryiko 219cb21ac58SAndrii Nakryiko /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ 220cb21ac58SAndrii Nakryiko 221cb21ac58SAndrii Nakryiko /* THIS FILE IS AUTOGENERATED! */ 222cb21ac58SAndrii Nakryiko #ifndef __EXAMPLE_SKEL_H__ 223cb21ac58SAndrii Nakryiko #define __EXAMPLE_SKEL_H__ 224cb21ac58SAndrii Nakryiko 225cb21ac58SAndrii Nakryiko #include <stdlib.h> 226229c3b47SToke Høiland-Jørgensen #include <bpf/libbpf.h> 227cb21ac58SAndrii Nakryiko 228cb21ac58SAndrii Nakryiko struct example { 229cb21ac58SAndrii Nakryiko struct bpf_object_skeleton *skeleton; 230cb21ac58SAndrii Nakryiko struct bpf_object *obj; 231cb21ac58SAndrii Nakryiko struct { 232cb21ac58SAndrii Nakryiko struct bpf_map *rodata; 233cb21ac58SAndrii Nakryiko struct bpf_map *data; 234cb21ac58SAndrii Nakryiko struct bpf_map *bss; 235cb21ac58SAndrii Nakryiko struct bpf_map *my_map; 236cb21ac58SAndrii Nakryiko } maps; 237cb21ac58SAndrii Nakryiko struct { 238cb21ac58SAndrii Nakryiko struct bpf_program *handle_sys_enter; 239cb21ac58SAndrii Nakryiko struct bpf_program *handle_sys_exit; 240cb21ac58SAndrii Nakryiko } progs; 241cb21ac58SAndrii Nakryiko struct { 242cb21ac58SAndrii Nakryiko struct bpf_link *handle_sys_enter; 243cb21ac58SAndrii Nakryiko struct bpf_link *handle_sys_exit; 244cb21ac58SAndrii Nakryiko } links; 245cb21ac58SAndrii Nakryiko struct example__bss { 246cb21ac58SAndrii Nakryiko struct { 247cb21ac58SAndrii Nakryiko int x; 248cb21ac58SAndrii Nakryiko } data; 249cb21ac58SAndrii Nakryiko } *bss; 250cb21ac58SAndrii Nakryiko struct example__data { 251cb21ac58SAndrii Nakryiko _Bool global_flag; 252cb21ac58SAndrii Nakryiko long int handle_sys_enter_my_static_var; 253cb21ac58SAndrii Nakryiko } *data; 254cb21ac58SAndrii Nakryiko struct example__rodata { 255cb21ac58SAndrii Nakryiko int param1; 256cb21ac58SAndrii Nakryiko } *rodata; 257cb21ac58SAndrii Nakryiko }; 258cb21ac58SAndrii Nakryiko 259cb21ac58SAndrii Nakryiko static void example__destroy(struct example *obj); 260cb21ac58SAndrii Nakryiko static inline struct example *example__open_opts( 261cb21ac58SAndrii Nakryiko const struct bpf_object_open_opts *opts); 262cb21ac58SAndrii Nakryiko static inline struct example *example__open(); 263cb21ac58SAndrii Nakryiko static inline int example__load(struct example *obj); 264cb21ac58SAndrii Nakryiko static inline struct example *example__open_and_load(); 265cb21ac58SAndrii Nakryiko static inline int example__attach(struct example *obj); 266cb21ac58SAndrii Nakryiko static inline void example__detach(struct example *obj); 267cb21ac58SAndrii Nakryiko 268cb21ac58SAndrii Nakryiko #endif /* __EXAMPLE_SKEL_H__ */ 269cb21ac58SAndrii Nakryiko 270*d80b2fcbSAndrii Nakryiko**$ cat example.c** 27116f3ddfbSQuentin Monnet 272cb21ac58SAndrii Nakryiko:: 273cb21ac58SAndrii Nakryiko 274cb21ac58SAndrii Nakryiko #include "example.skel.h" 275cb21ac58SAndrii Nakryiko 276cb21ac58SAndrii Nakryiko int main() 277cb21ac58SAndrii Nakryiko { 278cb21ac58SAndrii Nakryiko struct example *skel; 279cb21ac58SAndrii Nakryiko int err = 0; 280cb21ac58SAndrii Nakryiko 281cb21ac58SAndrii Nakryiko skel = example__open(); 282cb21ac58SAndrii Nakryiko if (!skel) 283cb21ac58SAndrii Nakryiko goto cleanup; 284cb21ac58SAndrii Nakryiko 285cb21ac58SAndrii Nakryiko skel->rodata->param1 = 128; 286cb21ac58SAndrii Nakryiko 287cb21ac58SAndrii Nakryiko err = example__load(skel); 288cb21ac58SAndrii Nakryiko if (err) 289cb21ac58SAndrii Nakryiko goto cleanup; 290cb21ac58SAndrii Nakryiko 291cb21ac58SAndrii Nakryiko err = example__attach(skel); 292cb21ac58SAndrii Nakryiko if (err) 293cb21ac58SAndrii Nakryiko goto cleanup; 294cb21ac58SAndrii Nakryiko 295cb21ac58SAndrii Nakryiko /* all libbpf APIs are usable */ 296cb21ac58SAndrii Nakryiko printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map)); 297cb21ac58SAndrii Nakryiko printf("sys_enter prog FD: %d\n", 298cb21ac58SAndrii Nakryiko bpf_program__fd(skel->progs.handle_sys_enter)); 299cb21ac58SAndrii Nakryiko 300cb21ac58SAndrii Nakryiko /* detach and re-attach sys_exit program */ 301cb21ac58SAndrii Nakryiko bpf_link__destroy(skel->links.handle_sys_exit); 302cb21ac58SAndrii Nakryiko skel->links.handle_sys_exit = 303cb21ac58SAndrii Nakryiko bpf_program__attach(skel->progs.handle_sys_exit); 304cb21ac58SAndrii Nakryiko 305cb21ac58SAndrii Nakryiko printf("my_static_var: %ld\n", 306cb21ac58SAndrii Nakryiko skel->bss->handle_sys_enter_my_static_var); 307cb21ac58SAndrii Nakryiko 308cb21ac58SAndrii Nakryiko cleanup: 309cb21ac58SAndrii Nakryiko example__destroy(skel); 310cb21ac58SAndrii Nakryiko return err; 311cb21ac58SAndrii Nakryiko } 312cb21ac58SAndrii Nakryiko 313*d80b2fcbSAndrii Nakryiko**# ./example** 31416f3ddfbSQuentin Monnet 315cb21ac58SAndrii Nakryiko:: 316cb21ac58SAndrii Nakryiko 317cb21ac58SAndrii Nakryiko my_map name: my_map 318cb21ac58SAndrii Nakryiko sys_enter prog FD: 8 319cb21ac58SAndrii Nakryiko my_static_var: 7 320cb21ac58SAndrii Nakryiko 321cb21ac58SAndrii NakryikoThis is a stripped-out version of skeleton generated for above example code. 322