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 | |
12 | following prefixes: ``bpf_``, ``btf_``, ``libbpf_``. | |
13 | ||
14 | System call wrappers | |
15 | -------------------- | |
16 | ||
17 | System call wrappers are simple wrappers for commands supported by | |
18 | sys_bpf system call. These wrappers should go to ``bpf.h`` header file | |
19 | and map one-on-one to corresponding commands. | |
20 | ||
21 | For example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM`` | |
22 | command of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc. | |
23 | ||
24 | Objects | |
25 | ------- | |
26 | ||
27 | Another class of types and functions provided by libbpf API is "objects" | |
28 | and functions to work with them. Objects are high-level abstractions | |
29 | such as BPF program or BPF map. They're represented by corresponding | |
30 | structures such as ``struct bpf_object``, ``struct bpf_program``, | |
31 | ``struct bpf_map``, etc. | |
32 | ||
33 | Structures are forward declared and access to their fields should be | |
34 | provided via corresponding getters and setters rather than directly. | |
35 | ||
36 | These objects are associated with corresponding parts of ELF object that | |
37 | contains compiled BPF programs. | |
38 | ||
39 | For example ``struct bpf_object`` represents ELF object itself created | |
40 | from an ELF file or from a buffer, ``struct bpf_program`` represents a | |
41 | program in ELF object and ``struct bpf_map`` is a map. | |
42 | ||
43 | Functions that work with an object have names built from object name, | |
44 | double underscore and part that describes function purpose. | |
45 | ||
46 | For example ``bpf_object__open`` consists of the name of corresponding | |
47 | object, ``bpf_object``, double underscore and ``open`` that defines the | |
48 | purpose of the function to open ELF file and create ``bpf_object`` from | |
49 | it. | |
50 | ||
51 | Another example: ``bpf_program__load`` is named for corresponding | |
52 | object, ``bpf_program``, that is separated from other part of the name | |
53 | by double underscore. | |
54 | ||
55 | All objects and corresponding functions other than BTF related should go | |
56 | to ``libbpf.h``. BTF types and functions should go to ``btf.h``. | |
57 | ||
58 | Auxiliary functions | |
59 | ------------------- | |
60 | ||
61 | Auxiliary functions and types that don't fit well in any of categories | |
62 | described above should have ``libbpf_`` prefix, e.g. | |
63 | ``libbpf_get_error`` or ``libbpf_prog_type_by_name``. | |
64 | ||
65 | libbpf ABI | |
66 | ========== | |
67 | ||
68 | libbpf can be both linked statically or used as DSO. To avoid possible | |
69 | conflicts with other libraries an application is linked with, all | |
70 | non-static libbpf symbols should have one of the prefixes mentioned in | |
71 | API documentation above. See API naming convention to choose the right | |
72 | name for a new symbol. | |
73 | ||
74 | Symbol visibility | |
75 | ----------------- | |
76 | ||
77 | libbpf follow the model when all global symbols have visibility "hidden" | |
78 | by default and to make a symbol visible it has to be explicitly | |
79 | attributed 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 | ||
85 | This prevents from accidentally exporting a symbol, that is not supposed | |
86 | to be a part of ABI what, in turn, improves both libbpf developer- and | |
87 | user-experiences. | |
88 | ||
89 | ABI versionning | |
90 | --------------- | |
91 | ||
92 | To make future ABI extensions possible libbpf ABI is versioned. | |
93 | Versioning is implemented by ``libbpf.map`` version script that is | |
94 | passed to linker. | |
95 | ||
96 | Version name is ``LIBBPF_`` prefix + three-component numeric version, | |
97 | starting from ``0.0.1``. | |
98 | ||
99 | Every time ABI is being changed, e.g. because a new symbol is added or | |
100 | semantic of existing symbol is changed, ABI version should be bumped. | |
101 | ||
102 | For 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 | ||
132 | Format of version script and ways to handle ABI changes, including | |
133 | incompatible ones, described in details in [1]. | |
134 | ||
135 | Links | |
136 | ===== | |
137 | ||
138 | [1] https://www.akkadia.org/drepper/dsohowto.pdf | |
139 | (Chapter 3. Maintaining APIs and ABIs). |