| Message ID | 20220922115257.99815-3-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Changes Requested |
| Delegated to: | BPF |
| Headers | show |
| Series | Add table of BPF program types to docs | expand |
On Thu, Sep 22, 2022 at 12:52:57PM +0100, Donald Hunter wrote: > +.. > + program_types.csv is generated from tools/lib/bpf/libbpf.c and is formatted 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 The note above doesn't get rendered on htmldocs output, so I have applied the fixup: ---- >8 ---- diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst index b74fbf3363dd6c..3ce0ec94b399b4 100644 --- a/Documentation/bpf/libbpf/program_types.rst +++ b/Documentation/bpf/libbpf/program_types.rst @@ -16,15 +16,17 @@ When ``extras`` are specified, they provide details of how to auto-attach the BP 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 formatted 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 +.. note:: + The table below is generated from ``tools/lib/bpf/libbpf.c`` and is + formatted like this (in CSV format):: + + 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: program_types.csv Thanks.
Bagas Sanjaya <bagasdotme@gmail.com> writes: > On Thu, Sep 22, 2022 at 12:52:57PM +0100, Donald Hunter wrote: >> +.. >> + program_types.csv is generated from tools/lib/bpf/libbpf.c and is formatted 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 > > The note above doesn't get rendered on htmldocs output, so I have applied > the fixup: It was intended to be a comment to the reader of program_types.rst that this is the format of the .csv file that will be rendered. It was not meant to be a note on the rendered page. The rendered page will show the table that is produced by the csv-table directive which is self explanatory. > > ---- >8 ---- > > diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst > index b74fbf3363dd6c..3ce0ec94b399b4 100644 > --- a/Documentation/bpf/libbpf/program_types.rst > +++ b/Documentation/bpf/libbpf/program_types.rst > @@ -16,15 +16,17 @@ When ``extras`` are specified, they provide details of how to auto-attach the BP > 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 formatted 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 > +.. note:: > + The table below is generated from ``tools/lib/bpf/libbpf.c`` and is > + formatted like this (in CSV format):: > + > + 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: program_types.csv > > Thanks.
On 9/23/22 22:05, Donald Hunter wrote: >> The note above doesn't get rendered on htmldocs output, so I have applied >> the fixup: > > It was intended to be a comment to the reader of program_types.rst that > this is the format of the .csv file that will be rendered. It was not > meant to be a note on the rendered page. > > The rendered page will show the table that is produced by the csv-table > directive which is self explanatory. > AFAIK, I don't see any disclaimer for that table...
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/.gitignore b/Documentation/bpf/libbpf/.gitignore new file mode 100644 index 000000000000..c9013b8cae08 --- /dev/null +++ b/Documentation/bpf/libbpf/.gitignore @@ -0,0 +1 @@ +/program_types.csv diff --git a/Documentation/bpf/libbpf/Makefile b/Documentation/bpf/libbpf/Makefile new file mode 100644 index 000000000000..9cc3f67b5602 --- /dev/null +++ b/Documentation/bpf/libbpf/Makefile @@ -0,0 +1,29 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Rules to convert BPF program types in tools/lib/bpf/libbpf.c +# into a .csv file + +PROGRAM_TYPES = $(srctree)/Documentation/bpf/libbpf/program_types.csv + +TARGETS := $(PROGRAM_TYPES) + + +$(PROGRAM_TYPES): $(srctree)/tools/lib/bpf/libbpf.c + $(Q)$(srctree)/scripts/gen-bpf-progtypes.sh $< $@ + +.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..b74fbf3363dd --- /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 formatted 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: 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. diff --git a/scripts/gen-bpf-progtypes.sh b/scripts/gen-bpf-progtypes.sh new file mode 100755 index 000000000000..3bf36f26a2f7 --- /dev/null +++ b/scripts/gen-bpf-progtypes.sh @@ -0,0 +1,34 @@ +#!/bin/bash +# SPDX-License-Identifier: GPL-2.0-only +# +# Copyright (C) 2022 Red Hat. +# +# Generate a .csv table of BPF program types + +if [ "$#" -lt 2 ]; then + echo "Usage: gen-bpf-progtypes.sh </path/to/libbpf.c> </path/to/generated.csv>" + exit 1 +fi + +# Extract program types and properties from the section definitions in libbpf.c such as +# SEC_DEF("socket", SOCKET_FILTER, 0, SEC_NONE) to generate a table of program types in +# .csv format. +# +# 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 + +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 }' $1 | sort > $2
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/.gitignore | 1 + Documentation/bpf/libbpf/Makefile | 29 ++++++++++++++++++ Documentation/bpf/libbpf/index.rst | 3 ++ Documentation/bpf/libbpf/program_types.rst | 32 ++++++++++++++++++++ Documentation/bpf/programs.rst | 3 ++ scripts/gen-bpf-progtypes.sh | 34 ++++++++++++++++++++++ 7 files changed, 104 insertions(+), 1 deletion(-) create mode 100644 Documentation/bpf/libbpf/.gitignore create mode 100644 Documentation/bpf/libbpf/Makefile create mode 100644 Documentation/bpf/libbpf/program_types.rst create mode 100755 scripts/gen-bpf-progtypes.sh