README.rst
1.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
2
3libbpf API 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``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-on-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
52Another example: ``bpf_program__load`` is named for corresponding
53object, ``bpf_program``, that is separated from other part of the name
54by double underscore.
55
56All objects and corresponding functions other than BTF related should go
57to ``libbpf.h``. BTF types and functions should go to ``btf.h``.
58
59Auxiliary functions
60-------------------
61
62Auxiliary functions and types that don't fit well in any of categories
63described above should have ``libbpf_`` prefix, e.g.
64``libbpf_get_error`` or ``libbpf_prog_type_by_name``.
65
66AF_XDP functions
67-------------------
68
69AF_XDP functions should have an ``xsk_`` prefix, e.g.
70``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists
71of both low-level ring access functions and high-level configuration
72functions. These can be mixed and matched. Note that these functions
73are not reentrant for performance reasons.
74
75Please take a look at Documentation/networking/af_xdp.rst in the Linux
76kernel source tree on how to use XDP sockets and for some common
77mistakes in case you do not get any traffic up to user space.
78
79libbpf ABI
80==========
81
82libbpf can be both linked statically or used as DSO. To avoid possible
83conflicts with other libraries an application is linked with, all
84non-static libbpf symbols should have one of the prefixes mentioned in
85API documentation above. See API naming convention to choose the right
86name for a new symbol.
87
88Symbol visibility
89-----------------
90
91libbpf follow the model when all global symbols have visibility "hidden"
92by default and to make a symbol visible it has to be explicitly
93attributed with ``LIBBPF_API`` macro. For example:
94
95.. code-block:: c
96
97 LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);
98
99This prevents from accidentally exporting a symbol, that is not supposed
100to be a part of ABI what, in turn, improves both libbpf developer- and
101user-experiences.
102
103ABI versionning
104---------------
105
106To make future ABI extensions possible libbpf ABI is versioned.
107Versioning is implemented by ``libbpf.map`` version script that is
108passed to linker.
109
110Version name is ``LIBBPF_`` prefix + three-component numeric version,
111starting from ``0.0.1``.
112
113Every time ABI is being changed, e.g. because a new symbol is added or
114semantic of existing symbol is changed, ABI version should be bumped.
115This bump in ABI version is at most once per kernel development cycle.
116
117For example, if current state of ``libbpf.map`` is:
118
119.. code-block::
120 LIBBPF_0.0.1 {
121 global:
122 bpf_func_a;
123 bpf_func_b;
124 local:
125 \*;
126 };
127
128, and a new symbol ``bpf_func_c`` is being introduced, then
129``libbpf.map`` should be changed like this:
130
131.. code-block::
132 LIBBPF_0.0.1 {
133 global:
134 bpf_func_a;
135 bpf_func_b;
136 local:
137 \*;
138 };
139 LIBBPF_0.0.2 {
140 global:
141 bpf_func_c;
142 } LIBBPF_0.0.1;
143
144, where new version ``LIBBPF_0.0.2`` depends on the previous
145``LIBBPF_0.0.1``.
146
147Format of version script and ways to handle ABI changes, including
148incompatible ones, described in details in [1].
149
150Stand-alone build
151=================
152
153Under https://github.com/libbpf/libbpf there is a (semi-)automated
154mirror of the mainline's version of libbpf for a stand-alone build.
155
156However, all changes to libbpf's code base must be upstreamed through
157the mainline kernel tree.
158
159License
160=======
161
162libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
163
164Links
165=====
166
167[1] https://www.akkadia.org/drepper/dsohowto.pdf
168 (Chapter 3. Maintaining APIs and ABIs).
169