libbpf: Document API and ABI conventions

.. SPDX-License-Identifier: GPL-2.0

libbpf API naming convention

============================

libbpf API provides access to a few logically separated groups of

functions and types. Every group has its own naming convention

described here. It's recommended to follow these conventions whenever a

new function or type is added to keep libbpf API clean and consistent.

All types and functions provided by libbpf API should have one of the

following prefixes: ``bpf_``, ``btf_``, ``libbpf_``.

System call wrappers

--------------------

System call wrappers are simple wrappers for commands supported by

sys_bpf system call. These wrappers should go to ``bpf.h`` header file

and map one-on-one to corresponding commands.

For example ``bpf_map_lookup_elem`` wraps ``BPF_MAP_LOOKUP_ELEM``

command of sys_bpf, ``bpf_prog_attach`` wraps ``BPF_PROG_ATTACH``, etc.

Objects

-------

Another class of types and functions provided by libbpf API is "objects"

and functions to work with them. Objects are high-level abstractions

such as BPF program or BPF map. They're represented by corresponding

structures such as ``struct bpf_object``, ``struct bpf_program``,

``struct bpf_map``, etc.

Structures are forward declared and access to their fields should be

provided via corresponding getters and setters rather than directly.

These objects are associated with corresponding parts of ELF object that

contains compiled BPF programs.

For example ``struct bpf_object`` represents ELF object itself created

from an ELF file or from a buffer, ``struct bpf_program`` represents a

program in ELF object and ``struct bpf_map`` is a map.

Functions that work with an object have names built from object name,

double underscore and part that describes function purpose.

For example ``bpf_object__open`` consists of the name of corresponding

object, ``bpf_object``, double underscore and ``open`` that defines the

purpose of the function to open ELF file and create ``bpf_object`` from

it.

Another example: ``bpf_program__load`` is named for corresponding

object, ``bpf_program``, that is separated from other part of the name

by double underscore.

All objects and corresponding functions other than BTF related should go

to ``libbpf.h``. BTF types and functions should go to ``btf.h``.

Auxiliary functions

-------------------

Auxiliary functions and types that don't fit well in any of categories

described above should have ``libbpf_`` prefix, e.g.

``libbpf_get_error`` or ``libbpf_prog_type_by_name``.

libbpf ABI

==========

libbpf can be both linked statically or used as DSO. To avoid possible

conflicts with other libraries an application is linked with, all

non-static libbpf symbols should have one of the prefixes mentioned in

API documentation above. See API naming convention to choose the right

name for a new symbol.

Symbol visibility

-----------------

libbpf follow the model when all global symbols have visibility "hidden"

by default and to make a symbol visible it has to be explicitly

attributed with ``LIBBPF_API`` macro. For example:

.. code-block:: c

        LIBBPF_API int bpf_prog_get_fd_by_id(__u32 id);

This prevents from accidentally exporting a symbol, that is not supposed

to be a part of ABI what, in turn, improves both libbpf developer- and

user-experiences.

ABI versionning

---------------

To make future ABI extensions possible libbpf ABI is versioned.

Versioning is implemented by ``libbpf.map`` version script that is

passed to linker.

Version name is ``LIBBPF_`` prefix + three-component numeric version,

starting from ``0.0.1``.

Every time ABI is being changed, e.g. because a new symbol is added or

semantic of existing symbol is changed, ABI version should be bumped.

For example, if current state of ``libbpf.map`` is:

.. code-block::

        LIBBPF_0.0.1 {

        	global:

                        bpf_func_a;

                        bpf_func_b;

        	local:

        		\*;

        };

, and a new symbol ``bpf_func_c`` is being introduced, then

``libbpf.map`` should be changed like this:

.. code-block::

        LIBBPF_0.0.1 {

        	global:

                        bpf_func_a;

                        bpf_func_b;

        	local:

        		\*;

        };

        LIBBPF_0.0.2 {

                global:

                        bpf_func_c;

        } LIBBPF_0.0.1;

, where new version ``LIBBPF_0.0.2`` depends on the previous

``LIBBPF_0.0.1``.

Format of version script and ways to handle ABI changes, including

incompatible ones, described in details in [1].

Links

=====

[1] https://www.akkadia.org/drepper/dsohowto.pdf

    (Chapter 3. Maintaining APIs and ABIs).