Merge tag 'dmaengine-6.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/vkoul...
[linux-block.git] / Documentation / bpf / libbpf / libbpf_naming_convention.rst
CommitLineData
de94b651 1.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
76d1b894 2
f42cfb46
GS
3API naming convention
4=====================
76d1b894
AI
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
fb8ddf24
PL
12following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``btf_dump_``,
13``ring_buffer_``, ``perf_buffer_``.
76d1b894
AI
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
f42cfb46 20and map one to one to corresponding commands.
76d1b894
AI
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
76d1b894
AI
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
f42cfb46 62ABI
d20b4111 63---
76d1b894
AI
64
65libbpf can be both linked statically or used as DSO. To avoid possible
66conflicts with other libraries an application is linked with, all
67non-static libbpf symbols should have one of the prefixes mentioned in
68API documentation above. See API naming convention to choose the right
69name for a new symbol.
70
71Symbol visibility
72-----------------
73
74libbpf follow the model when all global symbols have visibility "hidden"
75by default and to make a symbol visible it has to be explicitly
76attributed with ``LIBBPF_API`` macro. For example:
77
78.. code-block:: c
79
80 LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);
81
82This prevents from accidentally exporting a symbol, that is not supposed
83to be a part of ABI what, in turn, improves both libbpf developer- and
84user-experiences.
85
86ABI versionning
87---------------
88
89To make future ABI extensions possible libbpf ABI is versioned.
90Versioning is implemented by ``libbpf.map`` version script that is
91passed 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 or
97semantic of existing symbol is changed, ABI version should be bumped.
63197f78 98This bump in ABI version is at most once per kernel development cycle.
76d1b894
AI
99
100For example, if current state of ``libbpf.map`` is:
101
7c4a2233 102.. code-block:: none
f42cfb46 103
76d1b894
AI
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, then
113``libbpf.map`` should be changed like this:
114
7c4a2233 115.. code-block:: none
f42cfb46 116
76d1b894
AI
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 previous
130``LIBBPF_0.0.1``.
131
132Format of version script and ways to handle ABI changes, including
133incompatible ones, described in details in [1].
134
80f21ff9 135Stand-alone build
f42cfb46 136-------------------
80f21ff9
DB
137
138Under https://github.com/libbpf/libbpf there is a (semi-)automated
139mirror of the mainline's version of libbpf for a stand-alone build.
140
141However, all changes to libbpf's code base must be upstreamed through
142the mainline kernel tree.
143
93303034
GS
144
145API documentation convention
146============================
147
148The libbpf API is documented via comments above definitions in
149header files. These comments can be rendered by doxygen and sphinx
150for well organized html output. This section describes the
151convention in which these comments should be formated.
152
153Here is an example from btf.h:
154
155.. code-block:: c
156
157 /**
158 * @brief **btf__new()** creates a new instance of a BTF object from the raw
159 * bytes of an ELF's BTF section
160 * @param data raw bytes
161 * @param size number of bytes passed in `data`
162 * @return new BTF object instance which has to be eventually freed with
163 * **btf__free()**
164 *
165 * On error, error-code-encoded-as-pointer is returned, not a NULL. To extract
166 * error code from such a pointer `libbpf_get_error()` should be used. If
167 * `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is enabled, NULL is
168 * returned on error instead. In both cases thread-local `errno` variable is
169 * 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 short
175description about this API. It starts with the name of the API, denoted in bold
176like so: **api_name**. Please include an open and close parenthesis if this is a
177function. Follow with the short description of the API. A longer form description
178can 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 each
181parameter. If this is a function with a non-void return, use the @return directive
182to document it.
183
80f21ff9 184License
f42cfb46 185-------------------
80f21ff9
DB
186
187libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
188
76d1b894 189Links
f42cfb46 190-------------------
76d1b894
AI
191
192[1] https://www.akkadia.org/drepper/dsohowto.pdf
193 (Chapter 3. Maintaining APIs and ABIs).