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