Extend the libbpf documentation with a table of program types,
attach points and ELF section names. This table uses data from
program_types.csv which is generated from tools/lib/bpf/libbpf.c
during the documentation build.
Signed-off-by: Donald Hunter <donald.hunter@xxxxxxxxx>
---
Documentation/Makefile | 3 +-
Documentation/bpf/libbpf/.gitignore | 1 +
Documentation/bpf/libbpf/Makefile | 29 ++++++++++++++++++
Documentation/bpf/libbpf/index.rst | 3 ++
Documentation/bpf/libbpf/program_types.rst | 32 ++++++++++++++++++++
Documentation/bpf/programs.rst | 3 ++
scripts/gen-bpf-progtypes.sh | 34 ++++++++++++++++++++++
7 files changed, 104 insertions(+), 1 deletion(-)
create mode 100644 Documentation/bpf/libbpf/.gitignore
create mode 100644 Documentation/bpf/libbpf/Makefile
create mode 100644 Documentation/bpf/libbpf/program_types.rst
create mode 100755 scripts/gen-bpf-progtypes.sh
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 8a63ef2dcd1c..f007314770e1 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -66,7 +66,8 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
BUILD_SUBDIRS = \
- Documentation/userspace-api/media
+ Documentation/userspace-api/media \
+ Documentation/bpf/libbpf
quiet_cmd_build_subdir = SUBDIR $2
cmd_build_subdir = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=$2 $3
diff --git a/Documentation/bpf/libbpf/.gitignore b/Documentation/bpf/libbpf/.gitignore
new file mode 100644
index 000000000000..c9013b8cae08
--- /dev/null
+++ b/Documentation/bpf/libbpf/.gitignore
@@ -0,0 +1 @@
+/program_types.csv
diff --git a/Documentation/bpf/libbpf/Makefile b/Documentation/bpf/libbpf/Makefile
new file mode 100644
index 000000000000..9cc3f67b5602
--- /dev/null
+++ b/Documentation/bpf/libbpf/Makefile
@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# Rules to convert BPF program types in tools/lib/bpf/libbpf.c
+# into a .csv file
+
+PROGRAM_TYPES = $(srctree)/Documentation/bpf/libbpf/program_types.csv
+
+TARGETS := $(PROGRAM_TYPES)
+
+
+$(PROGRAM_TYPES): $(srctree)/tools/lib/bpf/libbpf.c
+ $(Q)$(srctree)/scripts/gen-bpf-progtypes.sh $< $@
+
+.PHONY: all html epub xml latex linkcheck clean
+
+all: $(BUILDDIR) ${TARGETS}
+ @:
+
+html: all
+epub: all
+xml: all
+latex: all
+linkcheck:
+
+clean:
+ -$(Q)rm -f ${TARGETS} 2>/dev/null
+
+$(BUILDDIR):
+ $(Q)mkdir -p $@
diff --git a/Documentation/bpf/libbpf/index.rst b/Documentation/bpf/libbpf/index.rst
index 3722537d1384..f9b3b252e28f 100644
--- a/Documentation/bpf/libbpf/index.rst
+++ b/Documentation/bpf/libbpf/index.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+.. _libbpf:
+
libbpf
======
@@ -7,6 +9,7 @@ libbpf
:maxdepth: 1
API Documentation <https://libbpf.readthedocs.io/en/latest/api.html>
+ program_types
libbpf_naming_convention
libbpf_build
diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst
new file mode 100644
index 000000000000..b74fbf3363dd
--- /dev/null
+++ b/Documentation/bpf/libbpf/program_types.rst
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+
+.. _program_types_and_elf:
+
+Program Types and ELF Sections
+==============================
+
+The table below lists the program types, their attach types where relevant and the ELF section
+names supported by libbpf for them. The ELF section names follow these rules:
+
+- ``type`` is an exact match, e.g. ``SEC("socket")``
+- ``type+`` means it can be either exact ``SEC("type")`` or well-formed ``SEC("type/extras")``
+ with a ‘``/``’ separator between ``type`` and ``extras``.
+
+When ``extras`` are specified, they provide details of how to auto-attach the BPF program.
+The format of ``extras`` depends on the program type, e.g. ``SEC("tracepoint/<category>/<name>")``
+for tracepoints or ``SEC("usdt/<path-to-binary>:<usdt_provider>:<usdt_name>")`` for USDT probes.
+
+..
+ program_types.csv is generated from tools/lib/bpf/libbpf.c and is formatted like this:
+ Program Type,Attach Type,ELF Section Name,Sleepable
+ ``BPF_PROG_TYPE_SOCKET_FILTER``,,``socket``,
+ ``BPF_PROG_TYPE_SK_REUSEPORT``,``BPF_SK_REUSEPORT_SELECT_OR_MIGRATE``,``sk_reuseport/migrate``,
+ ``BPF_PROG_TYPE_SK_REUSEPORT``,``BPF_SK_REUSEPORT_SELECT``,``sk_reuseport``,
+ ``BPF_PROG_TYPE_KPROBE``,,``kprobe+``,
+ ``BPF_PROG_TYPE_KPROBE``,,``uprobe+``,
+ ``BPF_PROG_TYPE_KPROBE``,,``uprobe.s+``,Yes
+
+.. csv-table:: Program Types and Their ELF Section Names
+ :file: program_types.csv
+ :widths: 40 30 20 10
+ :header-rows: 1
diff --git a/Documentation/bpf/programs.rst b/Documentation/bpf/programs.rst
index 620eb667ac7a..c99000ab6d9b 100644
--- a/Documentation/bpf/programs.rst
+++ b/Documentation/bpf/programs.rst
@@ -7,3 +7,6 @@ Program Types
:glob:
prog_*
+
+For a list of all program types, see :ref:`program_types_and_elf` in
+the :ref:`libbpf` documentation.
diff --git a/scripts/gen-bpf-progtypes.sh b/scripts/gen-bpf-progtypes.sh
new file mode 100755
index 000000000000..3bf36f26a2f7
--- /dev/null
+++ b/scripts/gen-bpf-progtypes.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+# SPDX-License-Identifier: GPL-2.0-only
+#
+# Copyright (C) 2022 Red Hat.
+#
+# Generate a .csv table of BPF program types
+
+if [ "$#" -lt 2 ]; then
+ echo "Usage: gen-bpf-progtypes.sh </path/to/libbpf.c> </path/to/generated.csv>"
+ exit 1
+fi
+
+# Extract program types and properties from the section definitions in libbpf.c such as
+# SEC_DEF("socket", SOCKET_FILTER, 0, SEC_NONE) to generate a table of program types in
+# .csv format.
+#
+# Here is a sample of the generated output that includes .rst formatting:
+#
+# Program Type,Attach Type,ELF Section Name,Sleepable
+# ``BPF_PROG_TYPE_SOCKET_FILTER``,,``socket``,
+# ``BPF_PROG_TYPE_SK_REUSEPORT``,``BPF_SK_REUSEPORT_SELECT_OR_MIGRATE``,``sk_reuseport/migrate``,
+# ``BPF_PROG_TYPE_SK_REUSEPORT``,``BPF_SK_REUSEPORT_SELECT``,``sk_reuseport``,
+# ``BPF_PROG_TYPE_KPROBE``,,``kprobe+``,
+# ``BPF_PROG_TYPE_KPROBE``,,``uprobe+``,
+# ``BPF_PROG_TYPE_KPROBE``,,``uprobe.s+``,Yes
+
+awk -F'[",[:space:]]+' \
+ 'BEGIN { print "Program Type,Attach Type,ELF Section Name,Sleepable" }
+ /SEC_DEF\(\"/ && !/SEC_DEPRECATED/ {
+ type = "``BPF_PROG_TYPE_" $4 "``"
+ attach = index($5, "0") ? "" : "``" $5 "``";
+ section = "``" $3 "``"
+ sleepable = index($0, "SEC_SLEEPABLE") ? "Yes" : "";
+ print type "," attach "," section "," sleepable }' $1 | sort > $2
--
2.35.1
