Add table of BPF program types to docs
Subsystems (3)
v2 cover Add table of BPF program types to docs
Extend the libbpf documentation with a table of program types, attach points and ELF section names. The table uses data from program_types.csv which is generated from tools/lib/bpf/libbpf.c during the documentation build.
Patch 1 adds subdir support to Documentation/Makefile and changes userspace-api/media to use this instead of being a special case.
Patch 2 adds the the program_types documentation with a new makefile in the libbpf doc directory to generate program_types.csv
I plan to look at adding info about format of section "extras" as a follow-on.
v1 -> v2:
Automate the generation of program_types.csv as suggested by Andrii Nakryiko.
Donald Hunter (2):
Add subdir support to Documentation makefile
Add table of BPF program types to libbpf docs
Documentation/Makefile | 16 ++++++++-- Documentation/bpf/libbpf/Makefile | 36 ++++++++++++++++++++++ Documentation/bpf/libbpf/index.rst | 3 ++ Documentation/bpf/libbpf/program_types.rst | 18 +++++++++++ Documentation/bpf/programs.rst | 3 ++ Documentation/userspace-api/media/Makefile | 2 ++ 6 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 Documentation/bpf/libbpf/Makefile create mode 100644 Documentation/bpf/libbpf/program_types.rst
Signature · 1 line
2.35.1
PATCH v2 1/2 Add subdir support to Documentation makefile
Run make in list of subdirs to build generated sources and migrate userspace-api/media to use this instead of being a special case.
--- Documentation/Makefile | 15 +++++++++++++-- Documentation/userspace-api/media/Makefile | 2 ++ 2 files changed, 15 insertions(+), 2 deletions(-)
Documentation/Makefile +13 -2
@@ -65,6 +65,12 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # commands; the 'cmd' from scripts/Kbuild.include is not *loopable* loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; +BUILD_SUBDIRS = \ + Documentation/userspace-api/media + +quiet_cmd_build_subdir = SUBDIR $2 + cmd_build_subdir = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=$2 $3 + # $2 sphinx builder e.g. "html" # $3 name of the build subfolder / e.g. "userspace-api/media", used as: # * dest folder relative to $(BUILDDIR) and
@@ -74,7 +80,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; # e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) - cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ + cmd_sphinx = \ PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(PYTHON3) $(srctree)/scripts/jobserver-exec \
@@ -93,6 +99,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),html)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) linkcheckdocs:
@@ -100,6 +107,7 @@ linkcheckdocs: latexdocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),latex)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) ifeq ($(HAVE_PDFLATEX),0)
@@ -112,6 +120,7 @@ else # HAVE_PDFLATEX pdfdocs: latexdocs @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),latex)) $(foreach var,$(SPHINXDIRS), \ $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \ mkdir -p $(BUILDDIR)/$(var)/pdf; \
@@ -122,10 +131,12 @@ endif # HAVE_PDFLATEX epubdocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),epub)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),xml)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) endif # HAVE_SPHINX
@@ -138,7 +149,7 @@ refcheckdocs: cleandocs: $(Q)rm -rf $(BUILDDIR) - $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),clean)) dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:'
Documentation/userspace-api/media/Makefile +2 -0
@@ -50,6 +50,8 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception .PHONY: all html epub xml latex all: $(IMGDOT) $(BUILDDIR) ${TARGETS} + @: + html: all epub: all xml: all
Signature · 1 line
2.35.1
PATCH v2 2/2 Add table of BPF program types to libbpf docs
In reply to Donald HunterExtend 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.
--- 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
Documentation/Makefile +2 -1
@@ -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
Documentation/bpf/libbpf/Makefile new file +36 -0
@@ -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 $@
Documentation/bpf/libbpf/index.rst +3 -0
@@ -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.
Documentation/bpf/libbpf/program_types.rst new file +18 -0
@@ -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
Documentation/bpf/programs.rst +3 -0
@@ -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.
Signature · 1 line
2.35.1
Re: [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs
Quoted 86 lines · Donald Hunter
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.cduring the documentation build.Signed-off-by Donald Hunter <[email protected]>--- 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.rstDocumentation/Makefile +2
-1@@ -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 $3Documentation/bpf/libbpf/Makefile new file +36
-0@@ -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 $@Documentation/bpf/libbpf/index.rst +2
-0@@ -1,5 +1,7 @@ .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) +.. _libbpf: + libbpf ======
Documentation/bpf/libbpf/index.rst libbpf · line 11
Quoted 1 line
Documentation/bpf/libbpf/index.rst +0
-0@@ -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
Quoted 12 lines
Documentation/bpf/libbpf/index.rst +1
-0libbpf_naming_convention libbpf_build + program_types This is documentation for libbpf, a userspace library for loading and interacting with bpf programs.Documentation/bpf/libbpf/program_types.rst new file +0
-0
Documentation/bpf/libbpf/program_types.rst line 5
Quoted 5 lines
Documentation/bpf/libbpf/program_types.rst new file +5
-0@@ -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?
Documentation/bpf/libbpf/program_types.rst line 13
Quoted 8 lines
Documentation/bpf/libbpf/program_types.rst new file +8
-0+=============================== + +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)
Documentation/bpf/libbpf/program_types.rst line 18
Quoted 5 lines
Documentation/bpf/libbpf/program_types.rst new file +5
-0+ +.. 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
Quoted 14 lines
Documentation/bpf/programs.rst +3
-1@@ -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
Re: [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs
Quoted 9 lines · Andrii Nakryiko
Documentation/bpf/libbpf/index.rst libbpf · line 11
Quoted 6 lines
libbpf
======Documentation/bpf/libbpf/index.rst +0
-0@@ -9,6 +11,7 @@ libbpf API Documentation <https://libbpf.readthedocs.io/en/latest/api.html>I'd put
program_typeshere, it's more relevant and important than libbpf naming conventions
Good suggestion, thanks.
Quoted 4 lines
Quoted 4 lines
Documentation/bpf/libbpf/index.rst +1
-0libbpf_naming_convention libbpf_build + program_types
Quoted 15 lines
Documentation/bpf/libbpf/program_types.rst line 5
Quoted 13 lines
Documentation/bpf/libbpf/index.rst +0
-0This is documentation for libbpf, a userspace library for loading and interacting with bpf programs.Documentation/bpf/libbpf/program_types.rst new file +5
-0@@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + +.. _program_types_and_elf: + +Program Types and ELF Sectionsnit: two spaces?
Ack.
Quoted 9 lines
Documentation/bpf/libbpf/program_types.rst line 13
Quoted 8 lines
Documentation/bpf/libbpf/program_types.rst new file +8
-0+=============================== + +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")``
Quoted 7 lines
'/' 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.
Quoted 8 lines
Documentation/bpf/libbpf/program_types.rst line 18
Quoted 5 lines
Documentation/bpf/libbpf/program_types.rst new file +5
-0+ +.. csv-table:: Program Types and Their ELF Section Names + :file: ../../output/program_types.csv + :widths: 40 30 20 10 + :header-rows: 1it would be helpful to include a short snippet from generated CSV file to give a general idea of the output
Ack.