From: grantseltzer <grantseltzer@gmail.com>
To: andrii@kernel.org, daniel@iogearbox.net
Cc: grantseltzer@gmail.com, bpf@vger.kernel.org
Subject: [PATCH bpf-next 3/3] bpf: Add rst docs for libbpf
Date: Thu, 29 Apr 2021 05:47:34 +0000 [thread overview]
Message-ID: <20210429054734.53264-4-grantseltzer@gmail.com> (raw)
In-Reply-To: <20210429054734.53264-1-grantseltzer@gmail.com>
This adds rst files containg documentation files relevant for
libbpf development. naming_convention.rst is pulled from the
previous README.rst file. api.rst is an index page that links
to the api documentation generationg from doxygen+breathe.
Signed-off-by: grantseltzer <grantseltzer@gmail.com>
---
tools/lib/bpf/docs/api.rst | 60 +++++++++++++++++++
tools/lib/bpf/docs/build.rst | 39 ++++++++++++
tools/lib/bpf/docs/index.rst | 6 ++
.../naming_convention.rst} | 18 +++---
4 files changed, 116 insertions(+), 7 deletions(-)
create mode 100644 tools/lib/bpf/docs/api.rst
create mode 100644 tools/lib/bpf/docs/build.rst
rename tools/lib/bpf/{README.rst => docs/naming_convention.rst} (97%)
diff --git a/tools/lib/bpf/docs/api.rst b/tools/lib/bpf/docs/api.rst
new file mode 100644
index 000000000..36bac417b
--- /dev/null
+++ b/tools/lib/bpf/docs/api.rst
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+
+.. _api:
+
+.. contents:: Table of Contents
+ :local:
+ :depth: 1
+
+LIBBPF API
+==================
+
+
+libbpf.h
+------------------
+
+.. doxygenfile:: libbpf.h
+ :project: libbpf
+
+bpf_core_read.h
+------------------
+
+.. doxygenfile:: bpf_core_read.h
+ :project: libbpf
+
+btf.h
+------------------
+
+.. doxygenfile:: btf.h
+ :project: libbpf
+
+bpf_endian.h
+------------------
+
+.. doxygenfile:: bpf_endian.h
+ :project: libbpf
+
+libbpf_common.h
+------------------
+
+.. doxygenfile:: libbpf_common.h
+ :project: libbpf
+
+hashmap.h
+------------------
+
+.. doxygenfile:: hashmap.h
+ :project: libbpf
+
+
+bpf_helpers.h
+------------------
+
+.. doxygenfile:: bpf_helpers.h
+ :project: libbpf
+
+bpf_helper_defs.h
+------------------
+
+.. doxygenfile:: hashmap.h
+ :project: libbpf
diff --git a/tools/lib/bpf/docs/build.rst b/tools/lib/bpf/docs/build.rst
new file mode 100644
index 000000000..749f96dd2
--- /dev/null
+++ b/tools/lib/bpf/docs/build.rst
@@ -0,0 +1,39 @@
+.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+
+.. _build:
+
+Building libbpf
+=======================================
+
+libelf is an internal dependency of libbpf and thus it is required to link
+against and must be installed on the system for applications to work.
+pkg-config is used by default to find libelf, and the program called
+can be overridden with PKG_CONFIG.
+
+If using pkg-config at build time is not desired, it can be disabled by
+setting NO_PKG_CONFIG=1 when calling make.
+
+To build both static libbpf.a and shared libbpf.so:
+
+.. code-block:: bash
+
+ $ cd src
+ $ make
+
+To build only static libbpf.a library in directory build/ and install them
+together with libbpf headers in a staging directory root/:
+
+.. code-block:: bash
+
+ $ cd src
+ $ mkdir build root
+ $ BUILD_STATIC_ONLY=y OBJDIR=build DESTDIR=root make install
+
+To build both static libbpf.a and shared libbpf.so against a custom libelf
+dependency installed in /build/root/ and install them together with libbpf
+headers in a build directory /build/root/:
+
+.. code-block:: bash
+
+ $ cd src
+ $ PKG_CONFIG_PATH=/build/root/lib64/pkgconfig DESTDIR=/build/root make
\ No newline at end of file
diff --git a/tools/lib/bpf/docs/index.rst b/tools/lib/bpf/docs/index.rst
index 31a6ecfab..76bb93580 100644
--- a/tools/lib/bpf/docs/index.rst
+++ b/tools/lib/bpf/docs/index.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+
libbpf documentation
=======================================
@@ -13,3 +15,7 @@ be that this was already addressed or answered before.
.. toctree::
:caption: Documentation:
+
+ api
+ naming_convention
+ build
\ No newline at end of file
diff --git a/tools/lib/bpf/README.rst b/tools/lib/bpf/docs/naming_convention.rst
similarity index 97%
rename from tools/lib/bpf/README.rst
rename to tools/lib/bpf/docs/naming_convention.rst
index 8928f7787..6b9ae9701 100644
--- a/tools/lib/bpf/README.rst
+++ b/tools/lib/bpf/docs/naming_convention.rst
@@ -1,6 +1,8 @@
.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
-libbpf API naming convention
+.. _naming_convention:
+
+API naming convention
============================
libbpf API provides access to a few logically separated groups of
@@ -76,7 +78,7 @@ Please take a look at Documentation/networking/af_xdp.rst in the Linux
kernel source tree on how to use XDP sockets and for some common
mistakes in case you do not get any traffic up to user space.
-libbpf ABI
+ABI
==========
libbpf can be both linked statically or used as DSO. To avoid possible
@@ -116,7 +118,8 @@ This bump in ABI version is at most once per kernel development cycle.
For example, if current state of ``libbpf.map`` is:
-.. code-block::
+.. code-block:: c
+
LIBBPF_0.0.1 {
global:
bpf_func_a;
@@ -128,7 +131,8 @@ For example, if current state of ``libbpf.map`` is:
, and a new symbol ``bpf_func_c`` is being introduced, then
``libbpf.map`` should be changed like this:
-.. code-block::
+.. code-block:: c
+
LIBBPF_0.0.1 {
global:
bpf_func_a;
@@ -148,7 +152,7 @@ Format of version script and ways to handle ABI changes, including
incompatible ones, described in details in [1].
Stand-alone build
-=================
+-------------------
Under https://github.com/libbpf/libbpf there is a (semi-)automated
mirror of the mainline's version of libbpf for a stand-alone build.
@@ -157,12 +161,12 @@ However, all changes to libbpf's code base must be upstreamed through
the mainline kernel tree.
License
-=======
+-------------------
libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
Links
-=====
+-------------------
[1] https://www.akkadia.org/drepper/dsohowto.pdf
(Chapter 3. Maintaining APIs and ABIs).
--
2.29.2
next prev parent reply other threads:[~2021-04-29 21:41 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-29 5:47 [PATCH bpf-next 0/3] Autogenerating API documentation grantseltzer
2021-04-29 5:47 ` [PATCH bpf-next 1/3] bpf: Add sphinx documentation build files grantseltzer
2021-04-29 5:47 ` [PATCH bpf-next 2/3] bpf: Add doxygen configuration file grantseltzer
2021-04-29 5:47 ` grantseltzer [this message]
2021-04-29 22:57 ` [PATCH bpf-next 0/3] Autogenerating API documentation Jonathan Corbet
2021-04-30 14:04 ` Grant Seltzer Richman
2021-04-30 14:22 ` Jonathan Corbet
2021-04-30 14:27 ` Grant Seltzer Richman
2021-04-30 17:30 ` Andrii Nakryiko
2021-05-10 14:58 ` Grant Seltzer Richman
2021-05-10 17:48 ` Andrii Nakryiko
2021-05-26 3:22 ` Grant Seltzer Richman
2021-05-26 20:45 ` Andrii Nakryiko
2021-05-28 14:50 ` Grant Seltzer Richman
2021-06-01 19:01 ` Jonathan Corbet
2021-06-01 22:49 ` Grant Seltzer Richman
2021-06-01 23:19 ` Jonathan Corbet
2021-06-02 1:06 ` Grant Seltzer Richman
2021-06-04 21:18 ` Grant Seltzer Richman
2021-06-07 22:45 ` Andrii Nakryiko
2021-06-09 17:04 ` Grant Seltzer Richman
2021-06-10 17:14 ` Andrii Nakryiko
2021-06-11 20:00 ` Grant Seltzer Richman
2021-06-14 22:35 ` Andrii Nakryiko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210429054734.53264-4-grantseltzer@gmail.com \
--to=grantseltzer@gmail.com \
--cc=andrii@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=daniel@iogearbox.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).