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