^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) libbpf API naming convention
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) libbpf API provides access to a few logically separated groups of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) functions and types. Every group has its own naming convention
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) described here. It's recommended to follow these conventions whenever a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) new function or type is added to keep libbpf API clean and consistent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) All types and functions provided by libbpf API should have one of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``xsk_``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) ``perf_buffer_``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) System call wrappers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) System call wrappers are simple wrappers for commands supported by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) sys_bpf system call. These wrappers should go to ``bpf.h`` header file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) and map one-on-one to corresponding commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) For example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) command of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) Objects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Another class of types and functions provided by libbpf API is "objects"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) and functions to work with them. Objects are high-level abstractions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) such as BPF program or BPF map. They're represented by corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) structures such as ``struct bpf_object``, ``struct bpf_program``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ``struct bpf_map``, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Structures are forward declared and access to their fields should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) provided via corresponding getters and setters rather than directly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) These objects are associated with corresponding parts of ELF object that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) contains compiled BPF programs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) For example ``struct bpf_object`` represents ELF object itself created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) from an ELF file or from a buffer, ``struct bpf_program`` represents a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) program in ELF object and ``struct bpf_map`` is a map.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) Functions that work with an object have names built from object name,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) double underscore and part that describes function purpose.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) For example ``bpf_object__open`` consists of the name of corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) object, ``bpf_object``, double underscore and ``open`` that defines the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) purpose of the function to open ELF file and create ``bpf_object`` from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Another example: ``bpf_program__load`` is named for corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) object, ``bpf_program``, that is separated from other part of the name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) by double underscore.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) All objects and corresponding functions other than BTF related should go
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) to ``libbpf.h``. BTF types and functions should go to ``btf.h``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Auxiliary functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Auxiliary functions and types that don't fit well in any of categories
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) described above should have ``libbpf_`` prefix, e.g.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) ``libbpf_get_error`` or ``libbpf_prog_type_by_name``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) AF_XDP functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) AF_XDP functions should have an ``xsk_`` prefix, e.g.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) ``xsk_umem__get_data`` or ``xsk_umem__create``. The interface consists
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) of both low-level ring access functions and high-level configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) functions. These can be mixed and matched. Note that these functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) are not reentrant for performance reasons.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) Please take a look at Documentation/networking/af_xdp.rst in the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) kernel source tree on how to use XDP sockets and for some common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) mistakes in case you do not get any traffic up to user space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) libbpf ABI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) libbpf can be both linked statically or used as DSO. To avoid possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) conflicts with other libraries an application is linked with, all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) non-static libbpf symbols should have one of the prefixes mentioned in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) API documentation above. See API naming convention to choose the right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) name for a new symbol.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) Symbol visibility
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) libbpf follow the model when all global symbols have visibility "hidden"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) by default and to make a symbol visible it has to be explicitly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) attributed with ``LIBBPF_API`` macro. For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) This prevents from accidentally exporting a symbol, that is not supposed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) to be a part of ABI what, in turn, improves both libbpf developer- and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) user-experiences.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) ABI versionning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) To make future ABI extensions possible libbpf ABI is versioned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) Versioning is implemented by ``libbpf.map`` version script that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) passed to linker.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Version name is ``LIBBPF_`` prefix + three-component numeric version,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) starting from ``0.0.1``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) Every time ABI is being changed, e.g. because a new symbol is added or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) semantic of existing symbol is changed, ABI version should be bumped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) This bump in ABI version is at most once per kernel development cycle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) For example, if current state of ``libbpf.map`` is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) .. code-block::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) LIBBPF_0.0.1 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) global:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) bpf_func_a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) bpf_func_b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) local:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) \*;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) , and a new symbol ``bpf_func_c`` is being introduced, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) ``libbpf.map`` should be changed like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) .. code-block::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) LIBBPF_0.0.1 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) global:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) bpf_func_a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) bpf_func_b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) local:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) \*;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) LIBBPF_0.0.2 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) global:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) bpf_func_c;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) } LIBBPF_0.0.1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) , where new version ``LIBBPF_0.0.2`` depends on the previous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) ``LIBBPF_0.0.1``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) Format of version script and ways to handle ABI changes, including
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) incompatible ones, described in details in [1].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Stand-alone build
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) Under https://github.com/libbpf/libbpf there is a (semi-)automated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) mirror of the mainline's version of libbpf for a stand-alone build.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) However, all changes to libbpf's code base must be upstreamed through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) the mainline kernel tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) License
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) Links
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) =====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) [1] https://www.akkadia.org/drepper/dsohowto.pdf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) (Chapter 3. Maintaining APIs and ABIs).
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags