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