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_``, ``btf_dump_``,
13 ``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 ABI
63 ---
64
65 libbpf can be both linked statically or used as DSO. To avoid possible
66 conflicts with other libraries an application is linked with, all
67 non-static libbpf symbols should have one of the prefixes mentioned in
68 API documentation above. See API naming convention to choose the right
69 name for a new symbol.
70
71 Symbol visibility
72 -----------------
73
74 libbpf follow the model when all global symbols have visibility "hidden"
75 by default and to make a symbol visible it has to be explicitly
76 attributed 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
82 This prevents from accidentally exporting a symbol, that is not supposed
83 to be a part of ABI what, in turn, improves both libbpf developer- and
84 user-experiences.
85
86 ABI versioning
87 --------------
88
89 To make future ABI extensions possible libbpf ABI is versioned.
90 Versioning is implemented by ``libbpf.map`` version script that is
91 passed to linker.
92
93 Version name is ``LIBBPF_`` prefix + three-component numeric version,
94 starting from ``0.0.1``.
95
96 Every time ABI is being changed, e.g. because a new symbol is added or
97 semantic of existing symbol is changed, ABI version should be bumped.
98 This bump in ABI version is at most once per kernel development cycle.
99
100 For example, if current state of ``libbpf.map`` is:
101
102 .. code-block:: none
103
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
115 .. code-block:: none
116
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
132 Format of version script and ways to handle ABI changes, including
133 incompatible ones, described in details in [1].
134
135 Stand-alone build
136 -------------------
137
138 Under https://github.com/libbpf/libbpf there is a (semi-)automated
139 mirror of the mainline's version of libbpf for a stand-alone build.
140
141 However, all changes to libbpf's code base must be upstreamed through
142 the mainline kernel tree.
143
144
145 API documentation convention
146 ============================
147
148 The libbpf API is documented via comments above definitions in
149 header files. These comments can be rendered by doxygen and sphinx
150 for well organized html output. This section describes the
151 convention in which these comments should be formatted.
152
153 Here 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
172 The comment must start with a block comment of the form '/\*\*'.
173
174 The documentation always starts with a @brief directive. This line is a short
175 description about this API. It starts with the name of the API, denoted in bold
176 like so: **api_name**. Please include an open and close parenthesis if this is a
177 function. Follow with the short description of the API. A longer form description
178 can be added below the last directive, at the bottom of the comment.
179
180 Parameters are denoted with the @param directive, there should be one for each
181 parameter. If this is a function with a non-void return, use the @return directive
182 to document it.
183
184 License
185 -------------------
186
187 libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
188
189 Links
190 -------------------
191
192 [1] https://www.akkadia.org/drepper/dsohowto.pdf
193 (Chapter 3. Maintaining APIs and ABIs).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.