* [PATCH bpf-next v2 0/2] Add table of BPF program types to docs
@ 2022-08-24 22:10 Donald Hunter
2022-08-24 22:10 ` [PATCH bpf-next v2 1/2] Add subdir support to Documentation makefile Donald Hunter
2022-08-24 22:10 ` [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs Donald Hunter
0 siblings, 2 replies; 5+ messages in thread
From: Donald Hunter @ 2022-08-24 22:10 UTC (permalink / raw)
To: bpf, linux-doc, Jonathan Corbet; +Cc: Donald Hunter
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
--
2.35.1
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH bpf-next v2 1/2] Add subdir support to Documentation makefile
2022-08-24 22:10 [PATCH bpf-next v2 0/2] Add table of BPF program types to docs Donald Hunter
@ 2022-08-24 22:10 ` Donald Hunter
2022-08-24 22:10 ` [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs Donald Hunter
1 sibling, 0 replies; 5+ messages in thread
From: Donald Hunter @ 2022-08-24 22:10 UTC (permalink / raw)
To: bpf, linux-doc, Jonathan Corbet; +Cc: Donald Hunter
Run make in list of subdirs to build generated sources and migrate
userspace-api/media to use this instead of being a special case.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
---
Documentation/Makefile | 15 +++++++++++++--
Documentation/userspace-api/media/Makefile | 2 ++
2 files changed, 15 insertions(+), 2 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64d44c1ecad3..8a63ef2dcd1c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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:'
diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile
index 00922aa7efde..783c6f880b72 100644
--- a/Documentation/userspace-api/media/Makefile
+++ b/Documentation/userspace-api/media/Makefile
@@ -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
--
2.35.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs
2022-08-24 22:10 [PATCH bpf-next v2 0/2] Add table of BPF program types to docs Donald Hunter
2022-08-24 22:10 ` [PATCH bpf-next v2 1/2] Add subdir support to Documentation makefile Donald Hunter
@ 2022-08-24 22:10 ` Donald Hunter
2022-08-25 20:35 ` Andrii Nakryiko
1 sibling, 1 reply; 5+ messages in thread
From: Donald Hunter @ 2022-08-24 22:10 UTC (permalink / raw)
To: bpf, linux-doc, Jonathan Corbet; +Cc: 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.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>
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.
--
2.35.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs
2022-08-24 22:10 ` [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs Donald Hunter
@ 2022-08-25 20:35 ` Andrii Nakryiko
2022-08-29 8:26 ` Donald Hunter
0 siblings, 1 reply; 5+ messages in thread
From: Andrii Nakryiko @ 2022-08-25 20:35 UTC (permalink / raw)
To: Donald Hunter; +Cc: bpf, linux-doc, Jonathan Corbet
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
>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs
2022-08-25 20:35 ` Andrii Nakryiko
@ 2022-08-29 8:26 ` Donald Hunter
0 siblings, 0 replies; 5+ messages in thread
From: Donald Hunter @ 2022-08-29 8:26 UTC (permalink / raw)
To: Andrii Nakryiko; +Cc: bpf, linux-doc, Jonathan Corbet
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.
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2022-08-29 8:51 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-08-24 22:10 [PATCH bpf-next v2 0/2] Add table of BPF program types to docs Donald Hunter
2022-08-24 22:10 ` [PATCH bpf-next v2 1/2] Add subdir support to Documentation makefile Donald Hunter
2022-08-24 22:10 ` [PATCH bpf-next v2 2/2] Add table of BPF program types to libbpf docs Donald Hunter
2022-08-25 20:35 ` Andrii Nakryiko
2022-08-29 8:26 ` Donald Hunter
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).