tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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
14System call wrappers
15--------------------
16
17System call wrappers are simple wrappers for commands supported by
18sys_bpf system call. These wrappers should go to ``bpf.h`` header file
19and map one-on-one to corresponding commands.
20
21For example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM``
22command of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc.
23
24Objects
25-------
26
27Another class of types and functions provided by libbpf API is "objects"
28and functions to work with them. Objects are high-level abstractions
29such as BPF program or BPF map. They're represented by corresponding
30structures such as ``struct bpf_object``, ``struct bpf_program``,
31``struct bpf_map``, etc.
32
33Structures are forward declared and access to their fields should be
34provided via corresponding getters and setters rather than directly.
35
36These objects are associated with corresponding parts of ELF object that
37contains compiled BPF programs.
38
39For example ``struct bpf_object`` represents ELF object itself created
40from an ELF file or from a buffer, ``struct bpf_program`` represents a
41program in ELF object and ``struct bpf_map`` is a map.
42
43Functions that work with an object have names built from object name,
44double underscore and part that describes function purpose.
45
46For example ``bpf_object__open`` consists of the name of corresponding
47object, ``bpf_object``, double underscore and ``open`` that defines the
48purpose of the function to open ELF file and create ``bpf_object`` from
49it.
50
51Another example: ``bpf_program__load`` is named for corresponding
52object, ``bpf_program``, that is separated from other part of the name
53by double underscore.
54
55All objects and corresponding functions other than BTF related should go
56to ``libbpf.h``. BTF types and functions should go to ``btf.h``.
57
58Auxiliary functions
59-------------------
60
61Auxiliary functions and types that don't fit well in any of categories
62described above should have ``libbpf_`` prefix, e.g.
63``libbpf_get_error`` or ``libbpf_prog_type_by_name``.
64
65AF_XDP functions
66-------------------
67
68AF_XDP functions should have an ``xsk_`` prefix, e.g.
69``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists
70of both low-level ring access functions and high-level configuration
71functions. These can be mixed and matched. Note that these functions
72are not reentrant for performance reasons.
73
74Please take a look at Documentation/networking/af_xdp.rst in the Linux
75kernel source tree on how to use XDP sockets and for some common
76mistakes in case you do not get any traffic up to user space.
77
78libbpf ABI
79==========
80
81libbpf can be both linked statically or used as DSO. To avoid possible
82conflicts with other libraries an application is linked with, all
83non-static libbpf symbols should have one of the prefixes mentioned in
84API documentation above. See API naming convention to choose the right
85name for a new symbol.
86
87Symbol visibility
88-----------------
89
90libbpf follow the model when all global symbols have visibility "hidden"
91by default and to make a symbol visible it has to be explicitly
92attributed with ``LIBBPF_API`` macro. For example:
93
94.. code-block:: c
95
96 LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);
97
98This prevents from accidentally exporting a symbol, that is not supposed
99to be a part of ABI what, in turn, improves both libbpf developer- and
100user-experiences.
101
102ABI versionning
103---------------
104
105To make future ABI extensions possible libbpf ABI is versioned.
106Versioning is implemented by ``libbpf.map`` version script that is
107passed to linker.
108
109Version name is ``LIBBPF_`` prefix + three-component numeric version,
110starting from ``0.0.1``.
111
112Every time ABI is being changed, e.g. because a new symbol is added or
113semantic of existing symbol is changed, ABI version should be bumped.
114
115For example, if current state of ``libbpf.map`` is:
116
117.. code-block::
118 LIBBPF_0.0.1 {
119 global:
120 bpf_func_a;
121 bpf_func_b;
122 local:
123 \*;
124 };
125
126, and a new symbol ``bpf_func_c`` is being introduced, then
127``libbpf.map`` should be changed like this:
128
129.. code-block::
130 LIBBPF_0.0.1 {
131 global:
132 bpf_func_a;
133 bpf_func_b;
134 local:
135 \*;
136 };
137 LIBBPF_0.0.2 {
138 global:
139 bpf_func_c;
140 } LIBBPF_0.0.1;
141
142, where new version ``LIBBPF_0.0.2`` depends on the previous
143``LIBBPF_0.0.1``.
144
145Format of version script and ways to handle ABI changes, including
146incompatible ones, described in details in [1].
147
148Stand-alone build
149=================
150
151Under https://github.com/libbpf/libbpf there is a (semi-)automated
152mirror of the mainline's version of libbpf for a stand-alone build.
153
154However, all changes to libbpf's code base must be upstreamed through
155the mainline kernel tree.
156
157License
158=======
159
160libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
161
162Links
163=====
164
165[1] https://www.akkadia.org/drepper/dsohowto.pdf
166 (Chapter 3. Maintaining APIs and ABIs).