tools/lib/bpf/README.rst

   1 .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
   2
   3 libbpf API naming convention
   4 ============================
   5
   6 libbpf API provides access to a few logically separated groups of
   7 functions and types. Every group has its own naming convention
   8 described here. It's recommended to follow these conventions whenever a
   9 new function or type is added to keep libbpf API clean and consistent.
  10
  11 All types and functions provided by libbpf API should have one of the
  12 following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``xsk_``.
  13
  14 System call wrappers
  15 --------------------
  16
  17 System call wrappers are simple wrappers for commands supported by
  18 sys_bpf system call. These wrappers should go to ``bpf.h`` header file
  19 and map one-on-one to corresponding commands.
  20
  21 For example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM``
  22 command of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc.
  23
  24 Objects
  25 -------
  26
  27 Another class of types and functions provided by libbpf API is "objects"
  28 and functions to work with them. Objects are high-level abstractions
  29 such as BPF program or BPF map. They're represented by corresponding
  30 structures such as ``struct bpf_object``, ``struct bpf_program``,
  31 ``struct bpf_map``, etc.
  32
  33 Structures are forward declared and access to their fields should be
  34 provided via corresponding getters and setters rather than directly.
  35
  36 These objects are associated with corresponding parts of ELF object that
  37 contains compiled BPF programs.
  38
  39 For example ``struct bpf_object`` represents ELF object itself created
  40 from an ELF file or from a buffer, ``struct bpf_program`` represents a
  41 program in ELF object and ``struct bpf_map`` is a map.
  42
  43 Functions that work with an object have names built from object name,
  44 double underscore and part that describes function purpose.
  45
  46 For example ``bpf_object__open`` consists of the name of corresponding
  47 object, ``bpf_object``, double underscore and ``open`` that defines the
  48 purpose of the function to open ELF file and create ``bpf_object`` from
  49 it.
  50
  51 Another example: ``bpf_program__load`` is named for corresponding
  52 object, ``bpf_program``, that is separated from other part of the name
  53 by double underscore.
  54
  55 All objects and corresponding functions other than BTF related should go
  56 to ``libbpf.h``. BTF types and functions should go to ``btf.h``.
  57
  58 Auxiliary functions
  59 -------------------
  60
  61 Auxiliary functions and types that don't fit well in any of categories
  62 described above should have ``libbpf_`` prefix, e.g.
  63 ``libbpf_get_error`` or ``libbpf_prog_type_by_name``.
  64
  65 AF_XDP functions
  66 -------------------
  67
  68 AF_XDP functions should have an ``xsk_`` prefix, e.g.
  69 ``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists
  70 of both low-level ring access functions and high-level configuration
  71 functions. These can be mixed and matched. Note that these functions
  72 are not reentrant for performance reasons.
  73
  74 Please take a look at Documentation/networking/af_xdp.rst in the Linux
  75 kernel source tree on how to use XDP sockets and for some common
  76 mistakes in case you do not get any traffic up to user space.
  77
  78 libbpf ABI
  79 ==========
  80
  81 libbpf can be both linked statically or used as DSO. To avoid possible
  82 conflicts with other libraries an application is linked with, all
  83 non-static libbpf symbols should have one of the prefixes mentioned in
  84 API documentation above. See API naming convention to choose the right
  85 name for a new symbol.
  86
  87 Symbol visibility
  88 -----------------
  89
  90 libbpf follow the model when all global symbols have visibility "hidden"
  91 by default and to make a symbol visible it has to be explicitly
  92 attributed with ``LIBBPF_API`` macro. For example:
  93
  94 .. code-block:: c
  95
  96         LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);
  97
  98 This prevents from accidentally exporting a symbol, that is not supposed
  99 to be a part of ABI what, in turn, improves both libbpf developer- and
 100 user-experiences.
 101
 102 ABI versionning
 103 ---------------
 104
 105 To make future ABI extensions possible libbpf ABI is versioned.
 106 Versioning is implemented by ``libbpf.map`` version script that is
 107 passed to linker.
 108
 109 Version name is ``LIBBPF_`` prefix + three-component numeric version,
 110 starting from ``0.0.1``.
 111
 112 Every time ABI is being changed, e.g. because a new symbol is added or
 113 semantic of existing symbol is changed, ABI version should be bumped.
 114 This bump in ABI version is at most once per kernel development cycle.
 115
 116 For example, if current state of ``libbpf.map`` is:
 117
 118 .. code-block::
 119         LIBBPF_0.0.1 {
 120                 global:
 121                         bpf_func_a;
 122                         bpf_func_b;
 123                 local:
 124                         \*;
 125         };
 126
 127 , and a new symbol ``bpf_func_c`` is being introduced, then
 128 ``libbpf.map`` should be changed like this:
 129
 130 .. code-block::
 131         LIBBPF_0.0.1 {
 132                 global:
 133                         bpf_func_a;
 134                         bpf_func_b;
 135                 local:
 136                         \*;
 137         };
 138         LIBBPF_0.0.2 {
 139                 global:
 140                         bpf_func_c;
 141         } LIBBPF_0.0.1;
 142
 143 , where new version ``LIBBPF_0.0.2`` depends on the previous
 144 ``LIBBPF_0.0.1``.
 145
 146 Format of version script and ways to handle ABI changes, including
 147 incompatible ones, described in details in [1].
 148
 149 Stand-alone build
 150 =================
 151
 152 Under https://github.com/libbpf/libbpf there is a (semi-)automated
 153 mirror of the mainline's version of libbpf for a stand-alone build.
 154
 155 However, all changes to libbpf's code base must be upstreamed through
 156 the mainline kernel tree.
 157
 158 License
 159 =======
 160
 161 libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
 162
 163 Links
 164 =====
 165
 166 [1] https://www.akkadia.org/drepper/dsohowto.pdf
 167     (Chapter 3. Maintaining APIs and ABIs).