1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 =============== 3 ===============
4 libbpf Overview 4 libbpf Overview
5 =============== 5 ===============
6 6
7 libbpf is a C-based library containing a BPF l 7 libbpf is a C-based library containing a BPF loader that takes compiled BPF
8 object files and prepares and loads them into 8 object files and prepares and loads them into the Linux kernel. libbpf takes the
9 heavy lifting of loading, verifying, and attac 9 heavy lifting of loading, verifying, and attaching BPF programs to various
10 kernel hooks, allowing BPF application develop 10 kernel hooks, allowing BPF application developers to focus only on BPF program
11 correctness and performance. 11 correctness and performance.
12 12
13 The following are the high-level features supp 13 The following are the high-level features supported by libbpf:
14 14
15 * Provides high-level and low-level APIs for u 15 * Provides high-level and low-level APIs for user space programs to interact
16 with BPF programs. The low-level APIs wrap a 16 with BPF programs. The low-level APIs wrap all the bpf system call
17 functionality, which is useful when users ne 17 functionality, which is useful when users need more fine-grained control
18 over the interactions between user space and 18 over the interactions between user space and BPF programs.
19 * Provides overall support for the BPF object 19 * Provides overall support for the BPF object skeleton generated by bpftool.
20 The skeleton file simplifies the process for 20 The skeleton file simplifies the process for the user space programs to access
21 global variables and work with BPF programs. 21 global variables and work with BPF programs.
22 * Provides BPF-side APIS, including BPF helper 22 * Provides BPF-side APIS, including BPF helper definitions, BPF maps support,
23 and tracing helpers, allowing developers to 23 and tracing helpers, allowing developers to simplify BPF code writing.
24 * Supports BPF CO-RE mechanism, enabling BPF d 24 * Supports BPF CO-RE mechanism, enabling BPF developers to write portable
25 BPF programs that can be compiled once and r 25 BPF programs that can be compiled once and run across different kernel
26 versions. 26 versions.
27 27
28 This document will delve into the above concep 28 This document will delve into the above concepts in detail, providing a deeper
29 understanding of the capabilities and advantag 29 understanding of the capabilities and advantages of libbpf and how it can help
30 you develop BPF applications efficiently. 30 you develop BPF applications efficiently.
31 31
32 BPF App Lifecycle and libbpf APIs 32 BPF App Lifecycle and libbpf APIs
33 ================================== 33 ==================================
34 34
35 A BPF application consists of one or more BPF 35 A BPF application consists of one or more BPF programs (either cooperating or
36 completely independent), BPF maps, and global 36 completely independent), BPF maps, and global variables. The global
37 variables are shared between all BPF programs, 37 variables are shared between all BPF programs, which allows them to cooperate on
38 a common set of data. libbpf provides APIs tha 38 a common set of data. libbpf provides APIs that user space programs can use to
39 manipulate the BPF programs by triggering diff 39 manipulate the BPF programs by triggering different phases of a BPF application
40 lifecycle. 40 lifecycle.
41 41
42 The following section provides a brief overvie 42 The following section provides a brief overview of each phase in the BPF life
43 cycle: 43 cycle:
44 44
45 * **Open phase**: In this phase, libbpf parses 45 * **Open phase**: In this phase, libbpf parses the BPF
46 object file and discovers BPF maps, BPF prog 46 object file and discovers BPF maps, BPF programs, and global variables. After
47 a BPF app is opened, user space apps can mak 47 a BPF app is opened, user space apps can make additional adjustments
48 (setting BPF program types, if necessary; pr 48 (setting BPF program types, if necessary; pre-setting initial values for
49 global variables, etc.) before all the entit 49 global variables, etc.) before all the entities are created and loaded.
50 50
51 * **Load phase**: In the load phase, libbpf cr 51 * **Load phase**: In the load phase, libbpf creates BPF
52 maps, resolves various relocations, and veri 52 maps, resolves various relocations, and verifies and loads BPF programs into
53 the kernel. At this point, libbpf validates 53 the kernel. At this point, libbpf validates all the parts of a BPF application
54 and loads the BPF program into the kernel, b 54 and loads the BPF program into the kernel, but no BPF program has yet been
55 executed. After the load phase, it’s possi 55 executed. After the load phase, it’s possible to set up the initial BPF map
56 state without racing with the BPF program co 56 state without racing with the BPF program code execution.
57 57
58 * **Attachment phase**: In this phase, libbpf 58 * **Attachment phase**: In this phase, libbpf
59 attaches BPF programs to various BPF hook po 59 attaches BPF programs to various BPF hook points (e.g., tracepoints, kprobes,
60 cgroup hooks, network packet processing pipe 60 cgroup hooks, network packet processing pipeline, etc.). During this
61 phase, BPF programs perform useful work such 61 phase, BPF programs perform useful work such as processing
62 packets, or updating BPF maps and global var 62 packets, or updating BPF maps and global variables that can be read from user
63 space. 63 space.
64 64
65 * **Tear down phase**: In the tear down phase, 65 * **Tear down phase**: In the tear down phase,
66 libbpf detaches BPF programs and unloads the 66 libbpf detaches BPF programs and unloads them from the kernel. BPF maps are
67 destroyed, and all the resources used by the 67 destroyed, and all the resources used by the BPF app are freed.
68 68
69 BPF Object Skeleton File 69 BPF Object Skeleton File
70 ======================== 70 ========================
71 71
72 BPF skeleton is an alternative interface to li 72 BPF skeleton is an alternative interface to libbpf APIs for working with BPF
73 objects. Skeleton code abstract away generic l 73 objects. Skeleton code abstract away generic libbpf APIs to significantly
74 simplify code for manipulating BPF programs fr 74 simplify code for manipulating BPF programs from user space. Skeleton code
75 includes a bytecode representation of the BPF 75 includes a bytecode representation of the BPF object file, simplifying the
76 process of distributing your BPF code. With BP 76 process of distributing your BPF code. With BPF bytecode embedded, there are no
77 extra files to deploy along with your applicat 77 extra files to deploy along with your application binary.
78 78
79 You can generate the skeleton header file ``(. 79 You can generate the skeleton header file ``(.skel.h)`` for a specific object
80 file by passing the BPF object to the bpftool. 80 file by passing the BPF object to the bpftool. The generated BPF skeleton
81 provides the following custom functions that c 81 provides the following custom functions that correspond to the BPF lifecycle,
82 each of them prefixed with the specific object 82 each of them prefixed with the specific object name:
83 83
84 * ``<name>__open()`` – creates and opens BPF 84 * ``<name>__open()`` – creates and opens BPF application (``<name>`` stands for
85 the specific bpf object name) 85 the specific bpf object name)
86 * ``<name>__load()`` – instantiates, loads,a 86 * ``<name>__load()`` – instantiates, loads,and verifies BPF application parts
87 * ``<name>__attach()`` – attaches all auto-a 87 * ``<name>__attach()`` – attaches all auto-attachable BPF programs (it’s
88 optional, you can have more control by using 88 optional, you can have more control by using libbpf APIs directly)
89 * ``<name>__destroy()`` – detaches all BPF p 89 * ``<name>__destroy()`` – detaches all BPF programs and
90 frees up all used resources 90 frees up all used resources
91 91
92 Using the skeleton code is the recommended way 92 Using the skeleton code is the recommended way to work with bpf programs. Keep
93 in mind, BPF skeleton provides access to the u 93 in mind, BPF skeleton provides access to the underlying BPF object, so whatever
94 was possible to do with generic libbpf APIs is 94 was possible to do with generic libbpf APIs is still possible even when the BPF
95 skeleton is used. It's an additive convenience 95 skeleton is used. It's an additive convenience feature, with no syscalls, and no
96 cumbersome code. 96 cumbersome code.
97 97
98 Other Advantages of Using Skeleton File 98 Other Advantages of Using Skeleton File
99 --------------------------------------- 99 ---------------------------------------
100 100
101 * BPF skeleton provides an interface for user 101 * BPF skeleton provides an interface for user space programs to work with BPF
102 global variables. The skeleton code memory m 102 global variables. The skeleton code memory maps global variables as a struct
103 into user space. The struct interface allows 103 into user space. The struct interface allows user space programs to initialize
104 BPF programs before the BPF load phase and f 104 BPF programs before the BPF load phase and fetch and update data from user
105 space afterward. 105 space afterward.
106 106
107 * The ``skel.h`` file reflects the object file 107 * The ``skel.h`` file reflects the object file structure by listing out the
108 available maps, programs, etc. BPF skeleton 108 available maps, programs, etc. BPF skeleton provides direct access to all the
109 BPF maps and BPF programs as struct fields. 109 BPF maps and BPF programs as struct fields. This eliminates the need for
110 string-based lookups with ``bpf_object_find_ 110 string-based lookups with ``bpf_object_find_map_by_name()`` and
111 ``bpf_object_find_program_by_name()`` APIs, 111 ``bpf_object_find_program_by_name()`` APIs, reducing errors due to BPF source
112 code and user-space code getting out of sync 112 code and user-space code getting out of sync.
113 113
114 * The embedded bytecode representation of the 114 * The embedded bytecode representation of the object file ensures that the
115 skeleton and the BPF object file are always 115 skeleton and the BPF object file are always in sync.
116 116
117 BPF Helpers 117 BPF Helpers
118 =========== 118 ===========
119 119
120 libbpf provides BPF-side APIs that BPF program 120 libbpf provides BPF-side APIs that BPF programs can use to interact with the
121 system. The BPF helpers definition allows deve 121 system. The BPF helpers definition allows developers to use them in BPF code as
122 any other plain C function. For example, there 122 any other plain C function. For example, there are helper functions to print
123 debugging messages, get the time since the sys 123 debugging messages, get the time since the system was booted, interact with BPF
124 maps, manipulate network packets, etc. 124 maps, manipulate network packets, etc.
125 125
126 For a complete description of what the helpers 126 For a complete description of what the helpers do, the arguments they take, and
127 the return value, see the `bpf-helpers 127 the return value, see the `bpf-helpers
128 <https://man7.org/linux/man-pages/man7/bpf-hel 128 <https://man7.org/linux/man-pages/man7/bpf-helpers.7.html>`_ man page.
129 129
130 BPF CO-RE (Compile Once – Run Everywhere) 130 BPF CO-RE (Compile Once – Run Everywhere)
131 ========================================= 131 =========================================
132 132
133 BPF programs work in the kernel space and have 133 BPF programs work in the kernel space and have access to kernel memory and data
134 structures. One limitation that BPF applicatio 134 structures. One limitation that BPF applications come across is the lack of
135 portability across different kernel versions a 135 portability across different kernel versions and configurations. `BCC
136 <https://github.com/iovisor/bcc/>`_ is one of 136 <https://github.com/iovisor/bcc/>`_ is one of the solutions for BPF
137 portability. However, it comes with runtime ov 137 portability. However, it comes with runtime overhead and a large binary size
138 from embedding the compiler with the applicati 138 from embedding the compiler with the application.
139 139
140 libbpf steps up the BPF program portability by 140 libbpf steps up the BPF program portability by supporting the BPF CO-RE concept.
141 BPF CO-RE brings together BTF type information 141 BPF CO-RE brings together BTF type information, libbpf, and the compiler to
142 produce a single executable binary that you ca 142 produce a single executable binary that you can run on multiple kernel versions
143 and configurations. 143 and configurations.
144 144
145 To make BPF programs portable libbpf relies on 145 To make BPF programs portable libbpf relies on the BTF type information of the
146 running kernel. Kernel also exposes this self- 146 running kernel. Kernel also exposes this self-describing authoritative BTF
147 information through ``sysfs`` at ``/sys/kernel 147 information through ``sysfs`` at ``/sys/kernel/btf/vmlinux``.
148 148
149 You can generate the BTF information for the r 149 You can generate the BTF information for the running kernel with the following
150 command: 150 command:
151 151
152 :: 152 ::
153 153
154 $ bpftool btf dump file /sys/kernel/btf/vmli 154 $ bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h
155 155
156 The command generates a ``vmlinux.h`` header f 156 The command generates a ``vmlinux.h`` header file with all kernel types
157 (:doc:`BTF types <../btf>`) that the running k 157 (:doc:`BTF types <../btf>`) that the running kernel uses. Including
158 ``vmlinux.h`` in your BPF program eliminates d 158 ``vmlinux.h`` in your BPF program eliminates dependency on system-wide kernel
159 headers. 159 headers.
160 160
161 libbpf enables portability of BPF programs by 161 libbpf enables portability of BPF programs by looking at the BPF program’s
162 recorded BTF type and relocation information a 162 recorded BTF type and relocation information and matching them to BTF
163 information (vmlinux) provided by the running 163 information (vmlinux) provided by the running kernel. libbpf then resolves and
164 matches all the types and fields, and updates 164 matches all the types and fields, and updates necessary offsets and other
165 relocatable data to ensure that BPF program’ 165 relocatable data to ensure that BPF program’s logic functions correctly for a
166 specific kernel on the host. BPF CO-RE concept 166 specific kernel on the host. BPF CO-RE concept thus eliminates overhead
167 associated with BPF development and allows dev 167 associated with BPF development and allows developers to write portable BPF
168 applications without modifications and runtime 168 applications without modifications and runtime source code compilation on the
169 target machine. 169 target machine.
170 170
171 The following code snippet shows how to read t 171 The following code snippet shows how to read the parent field of a kernel
172 ``task_struct`` using BPF CO-RE and libbf. The 172 ``task_struct`` using BPF CO-RE and libbf. The basic helper to read a field in a
173 CO-RE relocatable manner is ``bpf_core_read(ds 173 CO-RE relocatable manner is ``bpf_core_read(dst, sz, src)``, which will read
174 ``sz`` bytes from the field referenced by ``sr 174 ``sz`` bytes from the field referenced by ``src`` into the memory pointed to by
175 ``dst``. 175 ``dst``.
176 176
177 .. code-block:: C 177 .. code-block:: C
178 :emphasize-lines: 6 178 :emphasize-lines: 6
179 179
180 //... 180 //...
181 struct task_struct *task = (void *)bpf_get 181 struct task_struct *task = (void *)bpf_get_current_task();
182 struct task_struct *parent_task; 182 struct task_struct *parent_task;
183 int err; 183 int err;
184 184
185 err = bpf_core_read(&parent_task, sizeof(v 185 err = bpf_core_read(&parent_task, sizeof(void *), &task->parent);
186 if (err) { 186 if (err) {
187 /* handle error */ 187 /* handle error */
188 } 188 }
189 189
190 /* parent_task contains the value of task- 190 /* parent_task contains the value of task->parent pointer */
191 191
192 In the code snippet, we first get a pointer to 192 In the code snippet, we first get a pointer to the current ``task_struct`` using
193 ``bpf_get_current_task()``. We then use ``bpf 193 ``bpf_get_current_task()``. We then use ``bpf_core_read()`` to read the parent
194 field of task struct into the ``parent_task`` 194 field of task struct into the ``parent_task`` variable. ``bpf_core_read()`` is
195 just like ``bpf_probe_read_kernel()`` BPF help 195 just like ``bpf_probe_read_kernel()`` BPF helper, except it records information
196 about the field that should be relocated on th 196 about the field that should be relocated on the target kernel. i.e, if the
197 ``parent`` field gets shifted to a different o 197 ``parent`` field gets shifted to a different offset within
198 ``struct task_struct`` due to some new field a 198 ``struct task_struct`` due to some new field added in front of it, libbpf will
199 automatically adjust the actual offset to the 199 automatically adjust the actual offset to the proper value.
200 200
201 Getting Started with libbpf 201 Getting Started with libbpf
202 =========================== 202 ===========================
203 203
204 Check out the `libbpf-bootstrap <https://githu 204 Check out the `libbpf-bootstrap <https://github.com/libbpf/libbpf-bootstrap>`_
205 repository with simple examples of using libbp 205 repository with simple examples of using libbpf to build various BPF
206 applications. 206 applications.
207 207
208 See also `libbpf API documentation 208 See also `libbpf API documentation
209 <https://libbpf.readthedocs.io/en/latest/api.h 209 <https://libbpf.readthedocs.io/en/latest/api.html>`_.
210 210
211 libbpf and Rust 211 libbpf and Rust
212 =============== 212 ===============
213 213
214 If you are building BPF applications in Rust, 214 If you are building BPF applications in Rust, it is recommended to use the
215 `Libbpf-rs <https://github.com/libbpf/libbpf-r 215 `Libbpf-rs <https://github.com/libbpf/libbpf-rs>`_ library instead of bindgen
216 bindings directly to libbpf. Libbpf-rs wraps l 216 bindings directly to libbpf. Libbpf-rs wraps libbpf functionality in
217 Rust-idiomatic interfaces and provides libbpf- 217 Rust-idiomatic interfaces and provides libbpf-cargo plugin to handle BPF code
218 compilation and skeleton generation. Using Lib 218 compilation and skeleton generation. Using Libbpf-rs will make building user
219 space part of the BPF application easier. Note 219 space part of the BPF application easier. Note that the BPF program themselves
220 must still be written in plain C. 220 must still be written in plain C.
221 221
222 libbpf logging 222 libbpf logging
223 ============== 223 ==============
224 224
225 By default, libbpf logs informational and warn 225 By default, libbpf logs informational and warning messages to stderr. The
226 verbosity of these messages can be controlled 226 verbosity of these messages can be controlled by setting the environment
227 variable LIBBPF_LOG_LEVEL to either warn, info 227 variable LIBBPF_LOG_LEVEL to either warn, info, or debug. A custom log
228 callback can be set using ``libbpf_set_print() 228 callback can be set using ``libbpf_set_print()``.
229 229
230 Additional Documentation 230 Additional Documentation
231 ======================== 231 ========================
232 232
233 * `Program types and ELF Sections <https://lib 233 * `Program types and ELF Sections <https://libbpf.readthedocs.io/en/latest/program_types.html>`_
234 * `API naming convention <https://libbpf.readt 234 * `API naming convention <https://libbpf.readthedocs.io/en/latest/libbpf_naming_convention.html>`_
235 * `Building libbpf <https://libbpf.readthedocs 235 * `Building libbpf <https://libbpf.readthedocs.io/en/latest/libbpf_build.html>`_
236 * `API documentation Convention <https://libbp 236 * `API documentation Convention <https://libbpf.readthedocs.io/en/latest/libbpf_naming_convention.html#api-documentation-convention>`_
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.