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_``.
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
65libbpf ABI
66==========
67
68libbpf can be both linked statically or used as DSO. To avoid possible
69conflicts with other libraries an application is linked with, all
70non-static libbpf symbols should have one of the prefixes mentioned in
71API documentation above. See API naming convention to choose the right
72name for a new symbol.
73
74Symbol visibility
75-----------------
76
77libbpf follow the model when all global symbols have visibility "hidden"
78by default and to make a symbol visible it has to be explicitly
79attributed with ``LIBBPF_API`` macro. For example:
80
81.. code-block:: c
82
83 LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);
84
85This prevents from accidentally exporting a symbol, that is not supposed
86to be a part of ABI what, in turn, improves both libbpf developer- and
87user-experiences.
88
89ABI versionning
90---------------
91
92To make future ABI extensions possible libbpf ABI is versioned.
93Versioning is implemented by ``libbpf.map`` version script that is
94passed to linker.
95
96Version name is ``LIBBPF_`` prefix + three-component numeric version,
97starting from ``0.0.1``.
98
99Every time ABI is being changed, e.g. because a new symbol is added or
100semantic of existing symbol is changed, ABI version should be bumped.
101
102For example, if current state of ``libbpf.map`` is:
103
104.. code-block::
105 LIBBPF_0.0.1 {
106 global:
107 bpf_func_a;
108 bpf_func_b;
109 local:
110 \*;
111 };
112
113, and a new symbol ``bpf_func_c`` is being introduced, then
114``libbpf.map`` should be changed like this:
115
116.. code-block::
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
144License
145=======
146
147libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
148
149Links
150=====
151
152[1] https://www.akkadia.org/drepper/dsohowto.pdf
153 (Chapter 3. Maintaining APIs and ABIs).