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

   1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2
   3 ================
   4 bpftool-gen
   5 ================
   6 -------------------------------------------------------------------------------
   7 tool for BPF code-generation
   8 -------------------------------------------------------------------------------
   9
  10 :Manual section: 8
  11
  12 .. include:: substitutions.rst
  13
  14 SYNOPSIS
  15 ========
  16
  17         **bpftool** [*OPTIONS*] **gen** *COMMAND*
  18
  19         *OPTIONS* := { |COMMON_OPTIONS| | { **-L** | **--use-loader** } }
  20
  21         *COMMAND* := { **object** | **skeleton** | **help** }
  22
  23 GEN COMMANDS
  24 =============
  25
  26 |       **bpftool** **gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...]
  27 |       **bpftool** **gen skeleton** *FILE* [**name** *OBJECT_NAME*]
  28 |       **bpftool** **gen subskeleton** *FILE* [**name** *OBJECT_NAME*]
  29 |       **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...]
  30 |       **bpftool** **gen help**
  31
  32 DESCRIPTION
  33 ===========
  34         **bpftool gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...]
  35                   Statically link (combine) together one or more *INPUT_FILE*'s
  36                   into a single resulting *OUTPUT_FILE*. All the files involved
  37                   are BPF ELF object files.
  38
  39                   The rules of BPF static linking are mostly the same as for
  40                   user-space object files, but in addition to combining data
  41                   and instruction sections, .BTF and .BTF.ext (if present in
  42                   any of the input files) data are combined together. .BTF
  43                   data is deduplicated, so all the common types across
  44                   *INPUT_FILE*'s will only be represented once in the resulting
  45                   BTF information.
  46
  47                   BPF static linking allows to partition BPF source code into
  48                   individually compiled files that are then linked into
  49                   a single resulting BPF object file, which can be used to
  50                   generated BPF skeleton (with **gen skeleton** command) or
  51                   passed directly into **libbpf** (using **bpf_object__open()**
  52                   family of APIs).
  53
  54         **bpftool gen skeleton** *FILE*
  55                   Generate BPF skeleton C header file for a given *FILE*.
  56
  57                   BPF skeleton is an alternative interface to existing libbpf
  58                   APIs for working with BPF objects. Skeleton code is intended
  59                   to significantly shorten and simplify code to load and work
  60                   with BPF programs from userspace side. Generated code is
  61                   tailored to specific input BPF object *FILE*, reflecting its
  62                   structure by listing out available maps, program, variables,
  63                   etc. Skeleton eliminates the need to lookup mentioned
  64                   components by name. Instead, if skeleton instantiation
  65                   succeeds, they are populated in skeleton structure as valid
  66                   libbpf types (e.g., **struct bpf_map** pointer) and can be
  67                   passed to existing generic libbpf APIs.
  68
  69                   In addition to simple and reliable access to maps and
  70                   programs, skeleton provides a storage for BPF links (**struct
  71                   bpf_link**) for each BPF program within BPF object. When
  72                   requested, supported BPF programs will be automatically
  73                   attached and resulting BPF links stored for further use by
  74                   user in pre-allocated fields in skeleton struct. For BPF
  75                   programs that can't be automatically attached by libbpf,
  76                   user can attach them manually, but store resulting BPF link
  77                   in per-program link field. All such set up links will be
  78                   automatically destroyed on BPF skeleton destruction. This
  79                   eliminates the need for users to manage links manually and
  80                   rely on libbpf support to detach programs and free up
  81                   resources.
  82
  83                   Another facility provided by BPF skeleton is an interface to
  84                   global variables of all supported kinds: mutable, read-only,
  85                   as well as extern ones. This interface allows to pre-setup
  86                   initial values of variables before BPF object is loaded and
  87                   verified by kernel. For non-read-only variables, the same
  88                   interface can be used to fetch values of global variables on
  89                   userspace side, even if they are modified by BPF code.
  90
  91                   During skeleton generation, contents of source BPF object
  92                   *FILE* is embedded within generated code and is thus not
  93                   necessary to keep around. This ensures skeleton and BPF
  94                   object file are matching 1-to-1 and always stay in sync.
  95                   Generated code is dual-licensed under LGPL-2.1 and
  96                   BSD-2-Clause licenses.
  97
  98                   It is a design goal and guarantee that skeleton interfaces
  99                   are interoperable with generic libbpf APIs. User should
 100                   always be able to use skeleton API to create and load BPF
 101                   object, and later use libbpf APIs to keep working with
 102                   specific maps, programs, etc.
 103
 104                   As part of skeleton, few custom functions are generated.
 105                   Each of them is prefixed with object name. Object name can
 106                   either be derived from object file name, i.e., if BPF object
 107                   file name is **example.o**, BPF object name will be
 108                   **example**. Object name can be also specified explicitly
 109                   through **name** *OBJECT_NAME* parameter. The following
 110                   custom functions are provided (assuming **example** as
 111                   the object name):
 112
 113                   - **example__open** and **example__open_opts**.
 114                     These functions are used to instantiate skeleton. It
 115                     corresponds to libbpf's **bpf_object__open**\ () API.
 116                     **_opts** variants accepts extra **bpf_object_open_opts**
 117                     options.
 118
 119                   - **example__load**.
 120                     This function creates maps, loads and verifies BPF
 121                     programs, initializes global data maps. It corresponds to
 122                     libppf's **bpf_object__load**\ () API.
 123
 124                   - **example__open_and_load** combines **example__open** and
 125                     **example__load** invocations in one commonly used
 126                     operation.
 127
 128                   - **example__attach** and **example__detach**
 129                     This pair of functions allow to attach and detach,
 130                     correspondingly, already loaded BPF object. Only BPF
 131                     programs of types supported by libbpf for auto-attachment
 132                     will be auto-attached and their corresponding BPF links
 133                     instantiated. For other BPF programs, user can manually
 134                     create a BPF link and assign it to corresponding fields in
 135                     skeleton struct. **example__detach** will detach both
 136                     links created automatically, as well as those populated by
 137                     user manually.
 138
 139                   - **example__destroy**
 140                     Detach and unload BPF programs, free up all the resources
 141                     used by skeleton and BPF object.
 142
 143                   If BPF object has global variables, corresponding structs
 144                   with memory layout corresponding to global data data section
 145                   layout will be created. Currently supported ones are: *.data*,
 146                   *.bss*, *.rodata*, and *.kconfig* structs/data sections.
 147                   These data sections/structs can be used to set up initial
 148                   values of variables, if set before **example__load**.
 149                   Afterwards, if target kernel supports memory-mapped BPF
 150                   arrays, same structs can be used to fetch and update
 151                   (non-read-only) data from userspace, with same simplicity
 152                   as for BPF side.
 153
 154         **bpftool gen subskeleton** *FILE*
 155                   Generate BPF subskeleton C header file for a given *FILE*.
 156
 157                   Subskeletons are similar to skeletons, except they do not own
 158                   the corresponding maps, programs, or global variables. They
 159                   require that the object file used to generate them is already
 160                   loaded into a *bpf_object* by some other means.
 161
 162                   This functionality is useful when a library is included into a
 163                   larger BPF program. A subskeleton for the library would have
 164                   access to all objects and globals defined in it, without
 165                   having to know about the larger program.
 166
 167                   Consequently, there are only two functions defined
 168                   for subskeletons:
 169
 170                   - **example__open(bpf_object\*)**
 171                     Instantiates a subskeleton from an already opened (but not
 172                     necessarily loaded) **bpf_object**.
 173
 174                   - **example__destroy()**
 175                     Frees the storage for the subskeleton but *does not* unload
 176                     any BPF programs or maps.
 177
 178         **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...]
 179                   Generate a minimum BTF file as *OUTPUT*, derived from a given
 180                   *INPUT* BTF file, containing all needed BTF types so one, or
 181                   more, given eBPF objects CO-RE relocations may be satisfied.
 182
 183                   When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF,
 184                   libbpf, when loading an eBPF object, has to rely on external
 185                   BTF files to be able to calculate CO-RE relocations.
 186
 187                   Usually, an external BTF file is built from existing kernel
 188                   DWARF data using pahole. It contains all the types used by
 189                   its respective kernel image and, because of that, is big.
 190
 191                   The min_core_btf feature builds smaller BTF files, customized
 192                   to one or multiple eBPF objects, so they can be distributed
 193                   together with an eBPF CO-RE based application, turning the
 194                   application portable to different kernel versions.
 195
 196                   Check examples bellow for more information how to use it.
 197
 198         **bpftool gen help**
 199                   Print short help message.
 200
 201 OPTIONS
 202 =======
 203         .. include:: common_options.rst
 204
 205         -L, --use-loader
 206                   For skeletons, generate a "light" skeleton (also known as "loader"
 207                   skeleton). A light skeleton contains a loader eBPF program. It does
 208                   not use the majority of the libbpf infrastructure, and does not need
 209                   libelf.
 210
 211 EXAMPLES
 212 ========
 213 **$ cat example1.bpf.c**
 214
 215 ::
 216
 217   #include <stdbool.h>
 218   #include <linux/ptrace.h>
 219   #include <linux/bpf.h>
 220   #include <bpf/bpf_helpers.h>
 221
 222   const volatile int param1 = 42;
 223   bool global_flag = true;
 224   struct { int x; } data = {};
 225
 226   SEC("raw_tp/sys_enter")
 227   int handle_sys_enter(struct pt_regs *ctx)
 228   {
 229         static long my_static_var;
 230         if (global_flag)
 231                 my_static_var++;
 232         else
 233                 data.x += param1;
 234         return 0;
 235   }
 236
 237 **$ cat example2.bpf.c**
 238
 239 ::
 240
 241   #include <linux/ptrace.h>
 242   #include <linux/bpf.h>
 243   #include <bpf/bpf_helpers.h>
 244
 245   struct {
 246         __uint(type, BPF_MAP_TYPE_HASH);
 247         __uint(max_entries, 128);
 248         __type(key, int);
 249         __type(value, long);
 250   } my_map SEC(".maps");
 251
 252   SEC("raw_tp/sys_exit")
 253   int handle_sys_exit(struct pt_regs *ctx)
 254   {
 255         int zero = 0;
 256         bpf_map_lookup_elem(&my_map, &zero);
 257         return 0;
 258   }
 259
 260 **$ cat example3.bpf.c**
 261
 262 ::
 263
 264   #include <linux/ptrace.h>
 265   #include <linux/bpf.h>
 266   #include <bpf/bpf_helpers.h>
 267   /* This header file is provided by the bpf_testmod module. */
 268   #include "bpf_testmod.h"
 269
 270   int test_2_result = 0;
 271
 272   /* bpf_Testmod.ko calls this function, passing a "4"
 273    * and testmod_map->data.
 274    */
 275   SEC("struct_ops/test_2")
 276   void BPF_PROG(test_2, int a, int b)
 277   {
 278         test_2_result = a + b;
 279   }
 280
 281   SEC(".struct_ops")
 282   struct bpf_testmod_ops testmod_map = {
 283         .test_2 = (void *)test_2,
 284         .data = 0x1,
 285   };
 286
 287 This is example BPF application with three BPF programs and a mix of BPF
 288 maps and global variables. Source code is split across three source code
 289 files.
 290
 291 **$ clang --target=bpf -g example1.bpf.c -o example1.bpf.o**
 292
 293 **$ clang --target=bpf -g example2.bpf.c -o example2.bpf.o**
 294
 295 **$ clang --target=bpf -g example3.bpf.c -o example3.bpf.o**
 296
 297 **$ bpftool gen object example.bpf.o example1.bpf.o example2.bpf.o example3.bpf.o**
 298
 299 This set of commands compiles *example1.bpf.c*, *example2.bpf.c* and
 300 *example3.bpf.c* individually and then statically links respective object
 301 files into the final BPF ELF object file *example.bpf.o*.
 302
 303 **$ bpftool gen skeleton example.bpf.o name example | tee example.skel.h**
 304
 305 ::
 306
 307   /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
 308
 309   /* THIS FILE IS AUTOGENERATED! */
 310   #ifndef __EXAMPLE_SKEL_H__
 311   #define __EXAMPLE_SKEL_H__
 312
 313   #include <stdlib.h>
 314   #include <bpf/libbpf.h>
 315
 316   struct example {
 317         struct bpf_object_skeleton *skeleton;
 318         struct bpf_object *obj;
 319         struct {
 320                 struct bpf_map *rodata;
 321                 struct bpf_map *data;
 322                 struct bpf_map *bss;
 323                 struct bpf_map *my_map;
 324                 struct bpf_map *testmod_map;
 325         } maps;
 326         struct {
 327                 struct example__testmod_map__bpf_testmod_ops {
 328                         const struct bpf_program *test_1;
 329                         const struct bpf_program *test_2;
 330                         int data;
 331                 } *testmod_map;
 332         } struct_ops;
 333         struct {
 334                 struct bpf_program *handle_sys_enter;
 335                 struct bpf_program *handle_sys_exit;
 336         } progs;
 337         struct {
 338                 struct bpf_link *handle_sys_enter;
 339                 struct bpf_link *handle_sys_exit;
 340         } links;
 341         struct example__bss {
 342                 struct {
 343                         int x;
 344                 } data;
 345                 int test_2_result;
 346         } *bss;
 347         struct example__data {
 348                 _Bool global_flag;
 349                 long int handle_sys_enter_my_static_var;
 350         } *data;
 351         struct example__rodata {
 352                 int param1;
 353         } *rodata;
 354   };
 355
 356   static void example__destroy(struct example *obj);
 357   static inline struct example *example__open_opts(
 358                 const struct bpf_object_open_opts *opts);
 359   static inline struct example *example__open();
 360   static inline int example__load(struct example *obj);
 361   static inline struct example *example__open_and_load();
 362   static inline int example__attach(struct example *obj);
 363   static inline void example__detach(struct example *obj);
 364
 365   #endif /* __EXAMPLE_SKEL_H__ */
 366
 367 **$ cat example.c**
 368
 369 ::
 370
 371   #include "example.skel.h"
 372
 373   int main()
 374   {
 375         struct example *skel;
 376         int err = 0;
 377
 378         skel = example__open();
 379         if (!skel)
 380                 goto cleanup;
 381
 382         skel->rodata->param1 = 128;
 383
 384         /* Change the value through the pointer of shadow type */
 385         skel->struct_ops.testmod_map->data = 13;
 386
 387         err = example__load(skel);
 388         if (err)
 389                 goto cleanup;
 390
 391         /* The result of the function test_2() */
 392         printf("test_2_result: %d\n", skel->bss->test_2_result);
 393
 394         err = example__attach(skel);
 395         if (err)
 396                 goto cleanup;
 397
 398         /* all libbpf APIs are usable */
 399         printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
 400         printf("sys_enter prog FD: %d\n",
 401                bpf_program__fd(skel->progs.handle_sys_enter));
 402
 403         /* detach and re-attach sys_exit program */
 404         bpf_link__destroy(skel->links.handle_sys_exit);
 405         skel->links.handle_sys_exit =
 406                 bpf_program__attach(skel->progs.handle_sys_exit);
 407
 408         printf("my_static_var: %ld\n",
 409                skel->bss->handle_sys_enter_my_static_var);
 410
 411   cleanup:
 412         example__destroy(skel);
 413         return err;
 414   }
 415
 416 **# ./example**
 417
 418 ::
 419
 420   test_2_result: 17
 421   my_map name: my_map
 422   sys_enter prog FD: 8
 423   my_static_var: 7
 424
 425 This is a stripped-out version of skeleton generated for above example code.
 426
 427 min_core_btf
 428 ------------
 429
 430 **$ bpftool btf dump file 5.4.0-example.btf format raw**
 431
 432 ::
 433
 434   [1] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
 435   [2] CONST '(anon)' type_id=1
 436   [3] VOLATILE '(anon)' type_id=1
 437   [4] ARRAY '(anon)' type_id=1 index_type_id=21 nr_elems=2
 438   [5] PTR '(anon)' type_id=8
 439   [6] CONST '(anon)' type_id=5
 440   [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=(none)
 441   [8] CONST '(anon)' type_id=7
 442   [9] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
 443   <long output>
 444
 445 **$ bpftool btf dump file one.bpf.o format raw**
 446
 447 ::
 448
 449   [1] PTR '(anon)' type_id=2
 450   [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=4
 451         'ent' type_id=3 bits_offset=0
 452         'id' type_id=7 bits_offset=64
 453         'args' type_id=9 bits_offset=128
 454         '__data' type_id=12 bits_offset=512
 455   [3] STRUCT 'trace_entry' size=8 vlen=4
 456         'type' type_id=4 bits_offset=0
 457         'flags' type_id=5 bits_offset=16
 458         'preempt_count' type_id=5 bits_offset=24
 459   <long output>
 460
 461 **$ bpftool gen min_core_btf 5.4.0-example.btf 5.4.0-smaller.btf one.bpf.o**
 462
 463 **$ bpftool btf dump file 5.4.0-smaller.btf format raw**
 464
 465 ::
 466
 467   [1] TYPEDEF 'pid_t' type_id=6
 468   [2] STRUCT 'trace_event_raw_sys_enter' size=64 vlen=1
 469         'args' type_id=4 bits_offset=128
 470   [3] STRUCT 'task_struct' size=9216 vlen=2
 471         'pid' type_id=1 bits_offset=17920
 472         'real_parent' type_id=7 bits_offset=18048
 473   [4] ARRAY '(anon)' type_id=5 index_type_id=8 nr_elems=6
 474   [5] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
 475   [6] TYPEDEF '__kernel_pid_t' type_id=8
 476   [7] PTR '(anon)' type_id=3
 477   [8] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
 478   <end>
 479
 480 Now, the "5.4.0-smaller.btf" file may be used by libbpf as an external BTF file
 481 when loading the "one.bpf.o" object into the "5.4.0-example" kernel. Note that
 482 the generated BTF file won't allow other eBPF objects to be loaded, just the
 483 ones given to min_core_btf.
 484
 485 ::
 486
 487   LIBBPF_OPTS(bpf_object_open_opts, opts, .btf_custom_path = "5.4.0-smaller.btf");
 488   struct bpf_object *obj;
 489
 490   obj = bpf_object__open_file("one.bpf.o", &opts);
 491
 492   ...