Skip to contentSkip to conversation

BPF, docs: libbpf Overview Document

PATCH Superseded Sreevani Sreejith 2 participants 2 messages Mar 9, 2023 – Mar 10, 2023

Subsystems (2)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 BPF, docs: libbpf Overview Document

From: Sreevani <[email protected]>

Summary: Document that provides an overview of libbpf features for BPF application development.

Reviewers:

Subscribers:

---
 Documentation/bpf/libbpf/index.rst           |  25 +-
 Documentation/bpf/libbpf/libbpf_overview.rst | 238 +++++++++++++++++++
 2 files changed, 255 insertions(+), 8 deletions(-)
 create mode 100644 Documentation/bpf/libbpf/libbpf_overview.rst
Documentation/bpf/libbpf/index.rst +17 -8
index f9b3b252e28f..7545a2049692 100644
@@ -2,23 +2,32 @@
 
 .. _libbpf:
 
+======
 libbpf
 ======
 
+If you are looking to develop BPF applications using the libbpf library, this
+directory contains important documentation that you should read.
+
+To get started, it is recommended to begin with the :doc:`libbpf Overview
+<libbpf_overview>` document, which provides a high-level understanding of the
+libbpf APIs and their usage. This will give you a solid foundation to start
+exploring and utilizing the various features of libbpf to develop your BPF
+applications.
+
 .. toctree::
    :maxdepth: 1
 
+   libbpf_overview
    API Documentation <https://libbpf.readthedocs.io/en/latest/api.html>
    program_types
    libbpf_naming_convention
    libbpf_build
 
-This is documentation for libbpf, a userspace library for loading and
-interacting with bpf programs.
 
-All general BPF questions, including kernel functionality, libbpf APIs and
-their application, should be sent to [email protected] mailing list.
-You can `subscribe <http://vger.kernel.org/vger-lists.html#bpf>`_ to the
-mailing list search its `archive <https://lore.kernel.org/bpf/>`_.
-Please search the archive before asking new questions. It very well might
-be that this was already addressed or answered before.
+All general BPF questions, including kernel functionality, libbpf APIs and their
+application, should be sent to [email protected] mailing list.  You can
+`subscribe <http://vger.kernel.org/vger-lists.html#bpf>`_ to the mailing list
+search its `archive <https://lore.kernel.org/bpf/>`_.  Please search the archive
+before asking new questions. It may be that this was already addressed or
+answered before.
Documentation/bpf/libbpf/libbpf_overview.rst new file +238 -0

238 lines not on this page · raw message

Signature · 1 line
2.34.1
#1 lore raw
Quoted 8 lines · Sreevani Sreejith

From: Sreevani <[email protected]>

Summary: Document that provides an overview of libbpf features for BPF application development.

Reviewers:

Subscribers:

Please remove the boilerplate above. The summary should become patch description.

Quoted 3 lines

+======
libbpf
======

Why did you promote the heading above to title heading?

Documentation/bpf/libbpf/libbpf_overview.rst line 3

Quoted 9 lines
Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
new file mode 100644
index 000000000000..549469aa2d3b
@@ -0,0 +1,238 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.._libbpf-overview-label:

Missing space before label name. Or should the label name be "_libbpf-overview"?

Quoted 20 lines
Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
+#################################
+BPF App Lifecycle and libbpf APIs
+#################################

<snipped> ...

Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
+########################
+BPF Object Skeleton File
+########################

<snipped> ...
+---------------------------------------

Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
+Other Advantages of Using Skeleton File
+---------------------------------------
+

<snipped> ...

Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
+###########
+BPF Helpers
+###########

<snipped> ...

Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
+#########################################
+BPF CO-RE (Compile Once – Run Everywhere)
+#########################################
Quoted 1 line

<snipped> ...

See the bottom.

Documentation/bpf/libbpf/libbpf_overview.rst line 161

Quoted 6 lines
Documentation/bpf/libbpf/libbpf_overview.rst new file +6 -0
+You can generate the BTF information for the running kernel with the following
+command:
+
+::
+
+$ bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h

My htmldocs build renders the code block above fine, but IMO the convention here is to indent it.

Quoted 10 lines
Documentation/bpf/libbpf/libbpf_overview.rst new file +10 -0
+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``.
+
+  .. code-block:: C
+    :emphasize-lines: 6
+
+    //...

Documentation/bpf/libbpf/libbpf_overview.rst line 197

Quoted 10 lines
Documentation/bpf/libbpf/libbpf_overview.rst new file +10 -0
+    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 */

I guess :linenos: option also helps locating the highlighted line, right?

Documentation/bpf/libbpf/libbpf_overview.rst line 233

Quoted 11 lines
Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
+###########################
+Getting Started with libbpf
+###########################

<snipped> ...

Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
+###############
+libbpf and Rust
+###############

<snipped> ...

Documentation/bpf/libbpf/libbpf_overview.rst new file +3 -0
+########################
+Additional Documentation
+########################

For section headings above, I'd like to strip the overline. Yet, Sphinx is smart when discriminating headings based on underline/overline character.

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara