#
a70f5d84 |
| 31-Mar-2024 |
Rameez Rehman <rameezrehman408@hotmail.com> |
bpftool: Clean-up typos, punctuation, list formatting in docs
Improve the formatting of the attach flags for cgroup programs in the relevant man page, and fix typos ("can be on of", "an userspace in
bpftool: Clean-up typos, punctuation, list formatting in docs
Improve the formatting of the attach flags for cgroup programs in the relevant man page, and fix typos ("can be on of", "an userspace inet socket") when introducing that list. Also fix a couple of other trivial issues in docs.
[ Quentin: Fixed trival issues in bpftool-gen.rst and bpftool-iter.rst ]
Signed-off-by: Rameez Rehman <rameezrehman408@hotmail.com> Signed-off-by: Quentin Monnet <qmo@kernel.org> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20240331200346.29118-4-qmo@kernel.org
show more ...
|
#
ea379b3c |
| 31-Mar-2024 |
Rameez Rehman <rameezrehman408@hotmail.com> |
bpftool: Remove useless emphasis on command description in man pages
As it turns out, the terms in definition lists in the rST file are already rendered with bold-ish formatting when generating the
bpftool: Remove useless emphasis on command description in man pages
As it turns out, the terms in definition lists in the rST file are already rendered with bold-ish formatting when generating the man pages; all double-star sequences we have in the commands for the command description are unnecessary, and can be removed to make the documentation easier to read.
The rST files were automatically processed with:
sed -i '/DESCRIPTION/,/OPTIONS/ { /^\*/ s/\*\*//g }' b*.rst
Signed-off-by: Rameez Rehman <rameezrehman408@hotmail.com> Signed-off-by: Quentin Monnet <qmo@kernel.org> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20240331200346.29118-3-qmo@kernel.org
show more ...
|
#
f7b68543 |
| 31-Mar-2024 |
Rameez Rehman <rameezrehman408@hotmail.com> |
bpftool: Use simpler indentation in source rST for documentation
The rST manual pages for bpftool would use a mix of tabs and spaces for indentation. While this is the norm in C code, this is rather
bpftool: Use simpler indentation in source rST for documentation
The rST manual pages for bpftool would use a mix of tabs and spaces for indentation. While this is the norm in C code, this is rather unusual for rST documents, and over time we've seen many contributors use a wrong level of indentation for documentation update.
Let's fix bpftool's indentation in docs once and for all:
- Let's use spaces, that are more common in rST files. - Remove one level of indentation for the synopsis, the command description, and the "see also" section. As a result, all sections start with the same indentation level in the generated man page. - Rewrap the paragraphs after the changes.
There is no content change in this patch, only indentation and rewrapping changes. The wrapping in the generated source files for the manual pages is changed, but the pages displayed with "man" remain the same, apart from the adjusted indentation level on relevant sections.
[ Quentin: rebased on bpf-next, removed indent level for command description and options, updated synopsis, command summary, and "see also" sections. ]
Signed-off-by: Rameez Rehman <rameezrehman408@hotmail.com> Signed-off-by: Quentin Monnet <qmo@kernel.org> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20240331200346.29118-2-qmo@kernel.org
show more ...
|
#
f2e81192 |
| 29-Feb-2024 |
Kui-Feng Lee <thinker.li@gmail.com> |
bpftool: Add an example for struct_ops map and shadow type.
The example in bpftool-gen.8 explains how to use the pointer of the shadow type to change the value of a field of a struct_ops map.
Signe
bpftool: Add an example for struct_ops map and shadow type.
The example in bpftool-gen.8 explains how to use the pointer of the shadow type to change the value of a field of a struct_ops map.
Signed-off-by: Kui-Feng Lee <thinker.li@gmail.com> Signed-off-by: Andrii Nakryiko <andrii@kernel.org> Reviewed-by: Quentin Monnet <quentin@isovalent.com> Link: https://lore.kernel.org/bpf/20240229064523.2091270-5-thinker.li@gmail.com
show more ...
|
#
bbaf1ff0 |
| 24-Jun-2023 |
Fangrui Song <maskray@google.com> |
bpf: Replace deprecated -target with --target= for Clang
The -target option has been deprecated since clang 3.4 in 2013. Therefore, use the preferred --target=bpf form instead. This also matches how
bpf: Replace deprecated -target with --target= for Clang
The -target option has been deprecated since clang 3.4 in 2013. Therefore, use the preferred --target=bpf form instead. This also matches how we use --target= in scripts/Makefile.clang.
Signed-off-by: Fangrui Song <maskray@google.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: Yonghong Song <yhs@fb.com> Acked-by: Quentin Monnet <quentin@isovalent.com> Link: https://github.com/llvm/llvm-project/commit/274b6f0c87a6a1798de0a68135afc7f95def6277 Link: https://lore.kernel.org/bpf/20230624001856.1903733-1-maskray@google.com
show more ...
|
#
00389c58 |
| 16-Mar-2022 |
Delyan Kratunov <delyank@fb.com> |
bpftool: Add support for subskeletons
Subskeletons are headers which require an already loaded program to operate.
For example, when a BPF library is linked into a larger BPF object file, the libra
bpftool: Add support for subskeletons
Subskeletons are headers which require an already loaded program to operate.
For example, when a BPF library is linked into a larger BPF object file, the library userspace needs a way to access its own global variables without requiring knowledge about the larger program at build time.
As a result, subskeletons require a loaded bpf_object to open(). Further, they find their own symbols in the larger program by walking BTF type data at run time.
At this time, programs, maps, and globals are supported through non-owning pointers.
Signed-off-by: Delyan Kratunov <delyank@fb.com> Signed-off-by: Andrii Nakryiko <andrii@kernel.org> Link: https://lore.kernel.org/bpf/ca8a48b4841c72d285ecce82371bef4a899756cb.1647473511.git.delyank@fb.com
show more ...
|
#
1d1ffbf7 |
| 15-Feb-2022 |
Rafael David Tinoco <rafaeldtinoco@gmail.com> |
bpftool: Gen min_core_btf explanation and examples
Add "min_core_btf" feature explanation and one example of how to use it to bpftool-gen man page.
Signed-off-by: Mauricio Vásquez <mauricio@kinvolk
bpftool: Gen min_core_btf explanation and examples
Add "min_core_btf" feature explanation and one example of how to use it to bpftool-gen man page.
Signed-off-by: Mauricio Vásquez <mauricio@kinvolk.io> Signed-off-by: Rafael David Tinoco <rafael.tinoco@aquasec.com> Signed-off-by: Lorenzo Fontana <lorenzo.fontana@elastic.co> Signed-off-by: Leonardo Di Donato <leonardo.didonato@elastic.co> Signed-off-by: Andrii Nakryiko <andrii@kernel.org> Link: https://lore.kernel.org/bpf/20220215225856.671072-7-mauricio@kinvolk.io
show more ...
|
#
b6231815 |
| 15-Nov-2021 |
Quentin Monnet <quentin@isovalent.com> |
bpftool: Update doc (use susbtitutions) and test_bpftool_synctypes.py
test_bpftool_synctypes.py helps detecting inconsistencies in bpftool between the different list of types and options scattered i
bpftool: Update doc (use susbtitutions) and test_bpftool_synctypes.py
test_bpftool_synctypes.py helps detecting inconsistencies in bpftool between the different list of types and options scattered in the sources, the documentation, and the bash completion. For options that apply to all bpftool commands, the script had a hardcoded list of values, and would use them to check whether the man pages are up-to-date. When writing the script, it felt acceptable to have this list in order to avoid to open and parse bpftool's main.h every time, and because the list of global options in bpftool doesn't change so often.
However, this is prone to omissions, and we recently added a new -l|--legacy option which was described in common_options.rst, but not listed in the options summary of each manual page. The script did not complain, because it keeps comparing the hardcoded list to the (now) outdated list in the header file.
To address the issue, this commit brings the following changes:
- Options that are common to all bpftool commands (--json, --pretty, and --debug) are moved to a dedicated file, and used in the definition of a RST substitution. This substitution is used in the sources of all the man pages.
- This list of common options is updated, with the addition of the new -l|--legacy option.
- The script test_bpftool_synctypes.py is updated to compare: - Options specific to a command, found in C files, for the interactive help messages, with the same specific options from the relevant man page for that command. - Common options, checked just once: the list in main.h is compared with the new list in substitutions.rst.
Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20211115225844.33943-3-quentin@isovalent.com
show more ...
|
#
43448428 |
| 15-Nov-2021 |
Quentin Monnet <quentin@isovalent.com> |
bpftool: Add SPDX tags to RST documentation files
Most files in the kernel repository have a SPDX tags. The files that don't have such a tag (or another license boilerplate) tend to fall under the G
bpftool: Add SPDX tags to RST documentation files
Most files in the kernel repository have a SPDX tags. The files that don't have such a tag (or another license boilerplate) tend to fall under the GPL-2.0 license. In the past, bpftool's Makefile (for example) has been marked as GPL-2.0 for that reason, when in fact all bpftool is dual-licensed.
To prevent a similar confusion from happening with the RST documentation files for bpftool, let's explicitly mark all files as dual-licensed.
Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20211115225844.33943-2-quentin@isovalent.com
show more ...
|
#
986dec18 |
| 10-Nov-2021 |
Quentin Monnet <quentin@isovalent.com> |
bpftool: Fix indent in option lists in the documentation
Mixed indentation levels in the lists of options in bpftool's documentation produces some unexpected results. For the "bpftool" man page, it
bpftool: Fix indent in option lists in the documentation
Mixed indentation levels in the lists of options in bpftool's documentation produces some unexpected results. For the "bpftool" man page, it prints a warning:
$ make -C bpftool.8 GEN bpftool.8 <stdin>:26: (ERROR/3) Unexpected indentation.
For other pages, there is no warning, but it results in a line break appearing in the option lists in the generated man pages.
RST paragraphs should have a uniform indentation level. Let's fix it.
Fixes: c07ba629df97 ("tools: bpftool: Update and synchronise option list in doc and help msg") Fixes: 8cc8c6357c8f ("tools: bpftool: Document and add bash completion for -L, -B options") Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Andrii Nakryiko <andrii@kernel.org> Link: https://lore.kernel.org/bpf/20211110114632.24537-5-quentin@isovalent.com
show more ...
|
#
8cc8c635 |
| 30-Jul-2021 |
Quentin Monnet <quentin@isovalent.com> |
tools: bpftool: Document and add bash completion for -L, -B options
The -L|--use-loader option for using loader programs when loading, or when generating a skeleton, did not have any documentation o
tools: bpftool: Document and add bash completion for -L, -B options
The -L|--use-loader option for using loader programs when loading, or when generating a skeleton, did not have any documentation or bash completion. Same thing goes for -B|--base-btf, used to pass a path to a base BTF object for split BTF such as BTF for kernel modules.
This patch documents and adds bash completion for those options.
Fixes: 75fa1777694c ("tools/bpftool: Add bpftool support for split BTF") Fixes: d510296d331a ("bpftool: Use syscall/loader program in "prog load" and "gen skeleton" command.") Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Andrii Nakryiko <andrii@kernel.org> Link: https://lore.kernel.org/bpf/20210730215435.7095-7-quentin@isovalent.com
show more ...
|
#
c07ba629 |
| 30-Jul-2021 |
Quentin Monnet <quentin@isovalent.com> |
tools: bpftool: Update and synchronise option list in doc and help msg
All bpftool commands support the options for JSON output and debug from libbpf. In addition, some commands support additional o
tools: bpftool: Update and synchronise option list in doc and help msg
All bpftool commands support the options for JSON output and debug from libbpf. In addition, some commands support additional options corresponding to specific use cases.
The list of options described in the man pages for the different commands are not always accurate. The messages for interactive help are mostly limited to HELP_SPEC_OPTIONS, and are even less representative of the actual set of options supported for the commands.
Let's update the lists:
- HELP_SPEC_OPTIONS is modified to contain the "default" options (JSON and debug), and to be extensible (no ending curly bracket). - All commands use HELP_SPEC_OPTIONS in their help message, and then complete the list with their specific options. - The lists of options in the man pages are updated. - The formatting of the list for bpftool.rst is adjusted to match formatting for the other man pages. This is for consistency, and also because it will be helpful in a future patch to automatically check that the files are synchronised.
Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Andrii Nakryiko <andrii@kernel.org> Link: https://lore.kernel.org/bpf/20210730215435.7095-5-quentin@isovalent.com
show more ...
|
#
d80b2fcb |
| 18-Mar-2021 |
Andrii Nakryiko <andrii@kernel.org> |
bpftool: Add `gen object` command to perform BPF static linking
Add `bpftool gen object <output-file> <input_file>...` command to statically link multiple BPF ELF object files into a single output B
bpftool: Add `gen object` command to perform BPF static linking
Add `bpftool gen object <output-file> <input_file>...` command to statically link multiple BPF ELF object files into a single output BPF ELF object file.
This patch also updates bash completions and man page. Man page gets a short section on `gen object` command, but also updates the skeleton example to show off workflow for BPF application with two .bpf.c files, compiled individually with Clang, then resulting object files are linked together with `gen object`, and then final object file is used to generate usable BPF skeleton. This should help new users understand realistic workflow w.r.t. compiling mutli-file BPF application.
Signed-off-by: Andrii Nakryiko <andrii@kernel.org> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Reviewed-by: Quentin Monnet <quentin@isovalent.com> Link: https://lore.kernel.org/bpf/20210318194036.3521577-10-andrii@kernel.org
show more ...
|
#
c4122665 |
| 18-Mar-2021 |
Andrii Nakryiko <andrii@kernel.org> |
bpftool: Add ability to specify custom skeleton object name
Add optional name OBJECT_NAME parameter to `gen skeleton` command to override default object name, normally derived from input file name.
bpftool: Add ability to specify custom skeleton object name
Add optional name OBJECT_NAME parameter to `gen skeleton` command to override default object name, normally derived from input file name. This allows much more flexibility during build time.
Signed-off-by: Andrii Nakryiko <andrii@kernel.org> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Link: https://lore.kernel.org/bpf/20210318194036.3521577-9-andrii@kernel.org
show more ...
|
#
18841da9 |
| 10-Sep-2020 |
Quentin Monnet <quentin@isovalent.com> |
tools: bpftool: Automate generation for "SEE ALSO" sections in man pages
The "SEE ALSO" sections of bpftool's manual pages refer to bpf(2), bpf-helpers(7), then all existing bpftool man pages (save
tools: bpftool: Automate generation for "SEE ALSO" sections in man pages
The "SEE ALSO" sections of bpftool's manual pages refer to bpf(2), bpf-helpers(7), then all existing bpftool man pages (save the current one).
This leads to nearly-identical lists being duplicated in all manual pages. Ideally, when a new page is created, all lists should be updated accordingly, but this has led to omissions and inconsistencies multiple times in the past.
Let's take it out of the RST files and generate the "SEE ALSO" sections automatically in the Makefile when generating the man pages. The lists are not really useful in the RST anyway because all other pages are available in the same directory.
v3: - Fix conflict with a previous patchset that introduced RST2MAN_OPTS variable passed to rst2man.
v2: - Use "echo -n" instead of "printf" in Makefile, to avoid any risk of passing a format string directly to the command.
Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Andrii Nakryiko <andriin@fb.com> Link: https://lore.kernel.org/bpf/20200910203935.25304-1-quentin@isovalent.com
show more ...
|
#
f28ef96d |
| 09-Sep-2020 |
Quentin Monnet <quentin@isovalent.com> |
tools: bpftool: Include common options from separate file
Nearly all man pages for bpftool have the same common set of option flags (--help, --version, --json, --pretty, --debug). The description is
tools: bpftool: Include common options from separate file
Nearly all man pages for bpftool have the same common set of option flags (--help, --version, --json, --pretty, --debug). The description is duplicated across all the pages, which is more difficult to maintain if the description of an option changes. It may also be confusing to sort out what options are not "common" and should not be copied when creating new manual pages.
Let's move the description for those common options to a separate file, which is included with a RST directive when generating the man pages.
Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Andrii Nakryiko <andriin@fb.com> Link: https://lore.kernel.org/bpf/20200909162500.17010-3-quentin@isovalent.com
show more ...
|
#
16f3ddfb |
| 09-Sep-2020 |
Quentin Monnet <quentin@isovalent.com> |
tools: bpftool: Log info-level messages when building bpftool man pages
To build man pages for bpftool (and for eBPF helper functions), rst2man can log different levels of information. Let's make it
tools: bpftool: Log info-level messages when building bpftool man pages
To build man pages for bpftool (and for eBPF helper functions), rst2man can log different levels of information. Let's make it log all levels to keep the RST files clean.
Doing so, rst2man complains about double colons, used for literal blocks, that look like underlines for section titles. Let's add the necessary blank lines.
v2: - Use "--verbose" instead of "-r 1" (same behaviour but more readable). - Pass it through a RST2MAN_OPTS variable so we can easily pass other options too.
Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Andrii Nakryiko <andriin@fb.com> Link: https://lore.kernel.org/bpf/20200909162251.15498-2-quentin@isovalent.com
show more ...
|
#
c8caa0bb |
| 11-May-2020 |
Quentin Monnet <quentin@isovalent.com> |
tools, bpftool: Minor fixes for documentation
Bring minor improvements to bpftool documentation. Fix or harmonise formatting, update map types (including in interactive help), improve description fo
tools, bpftool: Minor fixes for documentation
Bring minor improvements to bpftool documentation. Fix or harmonise formatting, update map types (including in interactive help), improve description for "map create", fix a build warning due to a missing line after the double-colon for the "bpftool prog profile" example, complete/harmonise/sort the list of related bpftool man pages in footers.
v2: - Remove (instead of changing) mark-up on "value" in bpftool-map.rst, when it does not refer to something passed on the command line. - Fix an additional typo ("hexadeximal") in the same file.
Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20200511161536.29853-3-quentin@isovalent.com
show more ...
|
#
229c3b47 |
| 20-Jan-2020 |
Toke Høiland-Jørgensen <toke@redhat.com> |
bpftool: Use consistent include paths for libbpf
Fix bpftool to include libbpf header files with the bpf/ prefix, to be consistent with external users of the library. Also ensure that all includes o
bpftool: Use consistent include paths for libbpf
Fix bpftool to include libbpf header files with the bpf/ prefix, to be consistent with external users of the library. Also ensure that all includes of exported libbpf header files (those that are exported on 'make install' of the library) use bracketed includes instead of quoted.
To make sure no new files are introduced that doesn't include the bpf/ prefix in its include, remove tools/lib/bpf from the include path entirely, and use tools/lib instead.
Fixes: 6910d7d3867a ("selftests/bpf: Ensure bpf_helper_defs.h are taken from selftests dir") Signed-off-by: Toke Høiland-Jørgensen <toke@redhat.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Andrii Nakryiko <andriin@fb.com> Link: https://lore.kernel.org/bpf/157952560684.1683545.4765181397974997027.stgit@toke.dk
show more ...
|
#
dacce641 |
| 18-Dec-2019 |
Andrii Nakryiko <andriin@fb.com> |
bpftool: Work-around rst2man conversion bug
Work-around what appears to be a bug in rst2man convertion tool, used to create man pages out of reStructureText-formatted documents. If text line starts
bpftool: Work-around rst2man conversion bug
Work-around what appears to be a bug in rst2man convertion tool, used to create man pages out of reStructureText-formatted documents. If text line starts with dot, rst2man will put it in resulting man file verbatim. This seems to cause man tool to interpret it as a directive/command (e.g., `.bs`), and subsequently not render entire line because it's unrecognized one.
Enclose '.xxx' words in extra formatting to work around.
Fixes: cb21ac588546 ("bpftool: Add gen subcommand manpage") Reported-by: Alexei Starovoitov <ast@kernel.org> Signed-off-by: Andrii Nakryiko <andriin@fb.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Yonghong Song <yhs@fb.com Link: https://lore.kernel.org/bpf/20191218221707.2552199-1-andriin@fb.com
show more ...
|
#
cb21ac58 |
| 18-Dec-2019 |
Andrii Nakryiko <andriin@fb.com> |
bpftool: Add gen subcommand manpage
Add bpftool-gen.rst describing skeleton on the high level. Also include a small, but complete, example BPF app (BPF side, userspace side, generated skeleton) in e
bpftool: Add gen subcommand manpage
Add bpftool-gen.rst describing skeleton on the high level. Also include a small, but complete, example BPF app (BPF side, userspace side, generated skeleton) in example section to demonstrate skeleton API and its usage.
Signed-off-by: Andrii Nakryiko <andriin@fb.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Yonghong Song <yhs@fb.com> Link: https://lore.kernel.org/bpf/20191218052552.2915188-4-andriin@fb.com
show more ...
|