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 .extern structs/data sections. These 117 data sections/structs can be used to set up initial values of 118 variables, if set before **example__load**. Afterwards, if 119 target kernel supports memory-mapped BPF arrays, same 120 structs can be used to fetch and update (non-read-only) 121 data from userspace, with same simplicity as for BPF side. 122 123 **bpftool gen help** 124 Print short help message. 125 126OPTIONS 127======= 128 -h, --help 129 Print short generic help message (similar to **bpftool help**). 130 131 -V, --version 132 Print version number (similar to **bpftool version**). 133 134 -j, --json 135 Generate JSON output. For commands that cannot produce JSON, 136 this option has no effect. 137 138 -p, --pretty 139 Generate human-readable JSON output. Implies **-j**. 140 141 -d, --debug 142 Print all logs available from libbpf, including debug-level 143 information. 144 145EXAMPLES 146======== 147**$ cat example.c** 148:: 149 150 #include <stdbool.h> 151 #include <linux/ptrace.h> 152 #include <linux/bpf.h> 153 #include "bpf_helpers.h" 154 155 const volatile int param1 = 42; 156 bool global_flag = true; 157 struct { int x; } data = {}; 158 159 struct { 160 __uint(type, BPF_MAP_TYPE_HASH); 161 __uint(max_entries, 128); 162 __type(key, int); 163 __type(value, long); 164 } my_map SEC(".maps"); 165 166 SEC("raw_tp/sys_enter") 167 int handle_sys_enter(struct pt_regs *ctx) 168 { 169 static long my_static_var; 170 if (global_flag) 171 my_static_var++; 172 else 173 data.x += param1; 174 return 0; 175 } 176 177 SEC("raw_tp/sys_exit") 178 int handle_sys_exit(struct pt_regs *ctx) 179 { 180 int zero = 0; 181 bpf_map_lookup_elem(&my_map, &zero); 182 return 0; 183 } 184 185This is example BPF application with two BPF programs and a mix of BPF maps 186and global variables. 187 188**$ bpftool gen skeleton example.o** 189:: 190 191 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ 192 193 /* THIS FILE IS AUTOGENERATED! */ 194 #ifndef __EXAMPLE_SKEL_H__ 195 #define __EXAMPLE_SKEL_H__ 196 197 #include <stdlib.h> 198 #include <libbpf.h> 199 200 struct example { 201 struct bpf_object_skeleton *skeleton; 202 struct bpf_object *obj; 203 struct { 204 struct bpf_map *rodata; 205 struct bpf_map *data; 206 struct bpf_map *bss; 207 struct bpf_map *my_map; 208 } maps; 209 struct { 210 struct bpf_program *handle_sys_enter; 211 struct bpf_program *handle_sys_exit; 212 } progs; 213 struct { 214 struct bpf_link *handle_sys_enter; 215 struct bpf_link *handle_sys_exit; 216 } links; 217 struct example__bss { 218 struct { 219 int x; 220 } data; 221 } *bss; 222 struct example__data { 223 _Bool global_flag; 224 long int handle_sys_enter_my_static_var; 225 } *data; 226 struct example__rodata { 227 int param1; 228 } *rodata; 229 }; 230 231 static void example__destroy(struct example *obj); 232 static inline struct example *example__open_opts( 233 const struct bpf_object_open_opts *opts); 234 static inline struct example *example__open(); 235 static inline int example__load(struct example *obj); 236 static inline struct example *example__open_and_load(); 237 static inline int example__attach(struct example *obj); 238 static inline void example__detach(struct example *obj); 239 240 #endif /* __EXAMPLE_SKEL_H__ */ 241 242**$ cat example_user.c** 243:: 244 245 #include "example.skel.h" 246 247 int main() 248 { 249 struct example *skel; 250 int err = 0; 251 252 skel = example__open(); 253 if (!skel) 254 goto cleanup; 255 256 skel->rodata->param1 = 128; 257 258 err = example__load(skel); 259 if (err) 260 goto cleanup; 261 262 err = example__attach(skel); 263 if (err) 264 goto cleanup; 265 266 /* all libbpf APIs are usable */ 267 printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map)); 268 printf("sys_enter prog FD: %d\n", 269 bpf_program__fd(skel->progs.handle_sys_enter)); 270 271 /* detach and re-attach sys_exit program */ 272 bpf_link__destroy(skel->links.handle_sys_exit); 273 skel->links.handle_sys_exit = 274 bpf_program__attach(skel->progs.handle_sys_exit); 275 276 printf("my_static_var: %ld\n", 277 skel->bss->handle_sys_enter_my_static_var); 278 279 cleanup: 280 example__destroy(skel); 281 return err; 282 } 283 284**# ./example_user** 285:: 286 287 my_map name: my_map 288 sys_enter prog FD: 8 289 my_static_var: 7 290 291This is a stripped-out version of skeleton generated for above example code. 292 293SEE ALSO 294======== 295 **bpf**\ (2), 296 **bpf-helpers**\ (7), 297 **bpftool**\ (8), 298 **bpftool-map**\ (8), 299 **bpftool-prog**\ (8), 300 **bpftool-cgroup**\ (8), 301 **bpftool-feature**\ (8), 302 **bpftool-net**\ (8), 303 **bpftool-perf**\ (8), 304 **bpftool-btf**\ (8) 305