Commit | Line | Data |
---|---|---|
de94b651 | 1 | .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) |
76d1b894 | 2 | |
f42cfb46 GS |
3 | API naming convention |
4 | ===================== | |
76d1b894 AI |
5 | |
6 | libbpf API provides access to a few logically separated groups of | |
7 | functions and types. Every group has its own naming convention | |
8 | described here. It's recommended to follow these conventions whenever a | |
9 | new function or type is added to keep libbpf API clean and consistent. | |
10 | ||
11 | All types and functions provided by libbpf API should have one of the | |
cd07a95f | 12 | following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``xsk_``, |
f42cfb46 | 13 | ``btf_dump_``, ``ring_buffer_``, ``perf_buffer_``. |
76d1b894 AI |
14 | |
15 | System call wrappers | |
16 | -------------------- | |
17 | ||
18 | System call wrappers are simple wrappers for commands supported by | |
19 | sys_bpf system call. These wrappers should go to ``bpf.h`` header file | |
f42cfb46 | 20 | and map one to one to corresponding commands. |
76d1b894 AI |
21 | |
22 | For example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM`` | |
23 | command of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc. | |
24 | ||
25 | Objects | |
26 | ------- | |
27 | ||
28 | Another class of types and functions provided by libbpf API is "objects" | |
29 | and functions to work with them. Objects are high-level abstractions | |
30 | such as BPF program or BPF map. They're represented by corresponding | |
31 | structures such as ``struct bpf_object``, ``struct bpf_program``, | |
32 | ``struct bpf_map``, etc. | |
33 | ||
34 | Structures are forward declared and access to their fields should be | |
35 | provided via corresponding getters and setters rather than directly. | |
36 | ||
37 | These objects are associated with corresponding parts of ELF object that | |
38 | contains compiled BPF programs. | |
39 | ||
40 | For example ``struct bpf_object`` represents ELF object itself created | |
41 | from an ELF file or from a buffer, ``struct bpf_program`` represents a | |
42 | program in ELF object and ``struct bpf_map`` is a map. | |
43 | ||
44 | Functions that work with an object have names built from object name, | |
45 | double underscore and part that describes function purpose. | |
46 | ||
47 | For example ``bpf_object__open`` consists of the name of corresponding | |
48 | object, ``bpf_object``, double underscore and ``open`` that defines the | |
49 | purpose of the function to open ELF file and create ``bpf_object`` from | |
50 | it. | |
51 | ||
76d1b894 AI |
52 | All objects and corresponding functions other than BTF related should go |
53 | to ``libbpf.h``. BTF types and functions should go to ``btf.h``. | |
54 | ||
55 | Auxiliary functions | |
56 | ------------------- | |
57 | ||
58 | Auxiliary functions and types that don't fit well in any of categories | |
59 | described above should have ``libbpf_`` prefix, e.g. | |
60 | ``libbpf_get_error`` or ``libbpf_prog_type_by_name``. | |
61 | ||
1cad0788 MK |
62 | AF_XDP functions |
63 | ------------------- | |
64 | ||
65 | AF_XDP functions should have an ``xsk_`` prefix, e.g. | |
66 | ``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists | |
67 | of both low-level ring access functions and high-level configuration | |
68 | functions. These can be mixed and matched. Note that these functions | |
69 | are not reentrant for performance reasons. | |
70 | ||
f42cfb46 | 71 | ABI |
76d1b894 AI |
72 | ========== |
73 | ||
74 | libbpf can be both linked statically or used as DSO. To avoid possible | |
75 | conflicts with other libraries an application is linked with, all | |
76 | non-static libbpf symbols should have one of the prefixes mentioned in | |
77 | API documentation above. See API naming convention to choose the right | |
78 | name for a new symbol. | |
79 | ||
80 | Symbol visibility | |
81 | ----------------- | |
82 | ||
83 | libbpf follow the model when all global symbols have visibility "hidden" | |
84 | by default and to make a symbol visible it has to be explicitly | |
85 | attributed 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 | ||
91 | This prevents from accidentally exporting a symbol, that is not supposed | |
92 | to be a part of ABI what, in turn, improves both libbpf developer- and | |
93 | user-experiences. | |
94 | ||
95 | ABI versionning | |
96 | --------------- | |
97 | ||
98 | To make future ABI extensions possible libbpf ABI is versioned. | |
99 | Versioning is implemented by ``libbpf.map`` version script that is | |
100 | passed to linker. | |
101 | ||
102 | Version name is ``LIBBPF_`` prefix + three-component numeric version, | |
103 | starting from ``0.0.1``. | |
104 | ||
105 | Every time ABI is being changed, e.g. because a new symbol is added or | |
106 | semantic of existing symbol is changed, ABI version should be bumped. | |
63197f78 | 107 | This bump in ABI version is at most once per kernel development cycle. |
76d1b894 AI |
108 | |
109 | For example, if current state of ``libbpf.map`` is: | |
110 | ||
7c4a2233 | 111 | .. code-block:: none |
f42cfb46 | 112 | |
76d1b894 AI |
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 | ||
7c4a2233 | 124 | .. code-block:: none |
f42cfb46 | 125 | |
76d1b894 AI |
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 | ||
141 | Format of version script and ways to handle ABI changes, including | |
142 | incompatible ones, described in details in [1]. | |
143 | ||
80f21ff9 | 144 | Stand-alone build |
f42cfb46 | 145 | ------------------- |
80f21ff9 DB |
146 | |
147 | Under https://github.com/libbpf/libbpf there is a (semi-)automated | |
148 | mirror of the mainline's version of libbpf for a stand-alone build. | |
149 | ||
150 | However, all changes to libbpf's code base must be upstreamed through | |
151 | the mainline kernel tree. | |
152 | ||
153 | License | |
f42cfb46 | 154 | ------------------- |
80f21ff9 DB |
155 | |
156 | libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause. | |
157 | ||
76d1b894 | 158 | Links |
f42cfb46 | 159 | ------------------- |
76d1b894 AI |
160 | |
161 | [1] https://www.akkadia.org/drepper/dsohowto.pdf | |
162 | (Chapter 3. Maintaining APIs and ABIs). |