Commit | Line | Data |
---|---|---|
de94b651 | 1 | .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) |
76d1b894 | 2 | |
f42cfb46 GS |
3 | API naming convention |
4 | ===================== | |
76d1b894 AI |
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 | |
cd07a95f | 12 | following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``xsk_``, |
f42cfb46 | 13 | ``btf_dump_``, ``ring_buffer_``, ``perf_buffer_``. |
76d1b894 AI |
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 | |
f42cfb46 | 20 | and map one to one to corresponding commands. |
76d1b894 AI |
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 | ||
76d1b894 AI |
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 | ||
1cad0788 MK |
62 | AF_XDP functions |
63 | ------------------- | |
64 | ||
65 | AF_XDP functions should have an ``xsk_`` prefix, e.g. | |
66 | ``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists | |
67 | of both low-level ring access functions and high-level configuration | |
68 | functions. These can be mixed and matched. Note that these functions | |
69 | are not reentrant for performance reasons. | |
70 | ||
f42cfb46 | 71 | ABI |
d20b4111 | 72 | --- |
76d1b894 AI |
73 | |
74 | libbpf can be both linked statically or used as DSO. To avoid possible | |
75 | conflicts with other libraries an application is linked with, all | |
76 | non-static libbpf symbols should have one of the prefixes mentioned in | |
77 | API documentation above. See API naming convention to choose the right | |
78 | name for a new symbol. | |
79 | ||
80 | Symbol visibility | |
81 | ----------------- | |
82 | ||
83 | libbpf follow the model when all global symbols have visibility "hidden" | |
84 | by default and to make a symbol visible it has to be explicitly | |
85 | attributed 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 | ||
91 | This prevents from accidentally exporting a symbol, that is not supposed | |
92 | to be a part of ABI what, in turn, improves both libbpf developer- and | |
93 | user-experiences. | |
94 | ||
95 | ABI versionning | |
96 | --------------- | |
97 | ||
98 | To make future ABI extensions possible libbpf ABI is versioned. | |
99 | Versioning is implemented by ``libbpf.map`` version script that is | |
100 | passed to linker. | |
101 | ||
102 | Version name is ``LIBBPF_`` prefix + three-component numeric version, | |
103 | starting from ``0.0.1``. | |
104 | ||
105 | Every time ABI is being changed, e.g. because a new symbol is added or | |
106 | semantic of existing symbol is changed, ABI version should be bumped. | |
63197f78 | 107 | This bump in ABI version is at most once per kernel development cycle. |
76d1b894 AI |
108 | |
109 | For example, if current state of ``libbpf.map`` is: | |
110 | ||
7c4a2233 | 111 | .. code-block:: none |
f42cfb46 | 112 | |
76d1b894 AI |
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 | ||
7c4a2233 | 124 | .. code-block:: none |
f42cfb46 | 125 | |
76d1b894 AI |
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 | ||
141 | Format of version script and ways to handle ABI changes, including | |
142 | incompatible ones, described in details in [1]. | |
143 | ||
80f21ff9 | 144 | Stand-alone build |
f42cfb46 | 145 | ------------------- |
80f21ff9 DB |
146 | |
147 | Under https://github.com/libbpf/libbpf there is a (semi-)automated | |
148 | mirror of the mainline's version of libbpf for a stand-alone build. | |
149 | ||
150 | However, all changes to libbpf's code base must be upstreamed through | |
151 | the mainline kernel tree. | |
152 | ||
93303034 GS |
153 | |
154 | API documentation convention | |
155 | ============================ | |
156 | ||
157 | The libbpf API is documented via comments above definitions in | |
158 | header files. These comments can be rendered by doxygen and sphinx | |
159 | for well organized html output. This section describes the | |
160 | convention in which these comments should be formated. | |
161 | ||
162 | Here 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 | ||
181 | The comment must start with a block comment of the form '/\*\*'. | |
182 | ||
183 | The documentation always starts with a @brief directive. This line is a short | |
184 | description about this API. It starts with the name of the API, denoted in bold | |
185 | like so: **api_name**. Please include an open and close parenthesis if this is a | |
186 | function. Follow with the short description of the API. A longer form description | |
187 | can be added below the last directive, at the bottom of the comment. | |
188 | ||
189 | Parameters are denoted with the @param directive, there should be one for each | |
190 | parameter. If this is a function with a non-void return, use the @return directive | |
191 | to document it. | |
192 | ||
80f21ff9 | 193 | License |
f42cfb46 | 194 | ------------------- |
80f21ff9 DB |
195 | |
196 | libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause. | |
197 | ||
76d1b894 | 198 | Links |
f42cfb46 | 199 | ------------------- |
76d1b894 AI |
200 | |
201 | [1] https://www.akkadia.org/drepper/dsohowto.pdf | |
202 | (Chapter 3. Maintaining APIs and ABIs). |