װsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget./translations/zh_CN/bpf/libbpf/libbpf_overviewmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/zh_TW/bpf/libbpf/libbpf_overviewmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/it_IT/bpf/libbpf/libbpf_overviewmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/ja_JP/bpf/libbpf/libbpf_overviewmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/ko_KR/bpf/libbpf/libbpf_overviewmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/pt_BR/bpf/libbpf/libbpf_overviewmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget./translations/sp_SP/bpf/libbpf/libbpf_overviewmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhH/var/lib/git/docbuild/linux/Documentation/bpf/libbpf/libbpf_overview.rsthKubhsection)}(hhh](htitle)}(hlibbpf Overviewh]hlibbpf Overview}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXSlibbpf is a C-based library containing a BPF loader that takes compiled BPF object files and prepares and loads them into the Linux kernel. libbpf takes the heavy lifting of loading, verifying, and attaching BPF programs to various kernel hooks, allowing BPF application developers to focus only on BPF program correctness and performance.h]hXSlibbpf is a C-based library containing a BPF loader that takes compiled BPF object files and prepares and loads them into the Linux kernel. libbpf takes the heavy lifting of loading, verifying, and attaching BPF programs to various kernel hooks, allowing BPF application developers to focus only on BPF program correctness and performance.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h>The following are the high-level features supported by libbpf:h]h>The following are the high-level features supported by libbpf:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh bullet_list)}(hhh](h list_item)}(hXProvides high-level and low-level APIs for user space programs to interact with BPF programs. The low-level APIs wrap all the bpf system call functionality, which is useful when users need more fine-grained control over the interactions between user space and BPF programs.h]h)}(hXProvides high-level and low-level APIs for user space programs to interact with BPF programs. The low-level APIs wrap all the bpf system call functionality, which is useful when users need more fine-grained control over the interactions between user space and BPF programs.h]hXProvides high-level and low-level APIs for user space programs to interact with BPF programs. The low-level APIs wrap all the bpf system call functionality, which is useful when users need more fine-grained control over the interactions between user space and BPF programs.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubj)}(hProvides overall support for the BPF object skeleton generated by bpftool. The skeleton file simplifies the process for the user space programs to access global variables and work with BPF programs.h]h)}(hProvides overall support for the BPF object skeleton generated by bpftool. The skeleton file simplifies the process for the user space programs to access global variables and work with BPF programs.h]hProvides overall support for the BPF object skeleton generated by bpftool. The skeleton file simplifies the process for the user space programs to access global variables and work with BPF programs.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubj)}(hProvides BPF-side APIS, including BPF helper definitions, BPF maps support, and tracing helpers, allowing developers to simplify BPF code writing.h]h)}(hProvides BPF-side APIS, including BPF helper definitions, BPF maps support, and tracing helpers, allowing developers to simplify BPF code writing.h]hProvides BPF-side APIS, including BPF helper definitions, BPF maps support, and tracing helpers, allowing developers to simplify BPF code writing.}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj2ubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubj)}(hSupports BPF CO-RE mechanism, enabling BPF developers to write portable BPF programs that can be compiled once and run across different kernel versions. h]h)}(hSupports BPF CO-RE mechanism, enabling BPF developers to write portable BPF programs that can be compiled once and run across different kernel versions.h]hSupports BPF CO-RE mechanism, enabling BPF developers to write portable BPF programs that can be compiled once and run across different kernel versions.}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjJubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubeh}(h]h ]h"]h$]h&]bullet*uh1hhhhKhhhhubh)}(hThis document will delve into the above concepts in detail, providing a deeper understanding of the capabilities and advantages of libbpf and how it can help you develop BPF applications efficiently.h]hThis document will delve into the above concepts in detail, providing a deeper understanding of the capabilities and advantages of libbpf and how it can help you develop BPF applications efficiently.}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h!BPF App Lifecycle and libbpf APIsh]h!BPF App Lifecycle and libbpf APIs}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjxhhhhhK!ubh)}(hXA BPF application consists of one or more BPF programs (either cooperating or completely independent), BPF maps, and global variables. The global variables are shared between all BPF programs, which allows them to cooperate on a common set of data. libbpf provides APIs that user space programs can use to manipulate the BPF programs by triggering different phases of a BPF application lifecycle.h]hXA BPF application consists of one or more BPF programs (either cooperating or completely independent), BPF maps, and global variables. The global variables are shared between all BPF programs, which allows them to cooperate on a common set of data. libbpf provides APIs that user space programs can use to manipulate the BPF programs by triggering different phases of a BPF application lifecycle.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hjxhhubh)}(hTThe following section provides a brief overview of each phase in the BPF life cycle:h]hTThe following section provides a brief overview of each phase in the BPF life cycle:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK*hjxhhubh)}(hhh](j)}(hXY**Open phase**: In this phase, libbpf parses the BPF object file and discovers BPF maps, BPF programs, and global variables. After a BPF app is opened, user space apps can make additional adjustments (setting BPF program types, if necessary; pre-setting initial values for global variables, etc.) before all the entities are created and loaded. h]h)}(hXX**Open phase**: In this phase, libbpf parses the BPF object file and discovers BPF maps, BPF programs, and global variables. After a BPF app is opened, user space apps can make additional adjustments (setting BPF program types, if necessary; pre-setting initial values for global variables, etc.) before all the entities are created and loaded.h](hstrong)}(h**Open phase**h]h Open phase}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhXJ: In this phase, libbpf parses the BPF object file and discovers BPF maps, BPF programs, and global variables. After a BPF app is opened, user space apps can make additional adjustments (setting BPF program types, if necessary; pre-setting initial values for global variables, etc.) before all the entities are created and loaded.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK-hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX**Load phase**: In the load phase, libbpf creates BPF maps, resolves various relocations, and verifies and loads BPF programs into the kernel. At this point, libbpf validates all the parts of a BPF application and loads the BPF program into the kernel, but no BPF program has yet been executed. After the load phase, it’s possible to set up the initial BPF map state without racing with the BPF program code execution. h]h)}(hX**Load phase**: In the load phase, libbpf creates BPF maps, resolves various relocations, and verifies and loads BPF programs into the kernel. At this point, libbpf validates all the parts of a BPF application and loads the BPF program into the kernel, but no BPF program has yet been executed. After the load phase, it’s possible to set up the initial BPF map state without racing with the BPF program code execution.h](j)}(h**Load phase**h]h Load phase}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX: In the load phase, libbpf creates BPF maps, resolves various relocations, and verifies and loads BPF programs into the kernel. At this point, libbpf validates all the parts of a BPF application and loads the BPF program into the kernel, but no BPF program has yet been executed. After the load phase, it’s possible to set up the initial BPF map state without racing with the BPF program code execution.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK3hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXO**Attachment phase**: In this phase, libbpf attaches BPF programs to various BPF hook points (e.g., tracepoints, kprobes, cgroup hooks, network packet processing pipeline, etc.). During this phase, BPF programs perform useful work such as processing packets, or updating BPF maps and global variables that can be read from user space. h]h)}(hXN**Attachment phase**: In this phase, libbpf attaches BPF programs to various BPF hook points (e.g., tracepoints, kprobes, cgroup hooks, network packet processing pipeline, etc.). During this phase, BPF programs perform useful work such as processing packets, or updating BPF maps and global variables that can be read from user space.h](j)}(h**Attachment phase**h]hAttachment phase}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX:: In this phase, libbpf attaches BPF programs to various BPF hook points (e.g., tracepoints, kprobes, cgroup hooks, network packet processing pipeline, etc.). During this phase, BPF programs perform useful work such as processing packets, or updating BPF maps and global variables that can be read from user space.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK:hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h**Tear down phase**: In the tear down phase, libbpf detaches BPF programs and unloads them from the kernel. BPF maps are destroyed, and all the resources used by the BPF app are freed. h]h)}(h**Tear down phase**: In the tear down phase, libbpf detaches BPF programs and unloads them from the kernel. BPF maps are destroyed, and all the resources used by the BPF app are freed.h](j)}(h**Tear down phase**h]hTear down phase}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh: In the tear down phase, libbpf detaches BPF programs and unloads them from the kernel. BPF maps are destroyed, and all the resources used by the BPF app are freed.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKAhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jhjiuh1hhhhK-hjxhhubeh}(h]!bpf-app-lifecycle-and-libbpf-apisah ]h"]!bpf app lifecycle and libbpf apisah$]h&]uh1hhhhhhhhK!ubh)}(hhh](h)}(hBPF Object Skeleton Fileh]hBPF Object Skeleton File}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhjPhhhhhKFubh)}(hXBPF skeleton is an alternative interface to libbpf APIs for working with BPF objects. Skeleton code abstract away generic libbpf APIs to significantly simplify code for manipulating BPF programs from user space. Skeleton code includes a bytecode representation of the BPF object file, simplifying the process of distributing your BPF code. With BPF bytecode embedded, there are no extra files to deploy along with your application binary.h]hXBPF skeleton is an alternative interface to libbpf APIs for working with BPF objects. Skeleton code abstract away generic libbpf APIs to significantly simplify code for manipulating BPF programs from user space. Skeleton code includes a bytecode representation of the BPF object file, simplifying the process of distributing your BPF code. With BPF bytecode embedded, there are no extra files to deploy along with your application binary.}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjPhhubh)}(hXYou can generate the skeleton header file ``(.skel.h)`` for a specific object file by passing the BPF object to the bpftool. The generated BPF skeleton provides the following custom functions that correspond to the BPF lifecycle, each of them prefixed with the specific object name:h](h*You can generate the skeleton header file }(hjohhhNhNubhliteral)}(h ``(.skel.h)``h]h (.skel.h)}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjoubh for a specific object file by passing the BPF object to the bpftool. The generated BPF skeleton provides the following custom functions that correspond to the BPF lifecycle, each of them prefixed with the specific object name:}(hjohhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKOhjPhhubh)}(hhh](j)}(hm``__open()`` – creates and opens BPF application (```` stands for the specific bpf object name)h]h)}(hm``__open()`` – creates and opens BPF application (```` stands for the specific bpf object name)h](jx)}(h``__open()``h]h__open()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh( – creates and opens BPF application (}(hjhhhNhNubjx)}(h ````h]h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh) stands for the specific bpf object name)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKThjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hM``__load()`` – instantiates, loads,and verifies BPF application partsh]h)}(hjh](jx)}(h``__load()``h]h__load()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh; – instantiates, loads,and verifies BPF application parts}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKVhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``__attach()`` – attaches all auto-attachable BPF programs (it’s optional, you can have more control by using libbpf APIs directly)h]h)}(h``__attach()`` – attaches all auto-attachable BPF programs (it’s optional, you can have more control by using libbpf APIs directly)h](jx)}(h``__attach()``h]h__attach()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubhy – attaches all auto-attachable BPF programs (it’s optional, you can have more control by using libbpf APIs directly)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKWhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hT``__destroy()`` – detaches all BPF programs and frees up all used resources h]h)}(hS``__destroy()`` – detaches all BPF programs and frees up all used resourcesh](jx)}(h``__destroy()``h]h__destroy()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh> – detaches all BPF programs and frees up all used resources}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKYhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jhjiuh1hhhhKThjPhhubh)}(hXPUsing the skeleton code is the recommended way to work with bpf programs. Keep in mind, BPF skeleton provides access to the underlying BPF object, so whatever was possible to do with generic libbpf APIs is still possible even when the BPF skeleton is used. It's an additive convenience feature, with no syscalls, and no cumbersome code.h]hXRUsing the skeleton code is the recommended way to work with bpf programs. Keep in mind, BPF skeleton provides access to the underlying BPF object, so whatever was possible to do with generic libbpf APIs is still possible even when the BPF skeleton is used. It’s an additive convenience feature, with no syscalls, and no cumbersome code.}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hjPhhubh)}(hhh](h)}(h'Other Advantages of Using Skeleton Fileh]h'Other Advantages of Using Skeleton File}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjQhhhhhKcubh)}(hhh](j)}(hXDBPF skeleton provides an interface for user space programs to work with BPF global variables. The skeleton code memory maps global variables as a struct into user space. The struct interface allows user space programs to initialize BPF programs before the BPF load phase and fetch and update data from user space afterward. h]h)}(hXCBPF skeleton provides an interface for user space programs to work with BPF global variables. The skeleton code memory maps global variables as a struct into user space. The struct interface allows user space programs to initialize BPF programs before the BPF load phase and fetch and update data from user space afterward.h]hXCBPF skeleton provides an interface for user space programs to work with BPF global variables. The skeleton code memory maps global variables as a struct into user space. The struct interface allows user space programs to initialize BPF programs before the BPF load phase and fetch and update data from user space afterward.}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKehjeubah}(h]h ]h"]h$]h&]uh1jhjbhhhhhNubj)}(hXThe ``skel.h`` file reflects the object file structure by listing out the available maps, programs, etc. BPF skeleton provides direct access to all the BPF maps and BPF programs as struct fields. This eliminates the need for string-based lookups with ``bpf_object_find_map_by_name()`` and ``bpf_object_find_program_by_name()`` APIs, reducing errors due to BPF source code and user-space code getting out of sync. h]h)}(hXThe ``skel.h`` file reflects the object file structure by listing out the available maps, programs, etc. BPF skeleton provides direct access to all the BPF maps and BPF programs as struct fields. This eliminates the need for string-based lookups with ``bpf_object_find_map_by_name()`` and ``bpf_object_find_program_by_name()`` APIs, reducing errors due to BPF source code and user-space code getting out of sync.h](hThe }(hjhhhNhNubjx)}(h ``skel.h``h]hskel.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh file reflects the object file structure by listing out the available maps, programs, etc. BPF skeleton provides direct access to all the BPF maps and BPF programs as struct fields. This eliminates the need for string-based lookups with }(hjhhhNhNubjx)}(h!``bpf_object_find_map_by_name()``h]hbpf_object_find_map_by_name()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh and }(hjhhhNhNubjx)}(h%``bpf_object_find_program_by_name()``h]h!bpf_object_find_program_by_name()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubhV APIs, reducing errors due to BPF source code and user-space code getting out of sync.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKkhj}ubah}(h]h ]h"]h$]h&]uh1jhjbhhhhhNubj)}(h~The embedded bytecode representation of the object file ensures that the skeleton and the BPF object file are always in sync. h]h)}(h}The embedded bytecode representation of the object file ensures that the skeleton and the BPF object file are always in sync.h]h}The embedded bytecode representation of the object file ensures that the skeleton and the BPF object file are always in sync.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKrhjubah}(h]h ]h"]h$]h&]uh1jhjbhhhhhNubeh}(h]h ]h"]h$]h&]jhjiuh1hhhhKehjQhhubeh}(h]'other-advantages-of-using-skeleton-fileah ]h"]'other advantages of using skeleton fileah$]h&]uh1hhjPhhhhhKcubeh}(h]bpf-object-skeleton-fileah ]h"]bpf object skeleton fileah$]h&]uh1hhhhhhhhKFubh)}(hhh](h)}(h BPF Helpersh]h BPF Helpers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKvubh)}(hX`libbpf provides BPF-side APIs that BPF programs can use to interact with the system. The BPF helpers definition allows developers to use them in BPF code as any other plain C function. For example, there are helper functions to print debugging messages, get the time since the system was booted, interact with BPF maps, manipulate network packets, etc.h]hX`libbpf provides BPF-side APIs that BPF programs can use to interact with the system. The BPF helpers definition allows developers to use them in BPF code as any other plain C function. For example, there are helper functions to print debugging messages, get the time since the system was booted, interact with BPF maps, manipulate network packets, etc.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKxhjhhubh)}(hFor a complete description of what the helpers do, the arguments they take, and the return value, see the `bpf-helpers `_ man page.h](hjFor a complete description of what the helpers do, the arguments they take, and the return value, see the }(hjhhhNhNubh reference)}(hI`bpf-helpers `_h]h bpf-helpers}(hj"hhhNhNubah}(h]h ]h"]h$]h&]name bpf-helpersrefuri8https://man7.org/linux/man-pages/man7/bpf-helpers.7.htmluh1j hjubhtarget)}(h; h]h}(h]id1ah ]h"] bpf-helpersah$]h&]refurij3uh1j4 referencedKhjubh man page.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK~hjhhubeh}(h] bpf-helpersah ]h"] bpf helpersah$]h&]uh1hhhhhhhhKvubh)}(hhh](h)}(h+BPF CO-RE (Compile Once – Run Everywhere)h]h+BPF CO-RE (Compile Once – Run Everywhere)}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjVhhhhhKubh)}(hXBPF programs work in the kernel space and have access to kernel memory and data structures. One limitation that BPF applications come across is the lack of portability across different kernel versions and configurations. `BCC `_ is one of the solutions for BPF portability. However, it comes with runtime overhead and a large binary size from embedding the compiler with the application.h](hBPF programs work in the kernel space and have access to kernel memory and data structures. One limitation that BPF applications come across is the lack of portability across different kernel versions and configurations. }(hjghhhNhNubj!)}(h(`BCC `_h]hBCC}(hjohhhNhNubah}(h]h ]h"]h$]h&]nameBCCj2https://github.com/iovisor/bcc/uh1j hjgubj5)}(h" h]h}(h]bccah ]h"]bccah$]h&]refurijuh1j4jCKhjgubh is one of the solutions for BPF portability. However, it comes with runtime overhead and a large binary size from embedding the compiler with the application.}(hjghhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubh)}(hXlibbpf steps up the BPF program portability by supporting the BPF CO-RE concept. BPF CO-RE brings together BTF type information, libbpf, and the compiler to produce a single executable binary that you can run on multiple kernel versions and configurations.h]hXlibbpf steps up the BPF program portability by supporting the BPF CO-RE concept. BPF CO-RE brings together BTF type information, libbpf, and the compiler to produce a single executable binary that you can run on multiple kernel versions and configurations.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubh)}(hTo make BPF programs portable libbpf relies on the BTF type information of the running kernel. Kernel also exposes this self-describing authoritative BTF information through ``sysfs`` at ``/sys/kernel/btf/vmlinux``.h](hTo make BPF programs portable libbpf relies on the BTF type information of the running kernel. Kernel also exposes this self-describing authoritative BTF information through }(hjhhhNhNubjx)}(h ``sysfs``h]hsysfs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh at }(hjhhhNhNubjx)}(h``/sys/kernel/btf/vmlinux``h]h/sys/kernel/btf/vmlinux}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubh)}(hWYou can generate the BTF information for the running kernel with the following command:h]hWYou can generate the BTF information for the running kernel with the following command:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubh literal_block)}(hD$ bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.hh]hD$ bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjVhhubh)}(hThe command generates a ``vmlinux.h`` header file with all kernel types (:doc:`BTF types <../btf>`) that the running kernel uses. Including ``vmlinux.h`` in your BPF program eliminates dependency on system-wide kernel headers.h](hThe command generates a }(hjhhhNhNubjx)}(h ``vmlinux.h``h]h vmlinux.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh$ header file with all kernel types (}(hjhhhNhNubh)}(h:doc:`BTF types <../btf>`h]hinline)}(hjh]h BTF types}(hjhhhNhNubah}(h]h ](xrefstdstd-doceh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocbpf/libbpf/libbpf_overview refdomainj reftypedoc refexplicitrefwarn reftarget../btfuh1hhhhKhjubh*) that the running kernel uses. Including }(hjhhhNhNubjx)}(h ``vmlinux.h``h]h vmlinux.h}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubhI in your BPF program eliminates dependency on system-wide kernel headers.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubh)}(hXmlibbpf enables portability of BPF programs by looking at the BPF program’s recorded BTF type and relocation information and matching them to BTF information (vmlinux) provided by the running kernel. libbpf then resolves and matches all the types and fields, and updates necessary offsets and other relocatable data to ensure that BPF program’s logic functions correctly for a specific kernel on the host. BPF CO-RE concept thus eliminates overhead associated with BPF development and allows developers to write portable BPF applications without modifications and runtime source code compilation on the target machine.h]hXmlibbpf enables portability of BPF programs by looking at the BPF program’s recorded BTF type and relocation information and matching them to BTF information (vmlinux) provided by the running kernel. libbpf then resolves and matches all the types and fields, and updates necessary offsets and other relocatable data to ensure that BPF program’s logic functions correctly for a specific kernel on the host. BPF CO-RE concept thus eliminates overhead associated with BPF development and allows developers to write portable BPF applications without modifications and runtime source code compilation on the target machine.}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubh)}(hX@The following code snippet shows how to read the parent field of a kernel ``task_struct`` using BPF CO-RE and libbf. The basic helper to read a field in a CO-RE relocatable manner is ``bpf_core_read(dst, sz, src)``, which will read ``sz`` bytes from the field referenced by ``src`` into the memory pointed to by ``dst``.h](hJThe following code snippet shows how to read the parent field of a kernel }(hj^hhhNhNubjx)}(h``task_struct``h]h task_struct}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhj^ubh^ using BPF CO-RE and libbf. The basic helper to read a field in a CO-RE relocatable manner is }(hj^hhhNhNubjx)}(h``bpf_core_read(dst, sz, src)``h]hbpf_core_read(dst, sz, src)}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhj^ubh, which will read }(hj^hhhNhNubjx)}(h``sz``h]hsz}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhj^ubh$ bytes from the field referenced by }(hj^hhhNhNubjx)}(h``src``h]hsrc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhj^ubh into the memory pointed to by }(hj^hhhNhNubjx)}(h``dst``h]hdst}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhj^ubh.}(hj^hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubj)}(hX //... struct task_struct *task = (void *)bpf_get_current_task(); struct task_struct *parent_task; int err; err = bpf_core_read(&parent_task, sizeof(void *), &task->parent); if (err) { /* handle error */ } /* parent_task contains the value of task->parent pointer */h]hX //... struct task_struct *task = (void *)bpf_get_current_task(); struct task_struct *parent_task; int err; err = bpf_core_read(&parent_task, sizeof(void *), &task->parent); if (err) { /* handle error */ } /* parent_task contains the value of task->parent pointer */}hjsbah}(h]h ]h"]h$]h&]hhƌforcelanguageChighlight_args}hl_lines]Kasuh1jhhhKhjVhhubh)}(hXPIn the code snippet, we first get a pointer to the current ``task_struct`` using ``bpf_get_current_task()``. We then use ``bpf_core_read()`` to read the parent field of task struct into the ``parent_task`` variable. ``bpf_core_read()`` is just like ``bpf_probe_read_kernel()`` BPF helper, except it records information about the field that should be relocated on the target kernel. i.e, if the ``parent`` field gets shifted to a different offset within ``struct task_struct`` due to some new field added in front of it, libbpf will automatically adjust the actual offset to the proper value.h](h;In the code snippet, we first get a pointer to the current }(hjhhhNhNubjx)}(h``task_struct``h]h task_struct}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh using }(hjhhhNhNubjx)}(h``bpf_get_current_task()``h]hbpf_get_current_task()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh. We then use }(hjhhhNhNubjx)}(h``bpf_core_read()``h]hbpf_core_read()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh2 to read the parent field of task struct into the }(hjhhhNhNubjx)}(h``parent_task``h]h parent_task}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh variable. }(hjhhhNhNubjx)}(h``bpf_core_read()``h]hbpf_core_read()}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh is just like }(hjhhhNhNubjx)}(h``bpf_probe_read_kernel()``h]hbpf_probe_read_kernel()}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubhv BPF helper, except it records information about the field that should be relocated on the target kernel. i.e, if the }(hjhhhNhNubjx)}(h ``parent``h]hparent}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubh1 field gets shifted to a different offset within }(hjhhhNhNubjx)}(h``struct task_struct``h]hstruct task_struct}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjubht due to some new field added in front of it, libbpf will automatically adjust the actual offset to the proper value.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubeh}(h]%bpf-co-re-compile-once-run-everywhereah ]h"]+bpf co-re (compile once – run everywhere)ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hGetting Started with libbpfh]hGetting Started with libbpf}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hCheck out the `libbpf-bootstrap `_ repository with simple examples of using libbpf to build various BPF applications.h](hCheck out the }(hjhhhNhNubj!)}(h@`libbpf-bootstrap `_h]hlibbpf-bootstrap}(hjhhhNhNubah}(h]h ]h"]h$]h&]namelibbpf-bootstrapj2*https://github.com/libbpf/libbpf-bootstrapuh1j hjubj5)}(h- h]h}(h]libbpf-bootstrapah ]h"]libbpf-bootstrapah$]h&]refurijuh1j4jCKhjubhS repository with simple examples of using libbpf to build various BPF applications.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXSee also `libbpf API documentation `_.h](h See also }(hjhhhNhNubj!)}(hN`libbpf API documentation `_h]hlibbpf API documentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]namelibbpf API documentationj20https://libbpf.readthedocs.io/en/latest/api.htmluh1j hjubj5)}(h3 h]h}(h]libbpf-api-documentationah ]h"]libbpf api documentationah$]h&]refurijuh1j4jCKhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]getting-started-with-libbpfah ]h"]getting started with libbpfah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hlibbpf and Rusth]hlibbpf and Rust}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXIf you are building BPF applications in Rust, it is recommended to use the `Libbpf-rs `_ library instead of bindgen bindings directly to libbpf. Libbpf-rs wraps libbpf functionality in Rust-idiomatic interfaces and provides libbpf-cargo plugin to handle BPF code compilation and skeleton generation. Using Libbpf-rs will make building user space part of the BPF application easier. Note that the BPF program themselves must still be written in plain C.h](hKIf you are building BPF applications in Rust, it is recommended to use the }(hj hhhNhNubj!)}(h2`Libbpf-rs `_h]h Libbpf-rs}(hjhhhNhNubah}(h]h ]h"]h$]h&]name Libbpf-rsj2#https://github.com/libbpf/libbpf-rsuh1j hj ubj5)}(h& h]h}(h] libbpf-rsah ]h"] libbpf-rsah$]h&]refurij#uh1j4jCKhj ubhXl library instead of bindgen bindings directly to libbpf. Libbpf-rs wraps libbpf functionality in Rust-idiomatic interfaces and provides libbpf-cargo plugin to handle BPF code compilation and skeleton generation. Using Libbpf-rs will make building user space part of the BPF application easier. Note that the BPF program themselves must still be written in plain C.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]libbpf-and-rustah ]h"]libbpf and rustah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hlibbpf loggingh]hlibbpf logging}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjChhhhhKubh)}(hX By default, libbpf logs informational and warning messages to stderr. The verbosity of these messages can be controlled by setting the environment variable LIBBPF_LOG_LEVEL to either warn, info, or debug. A custom log callback can be set using ``libbpf_set_print()``.h](hBy default, libbpf logs informational and warning messages to stderr. The verbosity of these messages can be controlled by setting the environment variable LIBBPF_LOG_LEVEL to either warn, info, or debug. A custom log callback can be set using }(hjThhhNhNubjx)}(h``libbpf_set_print()``h]hlibbpf_set_print()}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1jwhjTubh.}(hjThhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjChhubeh}(h]libbpf-loggingah ]h"]libbpf loggingah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hAdditional Documentationh]hAdditional Documentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj|hhhhhKubh)}(hhh](j)}(h^`Program types and ELF Sections `_h]h)}(hjh](j!)}(hjh]hProgram types and ELF Sections}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameProgram types and ELF Sectionsj2:https://libbpf.readthedocs.io/en/latest/program_types.htmluh1j hjubj5)}(h= h]h}(h]program-types-and-elf-sectionsah ]h"]program types and elf sectionsah$]h&]refurijuh1j4jCKhjubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``API naming convention `_h]h)}(hjh](j!)}(hjh]hAPI naming convention}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameAPI naming conventionj2Ehttps://libbpf.readthedocs.io/en/latest/libbpf_naming_convention.htmluh1j hjubj5)}(hH h]h}(h]api-naming-conventionah ]h"]api naming conventionah$]h&]refurijuh1j4jCKhjubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hN`Building libbpf `_h]h)}(hjh](j!)}(hjh]hBuilding libbpf}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameBuilding libbpfj29https://libbpf.readthedocs.io/en/latest/libbpf_build.htmluh1j hjubj5)}(h< h]h}(h]building-libbpfah ]h"]building libbpfah$]h&]refurijuh1j4jCKhjubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h`API documentation Convention `_h]h)}(hj"h](j!)}(hj"h]hAPI documentation Convention}(hj'hhhNhNubah}(h]h ]h"]h$]h&]nameAPI documentation Conventionj2bhttps://libbpf.readthedocs.io/en/latest/libbpf_naming_convention.html#api-documentation-conventionuh1j hj$ubj5)}(he h]h}(h]api-documentation-conventionah ]h"]api documentation conventionah$]h&]refurij6uh1j4jCKhj$ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jhjiuh1hhhhKhj|hhubeh}(h]additional-documentationah ]h"]additional documentationah$]h&]uh1hhhhhhhhKubeh}(h]libbpf-overviewah ]h"]libbpf overviewah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jcj`jMjJjjjjjSjPj?j<j~j{jjjjjjjjj@j=j-j*jyjvj[jXjjjjjj j@j=u nametypes}(jcjMjjjSj?j~jjjjj@j-jyj[jjjj@uh}(j`hjJjxjjPjjQjPjj<j6j{jVjjjjjjjjj=jj*j$jvjCjXj|jjjjj jj=j7u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jKsRparse_messages]transform_messages] transformerN include_log] decorationNhhub.