1.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) 2 3API naming convention 4===================== 5 6libbpf API provides access to a few logically separated groups of 7functions and types. Every group has its own naming convention 8described here. It's recommended to follow these conventions whenever a 9new function or type is added to keep libbpf API clean and consistent. 10 11All types and functions provided by libbpf API should have one of the 12following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``xsk_``, 13``btf_dump_``, ``ring_buffer_``, ``perf_buffer_``. 14 15System call wrappers 16-------------------- 17 18System call wrappers are simple wrappers for commands supported by 19sys_bpf system call. These wrappers should go to ``bpf.h`` header file 20and map one to one to corresponding commands. 21 22For example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM`` 23command of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc. 24 25Objects 26------- 27 28Another class of types and functions provided by libbpf API is "objects" 29and functions to work with them. Objects are high-level abstractions 30such as BPF program or BPF map. They're represented by corresponding 31structures such as ``struct bpf_object``, ``struct bpf_program``, 32``struct bpf_map``, etc. 33 34Structures are forward declared and access to their fields should be 35provided via corresponding getters and setters rather than directly. 36 37These objects are associated with corresponding parts of ELF object that 38contains compiled BPF programs. 39 40For example ``struct bpf_object`` represents ELF object itself created 41from an ELF file or from a buffer, ``struct bpf_program`` represents a 42program in ELF object and ``struct bpf_map`` is a map. 43 44Functions that work with an object have names built from object name, 45double underscore and part that describes function purpose. 46 47For example ``bpf_object__open`` consists of the name of corresponding 48object, ``bpf_object``, double underscore and ``open`` that defines the 49purpose of the function to open ELF file and create ``bpf_object`` from 50it. 51 52All objects and corresponding functions other than BTF related should go 53to ``libbpf.h``. BTF types and functions should go to ``btf.h``. 54 55Auxiliary functions 56------------------- 57 58Auxiliary functions and types that don't fit well in any of categories 59described above should have ``libbpf_`` prefix, e.g. 60``libbpf_get_error`` or ``libbpf_prog_type_by_name``. 61 62AF_XDP functions 63------------------- 64 65AF_XDP functions should have an ``xsk_`` prefix, e.g. 66``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists 67of both low-level ring access functions and high-level configuration 68functions. These can be mixed and matched. Note that these functions 69are not reentrant for performance reasons. 70 71ABI 72--- 73 74libbpf can be both linked statically or used as DSO. To avoid possible 75conflicts with other libraries an application is linked with, all 76non-static libbpf symbols should have one of the prefixes mentioned in 77API documentation above. See API naming convention to choose the right 78name for a new symbol. 79 80Symbol visibility 81----------------- 82 83libbpf follow the model when all global symbols have visibility "hidden" 84by default and to make a symbol visible it has to be explicitly 85attributed 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 91This prevents from accidentally exporting a symbol, that is not supposed 92to be a part of ABI what, in turn, improves both libbpf developer- and 93user-experiences. 94 95ABI versionning 96--------------- 97 98To make future ABI extensions possible libbpf ABI is versioned. 99Versioning is implemented by ``libbpf.map`` version script that is 100passed to linker. 101 102Version name is ``LIBBPF_`` prefix + three-component numeric version, 103starting from ``0.0.1``. 104 105Every time ABI is being changed, e.g. because a new symbol is added or 106semantic of existing symbol is changed, ABI version should be bumped. 107This bump in ABI version is at most once per kernel development cycle. 108 109For 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 141Format of version script and ways to handle ABI changes, including 142incompatible ones, described in details in [1]. 143 144Stand-alone build 145------------------- 146 147Under https://github.com/libbpf/libbpf there is a (semi-)automated 148mirror of the mainline's version of libbpf for a stand-alone build. 149 150However, all changes to libbpf's code base must be upstreamed through 151the mainline kernel tree. 152 153 154API documentation convention 155============================ 156 157The libbpf API is documented via comments above definitions in 158header files. These comments can be rendered by doxygen and sphinx 159for well organized html output. This section describes the 160convention in which these comments should be formated. 161 162Here is an example from btf.h: 163 164.. code-block:: c 165 166 /** 167 * @brief **btf__new()** creates a new instance of a BTF object from the raw 168 * bytes of an ELF's BTF section 169 * @param data raw bytes 170 * @param size number of bytes passed in `data` 171 * @return new BTF object instance which has to be eventually freed with 172 * **btf__free()** 173 * 174 * On error, error-code-encoded-as-pointer is returned, not a NULL. To extract 175 * error code from such a pointer `libbpf_get_error()` should be used. If 176 * `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is enabled, NULL is 177 * returned on error instead. In both cases thread-local `errno` variable is 178 * always set to error code as well. 179 */ 180 181The comment must start with a block comment of the form '/\*\*'. 182 183The documentation always starts with a @brief directive. This line is a short 184description about this API. It starts with the name of the API, denoted in bold 185like so: **api_name**. Please include an open and close parenthesis if this is a 186function. Follow with the short description of the API. A longer form description 187can be added below the last directive, at the bottom of the comment. 188 189Parameters are denoted with the @param directive, there should be one for each 190parameter. If this is a function with a non-void return, use the @return directive 191to document it. 192 193License 194------------------- 195 196libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause. 197 198Links 199------------------- 200 201[1] https://www.akkadia.org/drepper/dsohowto.pdf 202 (Chapter 3. Maintaining APIs and ABIs). 203