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