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_``, ``xsk_``,
13``btf_dump_``, ``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
62AF_XDP functions
63-------------------
64
65AF_XDP functions should have an ``xsk_`` prefix, e.g.
66``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists
67of both low-level ring access functions and high-level configuration
68functions. These can be mixed and matched. Note that these functions
69are not reentrant for performance reasons.
70
71ABI
72==========
73
74libbpf can be both linked statically or used as DSO. To avoid possible
75conflicts with other libraries an application is linked with, all
76non-static libbpf symbols should have one of the prefixes mentioned in
77API documentation above. See API naming convention to choose the right
78name for a new symbol.
79
80Symbol visibility
81-----------------
82
83libbpf follow the model when all global symbols have visibility "hidden"
84by default and to make a symbol visible it has to be explicitly
85attributed 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
91This prevents from accidentally exporting a symbol, that is not supposed
92to be a part of ABI what, in turn, improves both libbpf developer- and
93user-experiences.
94
95ABI versionning
96---------------
97
98To make future ABI extensions possible libbpf ABI is versioned.
99Versioning is implemented by ``libbpf.map`` version script that is
100passed to linker.
101
102Version name is ``LIBBPF_`` prefix + three-component numeric version,
103starting from ``0.0.1``.
104
105Every time ABI is being changed, e.g. because a new symbol is added or
106semantic of existing symbol is changed, ABI version should be bumped.
107This bump in ABI version is at most once per kernel development cycle.
108
109For example, if current state of ``libbpf.map`` is:
110
111.. code-block:: c
112
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
124.. code-block:: c
125
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
141Format of version script and ways to handle ABI changes, including
142incompatible ones, described in details in [1].
143
144Stand-alone build
145-------------------
146
147Under https://github.com/libbpf/libbpf there is a (semi-)automated
148mirror of the mainline's version of libbpf for a stand-alone build.
149
150However, all changes to libbpf's code base must be upstreamed through
151the mainline kernel tree.
152
153License
154-------------------
155
156libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
157
158Links
159-------------------
160
161[1] https://www.akkadia.org/drepper/dsohowto.pdf
162    (Chapter 3. Maintaining APIs and ABIs).
163