Documentation/bpf/libbpf/libbpf_naming_convention.rst

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