linux-dev/tools/bpf/bpftool/Documentation, branch master

bpf: Define new BPF_MAP_TYPE_USER_RINGBUF map type

2022-09-21T23:24:17Z

We want to support a ringbuf map type where samples are published from user-space, to be consumed by BPF programs. BPF currently supports a kernel -> user-space circular ring buffer via the BPF_MAP_TYPE_RINGBUF map type. We'll need to define a new map type for user-space -> kernel, as none of the helpers exported for BPF_MAP_TYPE_RINGBUF will apply to a user-space producer ring buffer, and we'll want to add one or more helper functions that would not apply for a kernel-producer ring buffer. This patch therefore adds a new BPF_MAP_TYPE_USER_RINGBUF map type definition. The map type is useless in its current form, as there is no way to access or use it for anything until we one or more BPF helpers. A follow-on patch will therefore add a new helper function that allows BPF programs to run callbacks on samples that are published to the ring buffer. Signed-off-by: David Vernet Signed-off-by: Andrii Nakryiko Acked-by: Andrii Nakryiko Link: https://lore.kernel.org/bpf/20220920000100.477320-2-void@manifault.com

bpftool: Rename "bpftool feature list" into "... feature list_builtins"

2022-07-05T09:53:54Z

To make it more explicit that the features listed with "bpftool feature list" are known to bpftool, but not necessary available on the system (as opposed to the probed features), rename the "feature list" command into "feature list_builtins". Note that "bpftool feature list" still works as before given that we recognise arguments from their prefixes; but the real name of the subcommand, in particular as displayed in the man page or the interactive help, will now include "_builtins". Since we update the bash completion accordingly, let's also take this chance to redirect error output to /dev/null in the completion script, to avoid displaying unexpected error messages when users attempt to tab-complete. Suggested-by: Daniel Borkmann Signed-off-by: Quentin Monnet Signed-off-by: Daniel Borkmann Acked-by: Yonghong Song Link: https://lore.kernel.org/bpf/20220701093805.16920-1-quentin@isovalent.com

bpftool: Add feature list (prog/map/link/attach types, helpers)

2022-06-30T14:17:03Z

Add a "bpftool feature list" subcommand to list BPF "features". Contrarily to "bpftool feature probe", this is not about the features available on the system. Instead, it lists all features known to bpftool from compilation time; in other words, all program, map, attach, link types known to the libbpf version in use, and all helpers found in the UAPI BPF header. The first use case for this feature is bash completion: running the command provides a list of types that can be used to produce the list of candidate map types, for example. Now that bpftool uses "standard" names provided by libbpf for the program, map, link, and attach types, having the ability to list these types and helpers could also be useful in scripts to loop over existing items. Sample output: # bpftool feature list prog_types | grep -vw unspec | head -n 6 socket_filter kprobe sched_cls sched_act tracepoint xdp # bpftool -p feature list map_types | jq '.[1]' "hash" # bpftool feature list attach_types | grep '^cgroup_' cgroup_inet_ingress cgroup_inet_egress [...] cgroup_inet_sock_release # bpftool feature list helpers | grep -vw bpf_unspec | wc -l 207 The "unspec" types and helpers are not filtered out by bpftool, so as to remain closer to the enums, and to preserve the indices in the JSON arrays (e.g. "hash" at index 1 == BPF_MAP_TYPE_HASH in map types list). Signed-off-by: Quentin Monnet Signed-off-by: Daniel Borkmann Acked-by: Daniel Müller Link: https://lore.kernel.org/bpf/20220629203637.138944-2-quentin@isovalent.com

bpftool: Use libbpf_bpf_attach_type_str

2022-06-02T23:26:30Z

This change switches bpftool over to using the recently introduced libbpf_bpf_attach_type_str function instead of maintaining its own string representation for the bpf_attach_type enum. Note that contrary to other enum types, the variant names that bpftool maps bpf_attach_type to do not adhere a simple to follow rule. With bpf_prog_type, for example, the textual representation can easily be inferred by stripping the BPF_PROG_TYPE_ prefix and lowercasing the remaining string. bpf_attach_type violates this rule for various variants. We decided to fix up this deficiency with this change, meaning that bpftool uses the same textual representations as libbpf. Supporting tests, completion scripts, and man pages have been adjusted accordingly. However, we did add support for accepting (the now undocumented) original attach type names when they are provided by users. For the test (test_bpftool_synctypes.py), I have removed the enum representation checks, because we no longer mirror the various enum variant names in bpftool source code. For the man page, help text, and completion script checks we are now using enum definitions from uapi/linux/bpf.h as the source of truth directly. Signed-off-by: Daniel Müller Signed-off-by: Andrii Nakryiko Acked-by: Quentin Monnet Link: https://lore.kernel.org/bpf/20220523230428.3077108-10-deso@posteo.net

bpftool: Add support for subskeletons

2022-03-18T06:12:39Z

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 Signed-off-by: Andrii Nakryiko Link: https://lore.kernel.org/bpf/ca8a48b4841c72d285ecce82371bef4a899756cb.1647473511.git.delyank@fb.com

bpftool: man: Add missing top level docs

2022-03-15T22:51:41Z

The top-level (bpftool.8) man page was missing docs for a few subcommands and their respective sub-sub-commands. This commit brings the top level man page up to date. Note that I've kept the ordering of the subcommands the same as in `bpftool help`. Signed-off-by: Daniel Xu Signed-off-by: Andrii Nakryiko Link: https://lore.kernel.org/bpf/3049ef5dc509c0d1832f0a8b2dba2ccaad0af688.1647213551.git.dxu@dxuuu.xyz

bpftool: Gen min_core_btf explanation and examples

2022-02-16T18:13:21Z

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 Signed-off-by: Rafael David Tinoco Signed-off-by: Lorenzo Fontana Signed-off-by: Leonardo Di Donato Signed-off-by: Andrii Nakryiko Link: https://lore.kernel.org/bpf/20220215225856.671072-7-mauricio@kinvolk.io

bpftool: Add libbpf's version number to "bpftool version" output

2022-02-11T05:09:47Z

To help users check what version of libbpf is being used with bpftool, print the number along with bpftool's own version number. Output: $ ./bpftool version ./bpftool v5.16.0 using libbpf v0.7 features: libbfd, libbpf_strict, skeletons $ ./bpftool version --json --pretty { "version": "5.16.0", "libbpf_version": "0.7", "features": { "libbfd": true, "libbpf_strict": true, "skeletons": true } } Note that libbpf does not expose its patch number. Signed-off-by: Quentin Monnet Signed-off-by: Andrii Nakryiko Link: https://lore.kernel.org/bpf/20220210104237.11649-2-quentin@isovalent.com

bpftool: Update doc (use susbtitutions) and test_bpftool_synctypes.py

2021-11-16T12:56:22Z

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 Signed-off-by: Daniel Borkmann Link: https://lore.kernel.org/bpf/20211115225844.33943-3-quentin@isovalent.com

bpftool: Add SPDX tags to RST documentation files

2021-11-16T12:56:22Z

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 Signed-off-by: Daniel Borkmann Link: https://lore.kernel.org/bpf/20211115225844.33943-2-quentin@isovalent.com