1.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) 2 3libbpf API 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``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-on-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 52Another example: ``bpf_program__load`` is named for corresponding 53object, ``bpf_program``, that is separated from other part of the name 54by double underscore. 55 56All objects and corresponding functions other than BTF related should go 57to ``libbpf.h``. BTF types and functions should go to ``btf.h``. 58 59Auxiliary functions 60------------------- 61 62Auxiliary functions and types that don't fit well in any of categories 63described above should have ``libbpf_`` prefix, e.g. 64``libbpf_get_error`` or ``libbpf_prog_type_by_name``. 65 66AF_XDP functions 67------------------- 68 69AF_XDP functions should have an ``xsk_`` prefix, e.g. 70``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists 71of both low-level ring access functions and high-level configuration 72functions. These can be mixed and matched. Note that these functions 73are not reentrant for performance reasons. 74 75Please take a look at Documentation/networking/af_xdp.rst in the Linux 76kernel source tree on how to use XDP sockets and for some common 77mistakes in case you do not get any traffic up to user space. 78 79libbpf ABI 80========== 81 82libbpf can be both linked statically or used as DSO. To avoid possible 83conflicts with other libraries an application is linked with, all 84non-static libbpf symbols should have one of the prefixes mentioned in 85API documentation above. See API naming convention to choose the right 86name for a new symbol. 87 88Symbol visibility 89----------------- 90 91libbpf follow the model when all global symbols have visibility "hidden" 92by default and to make a symbol visible it has to be explicitly 93attributed with ``LIBBPF_API`` macro. For example: 94 95.. code-block:: c 96 97 LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id); 98 99This prevents from accidentally exporting a symbol, that is not supposed 100to be a part of ABI what, in turn, improves both libbpf developer- and 101user-experiences. 102 103ABI versionning 104--------------- 105 106To make future ABI extensions possible libbpf ABI is versioned. 107Versioning is implemented by ``libbpf.map`` version script that is 108passed to linker. 109 110Version name is ``LIBBPF_`` prefix + three-component numeric version, 111starting from ``0.0.1``. 112 113Every time ABI is being changed, e.g. because a new symbol is added or 114semantic of existing symbol is changed, ABI version should be bumped. 115This bump in ABI version is at most once per kernel development cycle. 116 117For example, if current state of ``libbpf.map`` is: 118 119.. code-block:: 120 LIBBPF_0.0.1 { 121 global: 122 bpf_func_a; 123 bpf_func_b; 124 local: 125 \*; 126 }; 127 128, and a new symbol ``bpf_func_c`` is being introduced, then 129``libbpf.map`` should be changed like this: 130 131.. code-block:: 132 LIBBPF_0.0.1 { 133 global: 134 bpf_func_a; 135 bpf_func_b; 136 local: 137 \*; 138 }; 139 LIBBPF_0.0.2 { 140 global: 141 bpf_func_c; 142 } LIBBPF_0.0.1; 143 144, where new version ``LIBBPF_0.0.2`` depends on the previous 145``LIBBPF_0.0.1``. 146 147Format of version script and ways to handle ABI changes, including 148incompatible ones, described in details in [1]. 149 150Stand-alone build 151================= 152 153Under https://github.com/libbpf/libbpf there is a (semi-)automated 154mirror of the mainline's version of libbpf for a stand-alone build. 155 156However, all changes to libbpf's code base must be upstreamed through 157the mainline kernel tree. 158 159License 160======= 161 162libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause. 163 164Links 165===== 166 167[1] https://www.akkadia.org/drepper/dsohowto.pdf 168 (Chapter 3. Maintaining APIs and ABIs). 169