1.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
2
3API 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_``, ``btf_dump_``,
13``ring_buffer_``, ``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 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
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
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
62ABI
63---
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 versioning
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.
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:: 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
132Format of version script and ways to handle ABI changes, including
133incompatible ones, described in details in [1].
134
135Stand-alone build
136-------------------
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
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 formatted.
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
184License
185-------------------
186
187libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
188
189Links
190-------------------
191
192[1] https://www.akkadia.org/drepper/dsohowto.pdf
193    (Chapter 3. Maintaining APIs and ABIs).
194