Re: [PATCH bpf-next v3 2/2] Add table of BPF program types to libbpf docs

[Jani Nikula <jani.nikula@linux.intel.com>]

On Mon, 29 Aug 2022, Donald Hunter <donald.hunter@gmail.com> wrote:
> 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.

Oh, would be nice to turn all of these into proper but simple Sphinx
extensions that take the deps into account in the Sphinx build
process. And, of course, would be pure python instead of a combo of
Make, shell, and awk.

That's one of the reasons we chose Sphinx originally, to be able to
write Sphinx extensions and avoid complicated pipelines.

BR,
Jani.


>
> Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
> ---
>  Documentation/Makefile                     |  3 +-
>  Documentation/bpf/libbpf/Makefile          | 49 ++++++++++++++++++++++
>  Documentation/bpf/libbpf/index.rst         |  3 ++
>  Documentation/bpf/libbpf/program_types.rst | 32 ++++++++++++++
>  Documentation/bpf/programs.rst             |  3 ++
>  5 files changed, 89 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/bpf/libbpf/Makefile
>  create mode 100644 Documentation/bpf/libbpf/program_types.rst
>
> 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/Makefile b/Documentation/bpf/libbpf/Makefile
> new file mode 100644
> index 000000000000..b3dc096c4a96
> --- /dev/null
> +++ b/Documentation/bpf/libbpf/Makefile
> @@ -0,0 +1,49 @@
> +# SPDX-License-Identifier: GPL-2.0
> +#
> +# Rules to convert BPF program types in tools/lib/bpf/libbpf.c
> +# into a .csv file
> +
> +FILES = program_types.csv
> +
> +TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
> +
> +# Extract program types and properties from the section definitions in libbpf.c such as
> +# SEC_DEF("socket", SOCKET_FILTER, 0, SEC_NONE) to generate program_types.csv
> +#
> +# 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
> +
> +$(BUILDDIR)/program_types.csv:	$(srctree)/tools/lib/bpf/libbpf.c
> +	$(Q)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 }' \
> +	$< > $@
> +
> +.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..04fbb48b8a6a
> --- /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 fomatted 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: ../../output/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.

-- 
Jani Nikula, Intel Open Source Graphics Center