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