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* [**name** *OBJECT_NAME*] 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. Object name can 79 either be derived from object file name, i.e., if BPF object 80 file name is **example.o**, BPF object name will be 81 **example**. Object name can be also specified explicitly 82 through **name** *OBJECT_NAME* parameter. The following 83 custom functions are provided (assuming **example** as 84 the object name): 85 86 - **example__open** and **example__open_opts**. 87 These functions are used to instantiate skeleton. It 88 corresponds to libbpf's **bpf_object__open**\ () API. 89 **_opts** variants accepts extra **bpf_object_open_opts** 90 options. 91 92 - **example__load**. 93 This function creates maps, loads and verifies BPF 94 programs, initializes global data maps. It corresponds to 95 libppf's **bpf_object__load**\ () API. 96 97 - **example__open_and_load** combines **example__open** and 98 **example__load** invocations in one commonly used 99 operation. 100 101 - **example__attach** and **example__detach** 102 This pair of functions allow to attach and detach, 103 correspondingly, already loaded BPF object. Only BPF 104 programs of types supported by libbpf for auto-attachment 105 will be auto-attached and their corresponding BPF links 106 instantiated. For other BPF programs, user can manually 107 create a BPF link and assign it to corresponding fields in 108 skeleton struct. **example__detach** will detach both 109 links created automatically, as well as those populated by 110 user manually. 111 112 - **example__destroy** 113 Detach and unload BPF programs, free up all the resources 114 used by skeleton and BPF object. 115 116 If BPF object has global variables, corresponding structs 117 with memory layout corresponding to global data data section 118 layout will be created. Currently supported ones are: *.data*, 119 *.bss*, *.rodata*, and *.kconfig* structs/data sections. 120 These data sections/structs can be used to set up initial 121 values of variables, if set before **example__load**. 122 Afterwards, if target kernel supports memory-mapped BPF 123 arrays, same structs can be used to fetch and update 124 (non-read-only) data from userspace, with same simplicity 125 as for BPF side. 126 127 **bpftool gen help** 128 Print short help message. 129 130OPTIONS 131======= 132 .. include:: common_options.rst 133 134EXAMPLES 135======== 136**$ cat example.c** 137 138:: 139 140 #include <stdbool.h> 141 #include <linux/ptrace.h> 142 #include <linux/bpf.h> 143 #include "bpf_helpers.h" 144 145 const volatile int param1 = 42; 146 bool global_flag = true; 147 struct { int x; } data = {}; 148 149 struct { 150 __uint(type, BPF_MAP_TYPE_HASH); 151 __uint(max_entries, 128); 152 __type(key, int); 153 __type(value, long); 154 } my_map SEC(".maps"); 155 156 SEC("raw_tp/sys_enter") 157 int handle_sys_enter(struct pt_regs *ctx) 158 { 159 static long my_static_var; 160 if (global_flag) 161 my_static_var++; 162 else 163 data.x += param1; 164 return 0; 165 } 166 167 SEC("raw_tp/sys_exit") 168 int handle_sys_exit(struct pt_regs *ctx) 169 { 170 int zero = 0; 171 bpf_map_lookup_elem(&my_map, &zero); 172 return 0; 173 } 174 175This is example BPF application with two BPF programs and a mix of BPF maps 176and global variables. 177 178**$ bpftool gen skeleton example.o** 179 180:: 181 182 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ 183 184 /* THIS FILE IS AUTOGENERATED! */ 185 #ifndef __EXAMPLE_SKEL_H__ 186 #define __EXAMPLE_SKEL_H__ 187 188 #include <stdlib.h> 189 #include <bpf/libbpf.h> 190 191 struct example { 192 struct bpf_object_skeleton *skeleton; 193 struct bpf_object *obj; 194 struct { 195 struct bpf_map *rodata; 196 struct bpf_map *data; 197 struct bpf_map *bss; 198 struct bpf_map *my_map; 199 } maps; 200 struct { 201 struct bpf_program *handle_sys_enter; 202 struct bpf_program *handle_sys_exit; 203 } progs; 204 struct { 205 struct bpf_link *handle_sys_enter; 206 struct bpf_link *handle_sys_exit; 207 } links; 208 struct example__bss { 209 struct { 210 int x; 211 } data; 212 } *bss; 213 struct example__data { 214 _Bool global_flag; 215 long int handle_sys_enter_my_static_var; 216 } *data; 217 struct example__rodata { 218 int param1; 219 } *rodata; 220 }; 221 222 static void example__destroy(struct example *obj); 223 static inline struct example *example__open_opts( 224 const struct bpf_object_open_opts *opts); 225 static inline struct example *example__open(); 226 static inline int example__load(struct example *obj); 227 static inline struct example *example__open_and_load(); 228 static inline int example__attach(struct example *obj); 229 static inline void example__detach(struct example *obj); 230 231 #endif /* __EXAMPLE_SKEL_H__ */ 232 233**$ cat example_user.c** 234 235:: 236 237 #include "example.skel.h" 238 239 int main() 240 { 241 struct example *skel; 242 int err = 0; 243 244 skel = example__open(); 245 if (!skel) 246 goto cleanup; 247 248 skel->rodata->param1 = 128; 249 250 err = example__load(skel); 251 if (err) 252 goto cleanup; 253 254 err = example__attach(skel); 255 if (err) 256 goto cleanup; 257 258 /* all libbpf APIs are usable */ 259 printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map)); 260 printf("sys_enter prog FD: %d\n", 261 bpf_program__fd(skel->progs.handle_sys_enter)); 262 263 /* detach and re-attach sys_exit program */ 264 bpf_link__destroy(skel->links.handle_sys_exit); 265 skel->links.handle_sys_exit = 266 bpf_program__attach(skel->progs.handle_sys_exit); 267 268 printf("my_static_var: %ld\n", 269 skel->bss->handle_sys_enter_my_static_var); 270 271 cleanup: 272 example__destroy(skel); 273 return err; 274 } 275 276**# ./example_user** 277 278:: 279 280 my_map name: my_map 281 sys_enter prog FD: 8 282 my_static_var: 7 283 284This is a stripped-out version of skeleton generated for above example code. 285