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.
>
> 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

Oh. You should probably test this with out-of-tree builds.

BR,
Jani.

> +   :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