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