194 lines · plain
1.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)2 3API naming convention4=====================5 6libbpf API provides access to a few logically separated groups of7functions and types. Every group has its own naming convention8described here. It's recommended to follow these conventions whenever a9new 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 the12following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``btf_dump_``,13``ring_buffer_``, ``perf_buffer_``.14 15System call wrappers16--------------------17 18System call wrappers are simple wrappers for commands supported by19sys_bpf system call. These wrappers should go to ``bpf.h`` header file20and 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 25Objects26-------27 28Another class of types and functions provided by libbpf API is "objects"29and functions to work with them. Objects are high-level abstractions30such as BPF program or BPF map. They're represented by corresponding31structures such as ``struct bpf_object``, ``struct bpf_program``,32``struct bpf_map``, etc.33 34Structures are forward declared and access to their fields should be35provided via corresponding getters and setters rather than directly.36 37These objects are associated with corresponding parts of ELF object that38contains compiled BPF programs.39 40For example ``struct bpf_object`` represents ELF object itself created41from an ELF file or from a buffer, ``struct bpf_program`` represents a42program 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 corresponding48object, ``bpf_object``, double underscore and ``open`` that defines the49purpose of the function to open ELF file and create ``bpf_object`` from50it.51 52All objects and corresponding functions other than BTF related should go53to ``libbpf.h``. BTF types and functions should go to ``btf.h``.54 55Auxiliary functions56-------------------57 58Auxiliary functions and types that don't fit well in any of categories59described above should have ``libbpf_`` prefix, e.g.60``libbpf_get_error`` or ``libbpf_prog_type_by_name``.61 62ABI63---64 65libbpf can be both linked statically or used as DSO. To avoid possible66conflicts with other libraries an application is linked with, all67non-static libbpf symbols should have one of the prefixes mentioned in68API documentation above. See API naming convention to choose the right69name for a new symbol.70 71Symbol visibility72-----------------73 74libbpf follow the model when all global symbols have visibility "hidden"75by default and to make a symbol visible it has to be explicitly76attributed with ``LIBBPF_API`` macro. For example:77 78.. code-block:: c79 80 LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);81 82This prevents from accidentally exporting a symbol, that is not supposed83to be a part of ABI what, in turn, improves both libbpf developer- and84user-experiences.85 86ABI versioning87--------------88 89To make future ABI extensions possible libbpf ABI is versioned.90Versioning is implemented by ``libbpf.map`` version script that is91passed to linker.92 93Version name is ``LIBBPF_`` prefix + three-component numeric version,94starting from ``0.0.1``.95 96Every time ABI is being changed, e.g. because a new symbol is added or97semantic of existing symbol is changed, ABI version should be bumped.98This bump in ABI version is at most once per kernel development cycle.99 100For example, if current state of ``libbpf.map`` is:101 102.. code-block:: none103 104 LIBBPF_0.0.1 {105 global:106 bpf_func_a;107 bpf_func_b;108 local:109 \*;110 };111 112, and a new symbol ``bpf_func_c`` is being introduced, then113``libbpf.map`` should be changed like this:114 115.. code-block:: none116 117 LIBBPF_0.0.1 {118 global:119 bpf_func_a;120 bpf_func_b;121 local:122 \*;123 };124 LIBBPF_0.0.2 {125 global:126 bpf_func_c;127 } LIBBPF_0.0.1;128 129, where new version ``LIBBPF_0.0.2`` depends on the previous130``LIBBPF_0.0.1``.131 132Format of version script and ways to handle ABI changes, including133incompatible ones, described in details in [1].134 135Stand-alone build136-------------------137 138Under https://github.com/libbpf/libbpf there is a (semi-)automated139mirror of the mainline's version of libbpf for a stand-alone build.140 141However, all changes to libbpf's code base must be upstreamed through142the mainline kernel tree.143 144 145API documentation convention146============================147 148The libbpf API is documented via comments above definitions in149header files. These comments can be rendered by doxygen and sphinx150for well organized html output. This section describes the151convention in which these comments should be formatted.152 153Here is an example from btf.h:154 155.. code-block:: c156 157 /**158 * @brief **btf__new()** creates a new instance of a BTF object from the raw159 * bytes of an ELF's BTF section160 * @param data raw bytes161 * @param size number of bytes passed in `data`162 * @return new BTF object instance which has to be eventually freed with163 * **btf__free()**164 *165 * On error, error-code-encoded-as-pointer is returned, not a NULL. To extract166 * error code from such a pointer `libbpf_get_error()` should be used. If167 * `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is enabled, NULL is168 * returned on error instead. In both cases thread-local `errno` variable is169 * always set to error code as well.170 */171 172The comment must start with a block comment of the form '/\*\*'.173 174The documentation always starts with a @brief directive. This line is a short175description about this API. It starts with the name of the API, denoted in bold176like so: **api_name**. Please include an open and close parenthesis if this is a177function. Follow with the short description of the API. A longer form description178can be added below the last directive, at the bottom of the comment.179 180Parameters are denoted with the @param directive, there should be one for each181parameter. If this is a function with a non-void return, use the @return directive182to document it.183 184License185-------------------186 187libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.188 189Links190-------------------191 192[1] https://www.akkadia.org/drepper/dsohowto.pdf193 (Chapter 3. Maintaining APIs and ABIs).194