1f42cfb46SGrant Seltzer.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) 2f42cfb46SGrant Seltzer 3f42cfb46SGrant SeltzerAPI naming convention 4f42cfb46SGrant Seltzer===================== 5f42cfb46SGrant Seltzer 6f42cfb46SGrant Seltzerlibbpf API provides access to a few logically separated groups of 7f42cfb46SGrant Seltzerfunctions and types. Every group has its own naming convention 8f42cfb46SGrant Seltzerdescribed here. It's recommended to follow these conventions whenever a 9f42cfb46SGrant Seltzernew function or type is added to keep libbpf API clean and consistent. 10f42cfb46SGrant Seltzer 11f42cfb46SGrant SeltzerAll types and functions provided by libbpf API should have one of the 12fb8ddf24SPu Lehuifollowing prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``btf_dump_``, 13fb8ddf24SPu Lehui``ring_buffer_``, ``perf_buffer_``. 14f42cfb46SGrant Seltzer 15f42cfb46SGrant SeltzerSystem call wrappers 16f42cfb46SGrant Seltzer-------------------- 17f42cfb46SGrant Seltzer 18f42cfb46SGrant SeltzerSystem call wrappers are simple wrappers for commands supported by 19f42cfb46SGrant Seltzersys_bpf system call. These wrappers should go to ``bpf.h`` header file 20f42cfb46SGrant Seltzerand map one to one to corresponding commands. 21f42cfb46SGrant Seltzer 22f42cfb46SGrant SeltzerFor example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM`` 23f42cfb46SGrant Seltzercommand of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc. 24f42cfb46SGrant Seltzer 25f42cfb46SGrant SeltzerObjects 26f42cfb46SGrant Seltzer------- 27f42cfb46SGrant Seltzer 28f42cfb46SGrant SeltzerAnother class of types and functions provided by libbpf API is "objects" 29f42cfb46SGrant Seltzerand functions to work with them. Objects are high-level abstractions 30f42cfb46SGrant Seltzersuch as BPF program or BPF map. They're represented by corresponding 31f42cfb46SGrant Seltzerstructures such as ``struct bpf_object``, ``struct bpf_program``, 32f42cfb46SGrant Seltzer``struct bpf_map``, etc. 33f42cfb46SGrant Seltzer 34f42cfb46SGrant SeltzerStructures are forward declared and access to their fields should be 35f42cfb46SGrant Seltzerprovided via corresponding getters and setters rather than directly. 36f42cfb46SGrant Seltzer 37f42cfb46SGrant SeltzerThese objects are associated with corresponding parts of ELF object that 38f42cfb46SGrant Seltzercontains compiled BPF programs. 39f42cfb46SGrant Seltzer 40f42cfb46SGrant SeltzerFor example ``struct bpf_object`` represents ELF object itself created 41f42cfb46SGrant Seltzerfrom an ELF file or from a buffer, ``struct bpf_program`` represents a 42f42cfb46SGrant Seltzerprogram in ELF object and ``struct bpf_map`` is a map. 43f42cfb46SGrant Seltzer 44f42cfb46SGrant SeltzerFunctions that work with an object have names built from object name, 45f42cfb46SGrant Seltzerdouble underscore and part that describes function purpose. 46f42cfb46SGrant Seltzer 47f42cfb46SGrant SeltzerFor example ``bpf_object__open`` consists of the name of corresponding 48f42cfb46SGrant Seltzerobject, ``bpf_object``, double underscore and ``open`` that defines the 49f42cfb46SGrant Seltzerpurpose of the function to open ELF file and create ``bpf_object`` from 50f42cfb46SGrant Seltzerit. 51f42cfb46SGrant Seltzer 52f42cfb46SGrant SeltzerAll objects and corresponding functions other than BTF related should go 53f42cfb46SGrant Seltzerto ``libbpf.h``. BTF types and functions should go to ``btf.h``. 54f42cfb46SGrant Seltzer 55f42cfb46SGrant SeltzerAuxiliary functions 56f42cfb46SGrant Seltzer------------------- 57f42cfb46SGrant Seltzer 58f42cfb46SGrant SeltzerAuxiliary functions and types that don't fit well in any of categories 59f42cfb46SGrant Seltzerdescribed above should have ``libbpf_`` prefix, e.g. 60f42cfb46SGrant Seltzer``libbpf_get_error`` or ``libbpf_prog_type_by_name``. 61f42cfb46SGrant Seltzer 62f42cfb46SGrant SeltzerABI 63d20b4111SGrant Seltzer--- 64f42cfb46SGrant Seltzer 65f42cfb46SGrant Seltzerlibbpf can be both linked statically or used as DSO. To avoid possible 66f42cfb46SGrant Seltzerconflicts with other libraries an application is linked with, all 67f42cfb46SGrant Seltzernon-static libbpf symbols should have one of the prefixes mentioned in 68f42cfb46SGrant SeltzerAPI documentation above. See API naming convention to choose the right 69f42cfb46SGrant Seltzername for a new symbol. 70f42cfb46SGrant Seltzer 71f42cfb46SGrant SeltzerSymbol visibility 72f42cfb46SGrant Seltzer----------------- 73f42cfb46SGrant Seltzer 74f42cfb46SGrant Seltzerlibbpf follow the model when all global symbols have visibility "hidden" 75f42cfb46SGrant Seltzerby default and to make a symbol visible it has to be explicitly 76f42cfb46SGrant Seltzerattributed with ``LIBBPF_API`` macro. For example: 77f42cfb46SGrant Seltzer 78f42cfb46SGrant Seltzer.. code-block:: c 79f42cfb46SGrant Seltzer 80f42cfb46SGrant Seltzer LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id); 81f42cfb46SGrant Seltzer 82f42cfb46SGrant SeltzerThis prevents from accidentally exporting a symbol, that is not supposed 83f42cfb46SGrant Seltzerto be a part of ABI what, in turn, improves both libbpf developer- and 84f42cfb46SGrant Seltzeruser-experiences. 85f42cfb46SGrant Seltzer 86*1d3cab43SRandy DunlapABI versioning 87*1d3cab43SRandy Dunlap-------------- 88f42cfb46SGrant Seltzer 89f42cfb46SGrant SeltzerTo make future ABI extensions possible libbpf ABI is versioned. 90f42cfb46SGrant SeltzerVersioning is implemented by ``libbpf.map`` version script that is 91f42cfb46SGrant Seltzerpassed to linker. 92f42cfb46SGrant Seltzer 93f42cfb46SGrant SeltzerVersion name is ``LIBBPF_`` prefix + three-component numeric version, 94f42cfb46SGrant Seltzerstarting from ``0.0.1``. 95f42cfb46SGrant Seltzer 96f42cfb46SGrant SeltzerEvery time ABI is being changed, e.g. because a new symbol is added or 97f42cfb46SGrant Seltzersemantic of existing symbol is changed, ABI version should be bumped. 98f42cfb46SGrant SeltzerThis bump in ABI version is at most once per kernel development cycle. 99f42cfb46SGrant Seltzer 100f42cfb46SGrant SeltzerFor example, if current state of ``libbpf.map`` is: 101f42cfb46SGrant Seltzer 1027c4a2233SRandy Dunlap.. code-block:: none 103f42cfb46SGrant Seltzer 104f42cfb46SGrant Seltzer LIBBPF_0.0.1 { 105f42cfb46SGrant Seltzer global: 106f42cfb46SGrant Seltzer bpf_func_a; 107f42cfb46SGrant Seltzer bpf_func_b; 108f42cfb46SGrant Seltzer local: 109f42cfb46SGrant Seltzer \*; 110f42cfb46SGrant Seltzer }; 111f42cfb46SGrant Seltzer 112f42cfb46SGrant Seltzer, and a new symbol ``bpf_func_c`` is being introduced, then 113f42cfb46SGrant Seltzer``libbpf.map`` should be changed like this: 114f42cfb46SGrant Seltzer 1157c4a2233SRandy Dunlap.. code-block:: none 116f42cfb46SGrant Seltzer 117f42cfb46SGrant Seltzer LIBBPF_0.0.1 { 118f42cfb46SGrant Seltzer global: 119f42cfb46SGrant Seltzer bpf_func_a; 120f42cfb46SGrant Seltzer bpf_func_b; 121f42cfb46SGrant Seltzer local: 122f42cfb46SGrant Seltzer \*; 123f42cfb46SGrant Seltzer }; 124f42cfb46SGrant Seltzer LIBBPF_0.0.2 { 125f42cfb46SGrant Seltzer global: 126f42cfb46SGrant Seltzer bpf_func_c; 127f42cfb46SGrant Seltzer } LIBBPF_0.0.1; 128f42cfb46SGrant Seltzer 129f42cfb46SGrant Seltzer, where new version ``LIBBPF_0.0.2`` depends on the previous 130f42cfb46SGrant Seltzer``LIBBPF_0.0.1``. 131f42cfb46SGrant Seltzer 132f42cfb46SGrant SeltzerFormat of version script and ways to handle ABI changes, including 133f42cfb46SGrant Seltzerincompatible ones, described in details in [1]. 134f42cfb46SGrant Seltzer 135f42cfb46SGrant SeltzerStand-alone build 136f42cfb46SGrant Seltzer------------------- 137f42cfb46SGrant Seltzer 138f42cfb46SGrant SeltzerUnder https://github.com/libbpf/libbpf there is a (semi-)automated 139f42cfb46SGrant Seltzermirror of the mainline's version of libbpf for a stand-alone build. 140f42cfb46SGrant Seltzer 141f42cfb46SGrant SeltzerHowever, all changes to libbpf's code base must be upstreamed through 142f42cfb46SGrant Seltzerthe mainline kernel tree. 143f42cfb46SGrant Seltzer 14493303034SGrant Seltzer 14593303034SGrant SeltzerAPI documentation convention 14693303034SGrant Seltzer============================ 14793303034SGrant Seltzer 14893303034SGrant SeltzerThe libbpf API is documented via comments above definitions in 14993303034SGrant Seltzerheader files. These comments can be rendered by doxygen and sphinx 15093303034SGrant Seltzerfor well organized html output. This section describes the 151*1d3cab43SRandy Dunlapconvention in which these comments should be formatted. 15293303034SGrant Seltzer 15393303034SGrant SeltzerHere is an example from btf.h: 15493303034SGrant Seltzer 15593303034SGrant Seltzer.. code-block:: c 15693303034SGrant Seltzer 15793303034SGrant Seltzer /** 15893303034SGrant Seltzer * @brief **btf__new()** creates a new instance of a BTF object from the raw 15993303034SGrant Seltzer * bytes of an ELF's BTF section 16093303034SGrant Seltzer * @param data raw bytes 16193303034SGrant Seltzer * @param size number of bytes passed in `data` 16293303034SGrant Seltzer * @return new BTF object instance which has to be eventually freed with 16393303034SGrant Seltzer * **btf__free()** 16493303034SGrant Seltzer * 16593303034SGrant Seltzer * On error, error-code-encoded-as-pointer is returned, not a NULL. To extract 16693303034SGrant Seltzer * error code from such a pointer `libbpf_get_error()` should be used. If 16793303034SGrant Seltzer * `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is enabled, NULL is 16893303034SGrant Seltzer * returned on error instead. In both cases thread-local `errno` variable is 16993303034SGrant Seltzer * always set to error code as well. 17093303034SGrant Seltzer */ 17193303034SGrant Seltzer 17293303034SGrant SeltzerThe comment must start with a block comment of the form '/\*\*'. 17393303034SGrant Seltzer 17493303034SGrant SeltzerThe documentation always starts with a @brief directive. This line is a short 17593303034SGrant Seltzerdescription about this API. It starts with the name of the API, denoted in bold 17693303034SGrant Seltzerlike so: **api_name**. Please include an open and close parenthesis if this is a 17793303034SGrant Seltzerfunction. Follow with the short description of the API. A longer form description 17893303034SGrant Seltzercan be added below the last directive, at the bottom of the comment. 17993303034SGrant Seltzer 18093303034SGrant SeltzerParameters are denoted with the @param directive, there should be one for each 18193303034SGrant Seltzerparameter. If this is a function with a non-void return, use the @return directive 18293303034SGrant Seltzerto document it. 18393303034SGrant Seltzer 184f42cfb46SGrant SeltzerLicense 185f42cfb46SGrant Seltzer------------------- 186f42cfb46SGrant Seltzer 187f42cfb46SGrant Seltzerlibbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause. 188f42cfb46SGrant Seltzer 189f42cfb46SGrant SeltzerLinks 190f42cfb46SGrant Seltzer------------------- 191f42cfb46SGrant Seltzer 192f42cfb46SGrant Seltzer[1] https://www.akkadia.org/drepper/dsohowto.pdf 193f42cfb46SGrant Seltzer (Chapter 3. Maintaining APIs and ABIs). 194