diff mbox series

[bpf-next,v2,2/2] Add table of BPF program types to libbpf docs

Message ID 20220824221018.24684-3-donald.hunter@gmail.com (mailing list archive)
State Superseded
Delegated to: BPF
Headers show
Series Add table of BPF program types to docs | expand

Checks

Context Check Description
netdev/tree_selection success Clearly marked for bpf-next
netdev/fixes_present success Fixes tag not required for -next series
netdev/subject_prefix success Link
netdev/cover_letter success Series has a cover letter
netdev/patch_count success Link
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit success Errors and warnings before: 0 this patch: 0
netdev/cc_maintainers warning 13 maintainers not CCed: john.fastabend@gmail.com jolsa@kernel.org grantseltzer@gmail.com song@kernel.org yhs@fb.com dave@dtucker.co.uk daniel@iogearbox.net martin.lau@linux.dev haoluo@google.com ast@kernel.org andrii@kernel.org kpsingh@kernel.org sdf@google.com
netdev/build_clang success Errors and warnings before: 0 this patch: 0
netdev/module_param success Was 0 now: 0
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 0 this patch: 0
netdev/checkpatch warning WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0
bpf/vmtest-bpf-next-VM_Test-6 success Logs for test_maps on s390x with gcc
bpf/vmtest-bpf-next-VM_Test-9 success Logs for test_progs on s390x with gcc
bpf/vmtest-bpf-next-VM_Test-12 success Logs for test_progs_no_alu32 on s390x with gcc
bpf/vmtest-bpf-next-PR fail PR summary
bpf/vmtest-bpf-next-VM_Test-15 fail Logs for test_verifier on s390x with gcc
bpf/vmtest-bpf-next-VM_Test-4 success Logs for llvm-toolchain
bpf/vmtest-bpf-next-VM_Test-5 success Logs for set-matrix
bpf/vmtest-bpf-next-VM_Test-2 success Logs for build for x86_64 with gcc
bpf/vmtest-bpf-next-VM_Test-3 success Logs for build for x86_64 with llvm-16
bpf/vmtest-bpf-next-VM_Test-1 success Logs for build for s390x with gcc
bpf/vmtest-bpf-next-VM_Test-7 success Logs for test_maps on x86_64 with gcc
bpf/vmtest-bpf-next-VM_Test-8 success Logs for test_maps on x86_64 with llvm-16
bpf/vmtest-bpf-next-VM_Test-13 success Logs for test_progs_no_alu32 on x86_64 with gcc
bpf/vmtest-bpf-next-VM_Test-14 success Logs for test_progs_no_alu32 on x86_64 with llvm-16
bpf/vmtest-bpf-next-VM_Test-16 success Logs for test_verifier on x86_64 with gcc
bpf/vmtest-bpf-next-VM_Test-17 success Logs for test_verifier on x86_64 with llvm-16
bpf/vmtest-bpf-next-VM_Test-10 success Logs for test_progs on x86_64 with gcc
bpf/vmtest-bpf-next-VM_Test-11 success Logs for test_progs on x86_64 with llvm-16

Commit Message

Donald Hunter Aug. 24, 2022, 10:10 p.m. UTC
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          | 36 ++++++++++++++++++++++
 Documentation/bpf/libbpf/index.rst         |  3 ++
 Documentation/bpf/libbpf/program_types.rst | 18 +++++++++++
 Documentation/bpf/programs.rst             |  3 ++
 5 files changed, 62 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/bpf/libbpf/Makefile
 create mode 100644 Documentation/bpf/libbpf/program_types.rst

Comments

Andrii Nakryiko Aug. 25, 2022, 8:35 p.m. UTC | #1
On Wed, Aug 24, 2022 at 3:30 PM 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          | 36 ++++++++++++++++++++++
>  Documentation/bpf/libbpf/index.rst         |  3 ++
>  Documentation/bpf/libbpf/program_types.rst | 18 +++++++++++
>  Documentation/bpf/programs.rst             |  3 ++
>  5 files changed, 62 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..c0c2811c4dd6
> --- /dev/null
> +++ b/Documentation/bpf/libbpf/Makefile
> @@ -0,0 +1,36 @@
> +# 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))
> +
> +$(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..2c04a9b3aa1f 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
>  ======
>
> @@ -9,6 +11,7 @@ libbpf
>     API Documentation <https://libbpf.readthedocs.io/en/latest/api.html>

I'd put program_types here, it's more relevant and important than
libbpf naming conventions

>     libbpf_naming_convention
>     libbpf_build
> +   program_types
>
>  This is documentation for libbpf, a userspace library for loading and
>  interacting with bpf programs.
> diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst
> new file mode 100644
> index 000000000000..dc65ede09eef
> --- /dev/null
> +++ b/Documentation/bpf/libbpf/program_types.rst
> @@ -0,0 +1,18 @@
> +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
> +
> +.. _program_types_and_elf:
> +
> +Program Types  and ELF Sections

nit: two spaces?

> +===============================
> +
> +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, e.g. ``SEC("tracepoint/syscalls/sys_enter_open")``

'/' is always going to be a type and "extras" separator, but extra
section format is not formalized. We have cases where it's all '/'s
(like tracepoint you mentioned), but newer and more complicated format
uses ':' as separator, e.g.
SEC("usdt/<path-to-binary>:<usdt_provide>:<usdt_name>") (let's mention
the latter as well to not create false impression of only ever having
'/' as separator)

> +
> +.. csv-table:: Program Types and Their ELF Section Names
> +   :file: ../../output/program_types.csv
> +   :widths: 40 30 20 10
> +   :header-rows: 1

it would be helpful to include a short snippet from generated CSV file
to give a general idea of the output

> 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.
> --
> 2.35.1
>
Donald Hunter Aug. 29, 2022, 8:26 a.m. UTC | #2
Andrii Nakryiko <andrii.nakryiko@gmail.com> writes:
>
>>  libbpf
>>  ======
>>
>> @@ -9,6 +11,7 @@ libbpf
>>     API Documentation <https://libbpf.readthedocs.io/en/latest/api.html>
>
> I'd put program_types here, it's more relevant and important than
> libbpf naming conventions

Good suggestion, thanks.

>>     libbpf_naming_convention
>>     libbpf_build
>> +   program_types
>>
>>  This is documentation for libbpf, a userspace library for loading and
>>  interacting with bpf programs.
>> diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst
>> new file mode 100644
>> index 000000000000..dc65ede09eef
>> --- /dev/null
>> +++ b/Documentation/bpf/libbpf/program_types.rst
>> @@ -0,0 +1,18 @@
>> +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
>> +
>> +.. _program_types_and_elf:
>> +
>> +Program Types  and ELF Sections
>
> nit: two spaces?

Ack.

>> +===============================
>> +
>> +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, e.g. ``SEC("tracepoint/syscalls/sys_enter_open")``
>
> '/' is always going to be a type and "extras" separator, but extra
> section format is not formalized. We have cases where it's all '/'s
> (like tracepoint you mentioned), but newer and more complicated format
> uses ':' as separator, e.g.
> SEC("usdt/<path-to-binary>:<usdt_provide>:<usdt_name>") (let's mention
> the latter as well to not create false impression of only ever having
> '/' as separator)

I will add a more detailed description extras format and include the
USDT example.

>> +
>> +.. csv-table:: Program Types and Their ELF Section Names
>> +   :file: ../../output/program_types.csv
>> +   :widths: 40 30 20 10
>> +   :header-rows: 1
>
> it would be helpful to include a short snippet from generated CSV file
> to give a general idea of the output

Ack.
diff mbox series

Patch

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..c0c2811c4dd6
--- /dev/null
+++ b/Documentation/bpf/libbpf/Makefile
@@ -0,0 +1,36 @@ 
+# 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))
+
+$(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..2c04a9b3aa1f 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
 ======
 
@@ -9,6 +11,7 @@  libbpf
    API Documentation <https://libbpf.readthedocs.io/en/latest/api.html>
    libbpf_naming_convention
    libbpf_build
+   program_types
 
 This is documentation for libbpf, a userspace library for loading and
 interacting with bpf programs.
diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst
new file mode 100644
index 000000000000..dc65ede09eef
--- /dev/null
+++ b/Documentation/bpf/libbpf/program_types.rst
@@ -0,0 +1,18 @@ 
+.. 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, e.g. ``SEC("tracepoint/syscalls/sys_enter_open")``
+
+.. 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.