tools/bpf/bpftool/Documentation/bpftool-gen.rst

   1 ================
   2 bpftool-gen
   3 ================
   4 -------------------------------------------------------------------------------
   5 tool for BPF code-generation
   6 -------------------------------------------------------------------------------
   7
   8 :Manual section: 8
   9
  10 SYNOPSIS
  11 ========
  12
  13         **bpftool** [*OPTIONS*] **gen** *COMMAND*
  14
  15         *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
  16
  17         *COMMAND* := { **skeleton | **help** }
  18
  19 GEN COMMANDS
  20 =============
  21
  22 |       **bpftool** **gen skeleton** *FILE*
  23 |       **bpftool** **gen help**
  24
  25 DESCRIPTION
  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
 127 OPTIONS
 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
 146 EXAMPLES
 147 ========
 148 **$ cat example.c**
 149 ::
 150
 151   #include <stdbool.h>
 152   #include <linux/ptrace.h>
 153   #include <linux/bpf.h>
 154   #include "bpf_helpers.h"
 155
 156   const volatile int param1 = 42;
 157   bool global_flag = true;
 158   struct { int x; } data = {};
 159
 160   struct {
 161         __uint(type, BPF_MAP_TYPE_HASH);
 162         __uint(max_entries, 128);
 163         __type(key, int);
 164         __type(value, long);
 165   } my_map SEC(".maps");
 166
 167   SEC("raw_tp/sys_enter")
 168   int handle_sys_enter(struct pt_regs *ctx)
 169   {
 170         static long my_static_var;
 171         if (global_flag)
 172                 my_static_var++;
 173         else
 174                 data.x += param1;
 175         return 0;
 176   }
 177
 178   SEC("raw_tp/sys_exit")
 179   int handle_sys_exit(struct pt_regs *ctx)
 180   {
 181         int zero = 0;
 182         bpf_map_lookup_elem(&my_map, &zero);
 183         return 0;
 184   }
 185
 186 This is example BPF application with two BPF programs and a mix of BPF maps
 187 and global variables.
 188
 189 **$ bpftool gen skeleton example.o**
 190 ::
 191
 192   /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
 193
 194   /* THIS FILE IS AUTOGENERATED! */
 195   #ifndef __EXAMPLE_SKEL_H__
 196   #define __EXAMPLE_SKEL_H__
 197
 198   #include <stdlib.h>
 199   #include <bpf/libbpf.h>
 200
 201   struct example {
 202         struct bpf_object_skeleton *skeleton;
 203         struct bpf_object *obj;
 204         struct {
 205                 struct bpf_map *rodata;
 206                 struct bpf_map *data;
 207                 struct bpf_map *bss;
 208                 struct bpf_map *my_map;
 209         } maps;
 210         struct {
 211                 struct bpf_program *handle_sys_enter;
 212                 struct bpf_program *handle_sys_exit;
 213         } progs;
 214         struct {
 215                 struct bpf_link *handle_sys_enter;
 216                 struct bpf_link *handle_sys_exit;
 217         } links;
 218         struct example__bss {
 219                 struct {
 220                         int x;
 221                 } data;
 222         } *bss;
 223         struct example__data {
 224                 _Bool global_flag;
 225                 long int handle_sys_enter_my_static_var;
 226         } *data;
 227         struct example__rodata {
 228                 int param1;
 229         } *rodata;
 230   };
 231
 232   static void example__destroy(struct example *obj);
 233   static inline struct example *example__open_opts(
 234                 const struct bpf_object_open_opts *opts);
 235   static inline struct example *example__open();
 236   static inline int example__load(struct example *obj);
 237   static inline struct example *example__open_and_load();
 238   static inline int example__attach(struct example *obj);
 239   static inline void example__detach(struct example *obj);
 240
 241   #endif /* __EXAMPLE_SKEL_H__ */
 242
 243 **$ cat example_user.c**
 244 ::
 245
 246   #include "example.skel.h"
 247
 248   int main()
 249   {
 250         struct example *skel;
 251         int err = 0;
 252
 253         skel = example__open();
 254         if (!skel)
 255                 goto cleanup;
 256
 257         skel->rodata->param1 = 128;
 258
 259         err = example__load(skel);
 260         if (err)
 261                 goto cleanup;
 262
 263         err = example__attach(skel);
 264         if (err)
 265                 goto cleanup;
 266
 267         /* all libbpf APIs are usable */
 268         printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
 269         printf("sys_enter prog FD: %d\n",
 270                bpf_program__fd(skel->progs.handle_sys_enter));
 271
 272         /* detach and re-attach sys_exit program */
 273         bpf_link__destroy(skel->links.handle_sys_exit);
 274         skel->links.handle_sys_exit =
 275                 bpf_program__attach(skel->progs.handle_sys_exit);
 276
 277         printf("my_static_var: %ld\n",
 278                skel->bss->handle_sys_enter_my_static_var);
 279
 280   cleanup:
 281         example__destroy(skel);
 282         return err;
 283   }
 284
 285 **# ./example_user**
 286 ::
 287
 288   my_map name: my_map
 289   sys_enter prog FD: 8
 290   my_static_var: 7
 291
 292 This is a stripped-out version of skeleton generated for above example code.
 293
 294 SEE ALSO
 295 ========
 296         **bpf**\ (2),
 297         **bpf-helpers**\ (7),
 298         **bpftool**\ (8),
 299         **bpftool-map**\ (8),
 300         **bpftool-prog**\ (8),
 301         **bpftool-cgroup**\ (8),
 302         **bpftool-feature**\ (8),
 303         **bpftool-net**\ (8),
 304         **bpftool-perf**\ (8),
 305         **bpftool-btf**\ (8)