iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bpftool: Use simpler indentation in source rST for documentation

Browse Source 
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
This commit is contained in:
Rameez Rehman 2024-03-31 21:03:44 +01:00 committed by Daniel Borkmann
parent 623bdd58be
commit f7b6854364
14 changed files with 811 additions and 894 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
tools/bpf/bpftool/Documentation/Makefile
View File

@ -31,9 +31,9 @@ see_also = $(subst " ",, \
"\n" \
"SEE ALSO\n" \
"========\n" \
"\t**bpf**\ (2),\n" \
"\t**bpf-helpers**\\ (7)" \
$(foreach page,$(call list_pages,$(1)),",\n\t**$(page)**\\ (8)") \
"**bpf**\ (2),\n" \
"**bpf-helpers**\\ (7)" \
$(foreach page,$(call list_pages,$(1)),",\n**$(page)**\\ (8)") \
"\n")
$(OUTPUT)%.8: %.rst

66
tools/bpf/bpftool/Documentation/bpftool-btf.rst
View File

@ -35,40 +35,35 @@ BTF COMMANDS
DESCRIPTION
===========
**bpftool btf { show | list }** [**id** *BTF_ID*]
Show information about loaded BTF objects. If a BTF ID is
specified, show information only about given BTF object,
otherwise list all BTF objects currently loaded on the
system.
Show information about loaded BTF objects. If a BTF ID is specified, show
information only about given BTF object, otherwise list all BTF objects
currently loaded on the system.
Since Linux 5.8 bpftool is able to discover information about
processes that hold open file descriptors (FDs) against BTF
objects. On such kernels bpftool will automatically emit this
information as well.
Since Linux 5.8 bpftool is able to discover information about processes
that hold open file descriptors (FDs) against BTF objects. On such kernels
bpftool will automatically emit this information as well.
**bpftool btf dump** *BTF_SRC*
Dump BTF entries from a given *BTF_SRC*.
When **id** is specified, BTF object with that ID will be
loaded and all its BTF types emitted.
When **id** is specified, BTF object with that ID will be loaded and all
its BTF types emitted.
When **map** is provided, it's expected that map has
associated BTF object with BTF types describing key and
value. It's possible to select whether to dump only BTF
type(s) associated with key (**key**), value (**value**),
both key and value (**kv**), or all BTF types present in
associated BTF object (**all**). If not specified, **kv**
is assumed.
When **map** is provided, it's expected that map has associated BTF object
with BTF types describing key and value. It's possible to select whether to
dump only BTF type(s) associated with key (**key**), value (**value**),
both key and value (**kv**), or all BTF types present in associated BTF
object (**all**). If not specified, **kv** is assumed.
When **prog** is provided, it's expected that program has
associated BTF object with BTF types.
When **prog** is provided, it's expected that program has associated BTF
object with BTF types.
When specifying *FILE*, an ELF file is expected, containing
.BTF section with well-defined BTF binary format data,
typically produced by clang or pahole.
When specifying *FILE*, an ELF file is expected, containing .BTF section
with well-defined BTF binary format data, typically produced by clang or
pahole.
**format** option can be used to override default (raw)
output format. Raw (**raw**) or C-syntax (**c**) output
formats are supported.
**format** option can be used to override default (raw) output format. Raw
(**raw**) or C-syntax (**c**) output formats are supported.
**bpftool btf help**
Print short help message.
@ -78,18 +73,17 @@ OPTIONS
.. include:: common_options.rst
-B, --base-btf *FILE*
Pass a base BTF object. Base BTF objects are typically used
with BTF objects for kernel modules. To avoid duplicating
all kernel symbols required by modules, BTF objects for
modules are "split", they are built incrementally on top of
the kernel (vmlinux) BTF object. So the base BTF reference
should usually point to the kernel BTF.
Pass a base BTF object. Base BTF objects are typically used with BTF
objects for kernel modules. To avoid duplicating all kernel symbols
required by modules, BTF objects for modules are "split", they are
built incrementally on top of the kernel (vmlinux) BTF object. So the
base BTF reference should usually point to the kernel BTF.
When the main BTF object to process (for example, the
module BTF to dump) is passed as a *FILE*, bpftool attempts
to autodetect the path for the base object, and passing
this option is optional. When the main BTF object is passed
through other handles, this option becomes necessary.
When the main BTF object to process (for example, the module BTF to
dump) is passed as a *FILE*, bpftool attempts to autodetect the path
for the base object, and passing this option is optional. When the main
BTF object is passed through other handles, this option becomes
necessary.
EXAMPLES
========

82
tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
View File

@ -52,46 +52,43 @@ DESCRIPTION
**bpftool cgroup { show | list }** *CGROUP* [**effective**]
List all programs attached to the cgroup *CGROUP*.
Output will start with program ID followed by attach type,
attach flags and program name.
Output will start with program ID followed by attach type, attach flags and
program name.
If **effective** is specified retrieve effective programs that
will execute for events within a cgroup. This includes
inherited along with attached ones.
If **effective** is specified retrieve effective programs that will execute
for events within a cgroup. This includes inherited along with attached
ones.
**bpftool cgroup tree** [*CGROUP_ROOT*] [**effective**]
Iterate over all cgroups in *CGROUP_ROOT* and list all
attached programs. If *CGROUP_ROOT* is not specified,
bpftool uses cgroup v2 mountpoint.
Iterate over all cgroups in *CGROUP_ROOT* and list all attached programs.
If *CGROUP_ROOT* is not specified, bpftool uses cgroup v2 mountpoint.
The output is similar to the output of cgroup show/list
commands: it starts with absolute cgroup path, followed by
program ID, attach type, attach flags and program name.
The output is similar to the output of cgroup show/list commands: it starts
with absolute cgroup path, followed by program ID, attach type, attach
flags and program name.
If **effective** is specified retrieve effective programs that
will execute for events within a cgroup. This includes
inherited along with attached ones.
If **effective** is specified retrieve effective programs that will execute
for events within a cgroup. This includes inherited along with attached
ones.
**bpftool cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
Attach program *PROG* to the cgroup *CGROUP* with attach type
*ATTACH_TYPE* and optional *ATTACH_FLAGS*.
Attach program *PROG* to the cgroup *CGROUP* with attach type *ATTACH_TYPE*
and optional *ATTACH_FLAGS*.
*ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs
some bpf program, the program in this cgroup yields to sub-cgroup
program; **multi** if a sub-cgroup installs some bpf program,
that cgroup program gets run in addition to the program in this
cgroup.
*ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs some
bpf program, the program in this cgroup yields to sub-cgroup program;
**multi** if a sub-cgroup installs some bpf program, that cgroup program
gets run in addition to the program in this cgroup.
Only one program is allowed to be attached to a cgroup with
no attach flags or the **override** flag. Attaching another
program will release old program and attach the new one.
Only one program is allowed to be attached to a cgroup with no attach flags
or the **override** flag. Attaching another program will release old
program and attach the new one.
Multiple programs are allowed to be attached to a cgroup with
**multi**. They are executed in FIFO order (those that were
attached first, run first).
Multiple programs are allowed to be attached to a cgroup with **multi**.
They are executed in FIFO order (those that were attached first, run
first).
Non-default *ATTACH_FLAGS* are supported by kernel version 4.14
and later.
Non-default *ATTACH_FLAGS* are supported by kernel version 4.14 and later.
*ATTACH_TYPE* can be on of:
**ingress** ingress path of the inet socket (since 4.10);
@ -106,18 +103,18 @@ DESCRIPTION
**connect4** call to connect(2) for an inet4 socket (since 4.17);
**connect6** call to connect(2) for an inet6 socket (since 4.17);
**connect_unix** call to connect(2) for a unix socket (since 6.7);
**sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an
unconnected udp4 socket (since 4.18);
**sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an
unconnected udp6 socket (since 4.18);
**sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for
an unconnected unix socket (since 6.7);
**recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for
an unconnected udp4 socket (since 5.2);
**recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for
an unconnected udp6 socket (since 5.2);
**recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for
an unconnected unix socket (since 6.7);
**sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected
udp4 socket (since 4.18);
**sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected
udp6 socket (since 4.18);
**sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for an
unconnected unix socket (since 6.7);
**recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an
unconnected udp4 socket (since 5.2);
**recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an
unconnected udp6 socket (since 5.2);
**recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an
unconnected unix socket (since 6.7);
**sysctl** sysctl access (since 5.2);
**getsockopt** call to getsockopt (since 5.3);
**setsockopt** call to setsockopt (since 5.3);
@ -130,8 +127,7 @@ DESCRIPTION
**sock_release** closing an userspace inet socket (since 5.9).
**bpftool cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
Detach *PROG* from the cgroup *CGROUP* and attach type
*ATTACH_TYPE*.
Detach *PROG* from the cgroup *CGROUP* and attach type *ATTACH_TYPE*.
**bpftool prog help**
Print short help message.

67
tools/bpf/bpftool/Documentation/bpftool-feature.rst
View File

@ -33,54 +33,47 @@ FEATURE COMMANDS
DESCRIPTION
===========
**bpftool feature probe** [**kernel**] [**full**] [**macros** [**prefix** *PREFIX*]]
Probe the running kernel and dump a number of eBPF-related
parameters, such as availability of the **bpf**\ () system call,
JIT status, eBPF program types availability, eBPF helper
functions availability, and more.
Probe the running kernel and dump a number of eBPF-related parameters, such
as availability of the **bpf**\ () system call, JIT status, eBPF program
types availability, eBPF helper functions availability, and more.
By default, bpftool **does not run probes** for
**bpf_probe_write_user**\ () and **bpf_trace_printk**\()
helpers which print warnings to kernel logs. To enable them
and run all probes, the **full** keyword should be used.
By default, bpftool **does not run probes** for **bpf_probe_write_user**\
() and **bpf_trace_printk**\() helpers which print warnings to kernel logs.
To enable them and run all probes, the **full** keyword should be used.
If the **macros** keyword (but not the **-j** option) is
passed, a subset of the output is dumped as a list of
**#define** macros that are ready to be included in a C
header file, for example. If, additionally, **prefix** is
used to define a *PREFIX*, the provided string will be used
as a prefix to the names of the macros: this can be used to
avoid conflicts on macro names when including the output of
this command as a header file.
If the **macros** keyword (but not the **-j** option) is passed, a subset
of the output is dumped as a list of **#define** macros that are ready to
be included in a C header file, for example. If, additionally, **prefix**
is used to define a *PREFIX*, the provided string will be used as a prefix
to the names of the macros: this can be used to avoid conflicts on macro
names when including the output of this command as a header file.
Keyword **kernel** can be omitted. If no probe target is
specified, probing the kernel is the default behaviour.
Keyword **kernel** can be omitted. If no probe target is specified, probing
the kernel is the default behaviour.
When the **unprivileged** keyword is used, bpftool will dump
only the features available to a user who does not have the
**CAP_SYS_ADMIN** capability set. The features available in
that case usually represent a small subset of the parameters
supported by the system. Unprivileged users MUST use the
**unprivileged** keyword: This is to avoid misdetection if
bpftool is inadvertently run as non-root, for example. This
keyword is unavailable if bpftool was compiled without
libcap.
When the **unprivileged** keyword is used, bpftool will dump only the
features available to a user who does not have the **CAP_SYS_ADMIN**
capability set. The features available in that case usually represent a
small subset of the parameters supported by the system. Unprivileged users
MUST use the **unprivileged** keyword: This is to avoid misdetection if
bpftool is inadvertently run as non-root, for example. This keyword is
unavailable if bpftool was compiled without libcap.
**bpftool feature probe dev** *NAME* [**full**] [**macros** [**prefix** *PREFIX*]]
Probe network device for supported eBPF features and dump
results to the console.
Probe network device for supported eBPF features and dump results to the
console.
The keywords **full**, **macros** and **prefix** have the
same role as when probing the kernel.
The keywords **full**, **macros** and **prefix** have the same role as when
probing the kernel.
**bpftool feature list_builtins** *GROUP*
List items known to bpftool. These can be BPF program types
(**prog_types**), BPF map types (**map_types**), attach types
(**attach_types**), link types (**link_types**), or BPF helper
functions (**helpers**). The command does not probe the system, but
simply lists the elements that bpftool knows from compilation time,
as provided from libbpf (for all object types) or from the BPF UAPI
header (list of helpers). This can be used in scripts to iterate over
BPF types or helpers.
(**attach_types**), link types (**link_types**), or BPF helper functions
(**helpers**). The command does not probe the system, but simply lists the
elements that bpftool knows from compilation time, as provided from libbpf
(for all object types) or from the BPF UAPI header (list of helpers). This
can be used in scripts to iterate over BPF types or helpers.
**bpftool feature help**
Print short help message.

224
tools/bpf/bpftool/Documentation/bpftool-gen.rst
View File

@ -32,166 +32,145 @@ GEN COMMANDS
DESCRIPTION
===========
**bpftool gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...]
Statically link (combine) together one or more *INPUT_FILE*'s
into a single resulting *OUTPUT_FILE*. All the files involved
are BPF ELF object files.
Statically link (combine) together one or more *INPUT_FILE*'s into a single
resulting *OUTPUT_FILE*. All the files involved are BPF ELF object files.
The rules of BPF static linking are mostly the same as for
user-space object files, but in addition to combining data
and instruction sections, .BTF and .BTF.ext (if present in
any of the input files) data are combined together. .BTF
data is deduplicated, so all the common types across
*INPUT_FILE*'s will only be represented once in the resulting
BTF information.
The rules of BPF static linking are mostly the same as for user-space
object files, but in addition to combining data and instruction sections,
.BTF and .BTF.ext (if present in any of the input files) data are combined
together. .BTF data is deduplicated, so all the common types across
*INPUT_FILE*'s will only be represented once in the resulting BTF
information.
BPF static linking allows to partition BPF source code into
individually compiled files that are then linked into
a single resulting BPF object file, which can be used to
generated BPF skeleton (with **gen skeleton** command) or
passed directly into **libbpf** (using **bpf_object__open()**
BPF static linking allows to partition BPF source code into individually
compiled files that are then linked into a single resulting BPF object
file, which can be used to generated BPF skeleton (with **gen skeleton**
command) or passed directly into **libbpf** (using **bpf_object__open()**
family of APIs).
**bpftool gen skeleton** *FILE*
Generate BPF skeleton C header file for a given *FILE*.
BPF skeleton is an alternative interface to existing libbpf
APIs for working with BPF objects. Skeleton code is intended
to significantly shorten and simplify code to load and work
with BPF programs from userspace side. Generated code is
tailored to specific input BPF object *FILE*, reflecting its
structure by listing out available maps, program, variables,
etc. Skeleton eliminates the need to lookup mentioned
components by name. Instead, if skeleton instantiation
succeeds, they are populated in skeleton structure as valid
libbpf types (e.g., **struct bpf_map** pointer) and can be
passed to existing generic libbpf APIs.
BPF skeleton is an alternative interface to existing libbpf APIs for
working with BPF objects. Skeleton code is intended to significantly
shorten and simplify code to load and work with BPF programs from userspace
side. Generated code is tailored to specific input BPF object *FILE*,
reflecting its structure by listing out available maps, program, variables,
etc. Skeleton eliminates the need to lookup mentioned components by name.
Instead, if skeleton instantiation succeeds, they are populated in skeleton
structure as valid libbpf types (e.g., **struct bpf_map** pointer) and can
be passed to existing generic libbpf APIs.
In addition to simple and reliable access to maps and
programs, skeleton provides a storage for BPF links (**struct
bpf_link**) for each BPF program within BPF object. When
requested, supported BPF programs will be automatically
attached and resulting BPF links stored for further use by
user in pre-allocated fields in skeleton struct. For BPF
programs that can't be automatically attached by libbpf,
user can attach them manually, but store resulting BPF link
in per-program link field. All such set up links will be
automatically destroyed on BPF skeleton destruction. This
eliminates the need for users to manage links manually and
rely on libbpf support to detach programs and free up
resources.
In addition to simple and reliable access to maps and programs, skeleton
provides a storage for BPF links (**struct bpf_link**) for each BPF program
within BPF object. When requested, supported BPF programs will be
automatically attached and resulting BPF links stored for further use by
user in pre-allocated fields in skeleton struct. For BPF programs that
can't be automatically attached by libbpf, user can attach them manually,
but store resulting BPF link in per-program link field. All such set up
links will be automatically destroyed on BPF skeleton destruction. This
eliminates the need for users to manage links manually and rely on libbpf
support to detach programs and free up resources.
Another facility provided by BPF skeleton is an interface to
global variables of all supported kinds: mutable, read-only,
as well as extern ones. This interface allows to pre-setup
initial values of variables before BPF object is loaded and
verified by kernel. For non-read-only variables, the same
interface can be used to fetch values of global variables on
Another facility provided by BPF skeleton is an interface to global
variables of all supported kinds: mutable, read-only, as well as extern
ones. This interface allows to pre-setup initial values of variables before
BPF object is loaded and verified by kernel. For non-read-only variables,
the same interface can be used to fetch values of global variables on
userspace side, even if they are modified by BPF code.
During skeleton generation, contents of source BPF object
*FILE* is embedded within generated code and is thus not
necessary to keep around. This ensures skeleton and BPF
object file are matching 1-to-1 and always stay in sync.
Generated code is dual-licensed under LGPL-2.1 and
During skeleton generation, contents of source BPF object *FILE* is
embedded within generated code and is thus not necessary to keep around.
This ensures skeleton and BPF object file are matching 1-to-1 and always
stay in sync. Generated code is dual-licensed under LGPL-2.1 and
BSD-2-Clause licenses.
It is a design goal and guarantee that skeleton interfaces
are interoperable with generic libbpf APIs. User should
always be able to use skeleton API to create and load BPF
object, and later use libbpf APIs to keep working with
specific maps, programs, etc.
It is a design goal and guarantee that skeleton interfaces are
interoperable with generic libbpf APIs. User should always be able to use
skeleton API to create and load BPF object, and later use libbpf APIs to
keep working with specific maps, programs, etc.
As part of skeleton, few custom functions are generated.
Each of them is prefixed with object name. Object name can
either be derived from object file name, i.e., if BPF object
file name is **example.o**, BPF object name will be
**example**. Object name can be also specified explicitly
through **name** *OBJECT_NAME* parameter. The following
custom functions are provided (assuming **example** as
the object name):
As part of skeleton, few custom functions are generated. Each of them is
prefixed with object name. Object name can either be derived from object
file name, i.e., if BPF object file name is **example.o**, BPF object name
will be **example**. Object name can be also specified explicitly through
**name** *OBJECT_NAME* parameter. The following custom functions are
provided (assuming **example** as the object name):
- **example__open** and **example__open_opts**.
These functions are used to instantiate skeleton. It
corresponds to libbpf's **bpf_object__open**\ () API.
**_opts** variants accepts extra **bpf_object_open_opts**
options.
These functions are used to instantiate skeleton. It corresponds to
libbpf's **bpf_object__open**\ () API. **_opts** variants accepts extra
**bpf_object_open_opts** options.
- **example__load**.
This function creates maps, loads and verifies BPF
programs, initializes global data maps. It corresponds to
libppf's **bpf_object__load**\ () API.
This function creates maps, loads and verifies BPF programs, initializes
global data maps. It corresponds to libppf's **bpf_object__load**\ ()
API.
- **example__open_and_load** combines **example__open** and
**example__load** invocations in one commonly used
operation.
**example__load** invocations in one commonly used operation.
- **example__attach** and **example__detach**
This pair of functions allow to attach and detach,
correspondingly, already loaded BPF object. Only BPF
programs of types supported by libbpf for auto-attachment
will be auto-attached and their corresponding BPF links
instantiated. For other BPF programs, user can manually
create a BPF link and assign it to corresponding fields in
skeleton struct. **example__detach** will detach both
links created automatically, as well as those populated by
user manually.
This pair of functions allow to attach and detach, correspondingly,
already loaded BPF object. Only BPF programs of types supported by libbpf
for auto-attachment will be auto-attached and their corresponding BPF
links instantiated. For other BPF programs, user can manually create a
BPF link and assign it to corresponding fields in skeleton struct.
**example__detach** will detach both links created automatically, as well
as those populated by user manually.
- **example__destroy**
Detach and unload BPF programs, free up all the resources
used by skeleton and BPF object.
Detach and unload BPF programs, free up all the resources used by
skeleton and BPF object.
If BPF object has global variables, corresponding structs
with memory layout corresponding to global data data section
layout will be created. Currently supported ones are: *.data*,
*.bss*, *.rodata*, and *.kconfig* structs/data sections.
These data sections/structs can be used to set up initial
values of variables, if set before **example__load**.
Afterwards, if target kernel supports memory-mapped BPF
arrays, same structs can be used to fetch and update
(non-read-only) data from userspace, with same simplicity
as for BPF side.
If BPF object has global variables, corresponding structs with memory
layout corresponding to global data data section layout will be created.
Currently supported ones are: *.data*, *.bss*, *.rodata*, and *.kconfig*
structs/data sections. These data sections/structs can be used to set up
initial values of variables, if set before **example__load**. Afterwards,
if target kernel supports memory-mapped BPF arrays, same structs can be
used to fetch and update (non-read-only) data from userspace, with same
simplicity as for BPF side.
**bpftool gen subskeleton** *FILE*
Generate BPF subskeleton C header file for a given *FILE*.
Subskeletons are similar to skeletons, except they do not own
the corresponding maps, programs, or global variables. They
require that the object file used to generate them is already
loaded into a *bpf_object* by some other means.
Subskeletons are similar to skeletons, except they do not own the
corresponding maps, programs, or global variables. They require that the
object file used to generate them is already loaded into a *bpf_object* by
some other means.
This functionality is useful when a library is included into a
larger BPF program. A subskeleton for the library would have
access to all objects and globals defined in it, without
having to know about the larger program.
This functionality is useful when a library is included into a larger BPF
program. A subskeleton for the library would have access to all objects and
globals defined in it, without having to know about the larger program.
Consequently, there are only two functions defined
for subskeletons:
Consequently, there are only two functions defined for subskeletons:
- **example__open(bpf_object\*)**
Instantiates a subskeleton from an already opened (but not
necessarily loaded) **bpf_object**.
Instantiates a subskeleton from an already opened (but not necessarily
loaded) **bpf_object**.
- **example__destroy()**
Frees the storage for the subskeleton but *does not* unload
any BPF programs or maps.
Frees the storage for the subskeleton but *does not* unload any BPF
programs or maps.
**bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...]
Generate a minimum BTF file as *OUTPUT*, derived from a given
*INPUT* BTF file, containing all needed BTF types so one, or
more, given eBPF objects CO-RE relocations may be satisfied.
Generate a minimum BTF file as *OUTPUT*, derived from a given *INPUT* BTF
file, containing all needed BTF types so one, or more, given eBPF objects
CO-RE relocations may be satisfied.
When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF,
libbpf, when loading an eBPF object, has to rely on external
BTF files to be able to calculate CO-RE relocations.
When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF, libbpf, when
loading an eBPF object, has to rely on external BTF files to be able to
calculate CO-RE relocations.
Usually, an external BTF file is built from existing kernel
DWARF data using pahole. It contains all the types used by
its respective kernel image and, because of that, is big.
Usually, an external BTF file is built from existing kernel DWARF data
using pahole. It contains all the types used by its respective kernel image
and, because of that, is big.
The min_core_btf feature builds smaller BTF files, customized
to one or multiple eBPF objects, so they can be distributed
together with an eBPF CO-RE based application, turning the
application portable to different kernel versions.
The min_core_btf feature builds smaller BTF files, customized to one or
multiple eBPF objects, so they can be distributed together with an eBPF
CO-RE based application, turning the application portable to different
kernel versions.
Check examples bellow for more information how to use it.
@ -204,9 +183,8 @@ OPTIONS
-L, --use-loader
For skeletons, generate a "light" skeleton (also known as "loader"
skeleton). A light skeleton contains a loader eBPF program. It does
not use the majority of the libbpf infrastructure, and does not need
libelf.
skeleton). A light skeleton contains a loader eBPF program. It does not use
the majority of the libbpf infrastructure, and does not need libelf.
EXAMPLES
========

26
tools/bpf/bpftool/Documentation/bpftool-iter.rst
View File

@ -32,23 +32,19 @@ ITER COMMANDS
DESCRIPTION
===========
**bpftool iter pin** *OBJ* *PATH* [**map** *MAP*]
A bpf iterator combines a kernel iterating of
particular kernel data (e.g., tasks, bpf_maps, etc.)
and a bpf program called for each kernel data object
(e.g., one task, one bpf_map, etc.). User space can
*read* kernel iterator output through *read()* syscall.
A bpf iterator combines a kernel iterating of particular kernel data (e.g.,
tasks, bpf_maps, etc.) and a bpf program called for each kernel data object
(e.g., one task, one bpf_map, etc.). User space can *read* kernel iterator
output through *read()* syscall.
The *pin* command creates a bpf iterator from *OBJ*,
and pin it to *PATH*. The *PATH* should be located
in *bpffs* mount. It must not contain a dot
character ('.'), which is reserved for future extensions
of *bpffs*.
The *pin* command creates a bpf iterator from *OBJ*, and pin it to *PATH*.
The *PATH* should be located in *bpffs* mount. It must not contain a dot
character ('.'), which is reserved for future extensions of *bpffs*.
Map element bpf iterator requires an additional parameter
*MAP* so bpf program can iterate over map elements for
that map. User can have a bpf program in kernel to run
with each map element, do checking, filtering, aggregation,
etc. without copying data to user space.
Map element bpf iterator requires an additional parameter *MAP* so bpf
program can iterate over map elements for that map. User can have a bpf
program in kernel to run with each map element, do checking, filtering,
aggregation, etc. without copying data to user space.
User can then *cat PATH* to see the bpf iterator output.

39
tools/bpf/bpftool/Documentation/bpftool-link.rst
View File

@ -34,32 +34,28 @@ LINK COMMANDS
DESCRIPTION
===========
**bpftool link { show | list }** [*LINK*]
Show information about active links. If *LINK* is
specified show information only about given link,
otherwise list all links currently active on the system.
Show information about active links. If *LINK* is specified show
information only about given link, otherwise list all links currently
active on the system.
Output will start with link ID followed by link type and
zero or more named attributes, some of which depend on type
of link.
Output will start with link ID followed by link type and zero or more named
attributes, some of which depend on type of link.
Since Linux 5.8 bpftool is able to discover information about
processes that hold open file descriptors (FDs) against BPF
links. On such kernels bpftool will automatically emit this
information as well.
Since Linux 5.8 bpftool is able to discover information about processes
that hold open file descriptors (FDs) against BPF links. On such kernels
bpftool will automatically emit this information as well.
**bpftool link pin** *LINK* *FILE*
Pin link *LINK* as *FILE*.
Note: *FILE* must be located in *bpffs* mount. It must not
contain a dot character ('.'), which is reserved for future
extensions of *bpffs*.
Note: *FILE* must be located in *bpffs* mount. It must not contain a dot
character ('.'), which is reserved for future extensions of *bpffs*.
**bpftool link detach** *LINK*
Force-detach link *LINK*. BPF link and its underlying BPF
program will stay valid, but they will be detached from the
respective BPF hook and BPF link will transition into
a defunct state until last open file descriptor for that
link is closed.
Force-detach link *LINK*. BPF link and its underlying BPF program will stay
valid, but they will be detached from the respective BPF hook and BPF link
will transition into a defunct state until last open file descriptor for
that link is closed.
**bpftool link help**
Print short help message.
@ -69,12 +65,11 @@ OPTIONS
.. include:: common_options.rst
-f, --bpffs
When showing BPF links, show file names of pinned
links.
When showing BPF links, show file names of pinned links.
-n, --nomount
Do not automatically attempt to mount any virtual file system
(such as tracefs or BPF virtual file system) when necessary.
Do not automatically attempt to mount any virtual file system (such as
tracefs or BPF virtual file system) when necessary.
EXAMPLES
========

98
tools/bpf/bpftool/Documentation/bpftool-map.rst
View File

@ -60,51 +60,48 @@ MAP COMMANDS
DESCRIPTION
===========
**bpftool map { show | list }** [*MAP*]
Show information about loaded maps. If *MAP* is specified
show information only about given maps, otherwise list all
maps currently loaded on the system. In case of **name**,
*MAP* may match several maps which will all be shown.
Show information about loaded maps. If *MAP* is specified show information
only about given maps, otherwise list all maps currently loaded on the
system. In case of **name**, *MAP* may match several maps which will all
be shown.
Output will start with map ID followed by map type and
zero or more named attributes (depending on kernel version).
Output will start with map ID followed by map type and zero or more named
attributes (depending on kernel version).
Since Linux 5.8 bpftool is able to discover information about
processes that hold open file descriptors (FDs) against BPF
maps. On such kernels bpftool will automatically emit this
information as well.
Since Linux 5.8 bpftool is able to discover information about processes
that hold open file descriptors (FDs) against BPF maps. On such kernels
bpftool will automatically emit this information as well.
**bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] [**offload_dev** *NAME*]
Create a new map with given parameters and pin it to *bpffs*
as *FILE*.
Create a new map with given parameters and pin it to *bpffs* as *FILE*.
*FLAGS* should be an integer which is the combination of
desired flags, e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h
UAPI header for existing flags).
*FLAGS* should be an integer which is the combination of desired flags,
e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h UAPI header for existing
flags).
To create maps of type array-of-maps or hash-of-maps, the
**inner_map** keyword must be used to pass an inner map. The
kernel needs it to collect metadata related to the inner maps
that the new map will work with.
To create maps of type array-of-maps or hash-of-maps, the **inner_map**
keyword must be used to pass an inner map. The kernel needs it to collect
metadata related to the inner maps that the new map will work with.
Keyword **offload_dev** expects a network interface name,
and is used to request hardware offload for the map.
Keyword **offload_dev** expects a network interface name, and is used to
request hardware offload for the map.
**bpftool map dump** *MAP*
Dump all entries in a given *MAP*. In case of **name**,
*MAP* may match several maps which will all be dumped.
Dump all entries in a given *MAP*. In case of **name**, *MAP* may match
several maps which will all be dumped.
**bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*]
Update map entry for a given *KEY*.
*UPDATE_FLAGS* can be one of: **any** update existing entry
or add if doesn't exit; **exist** update only if entry already
exists; **noexist** update only if entry doesn't exist.
*UPDATE_FLAGS* can be one of: **any** update existing entry or add if
doesn't exit; **exist** update only if entry already exists; **noexist**
update only if entry doesn't exist.
If the **hex** keyword is provided in front of the bytes
sequence, the bytes are parsed as hexadecimal values, even if
no "0x" prefix is added. If the keyword is not provided, then
the bytes are parsed as decimal values, unless a "0x" prefix
(for hexadecimal) or a "0" prefix (for octal) is provided.
If the **hex** keyword is provided in front of the bytes sequence, the
bytes are parsed as hexadecimal values, even if no "0x" prefix is added. If
the keyword is not provided, then the bytes are parsed as decimal values,
unless a "0x" prefix (for hexadecimal) or a "0" prefix (for octal) is
provided.
**bpftool map lookup** *MAP* [**key** *DATA*]
Lookup **key** in the map.
@ -118,25 +115,23 @@ DESCRIPTION
**bpftool map pin** *MAP* *FILE*
Pin map *MAP* as *FILE*.
Note: *FILE* must be located in *bpffs* mount. It must not
contain a dot character ('.'), which is reserved for future
extensions of *bpffs*.
Note: *FILE* must be located in *bpffs* mount. It must not contain a dot
character ('.'), which is reserved for future extensions of *bpffs*.
**bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map.
Install perf rings into a perf event array map and dump
output of any **bpf_perf_event_output**\ () call in the kernel.
By default read the number of CPUs on the system and
install perf ring for each CPU in the corresponding index
in the array.
Install perf rings into a perf event array map and dump output of any
**bpf_perf_event_output**\ () call in the kernel. By default read the
number of CPUs on the system and install perf ring for each CPU in the
corresponding index in the array.
If **cpu** and **index** are specified, install perf ring
for given **cpu** at **index** in the array (single ring).
If **cpu** and **index** are specified, install perf ring for given **cpu**
at **index** in the array (single ring).
Note that installing a perf ring into an array will silently
replace any existing ring. Any other application will stop
receiving events if it installed its rings earlier.
Note that installing a perf ring into an array will silently replace any
existing ring. Any other application will stop receiving events if it
installed its rings earlier.
**bpftool map peek** *MAP*
Peek next value in the queue or stack.
@ -154,12 +149,11 @@ DESCRIPTION
Dequeue and print value from the queue.
**bpftool map freeze** *MAP*
Freeze the map as read-only from user space. Entries from a
frozen map can not longer be updated or deleted with the
**bpf**\ () system call. This operation is not reversible,
and the map remains immutable from user space until its
destruction. However, read and write permissions for BPF
programs to the map remain unchanged.
Freeze the map as read-only from user space. Entries from a frozen map can
not longer be updated or deleted with the **bpf**\ () system call. This
operation is not reversible, and the map remains immutable from user space
until its destruction. However, read and write permissions for BPF programs
to the map remain unchanged.
**bpftool map help**
Print short help message.
@ -172,8 +166,8 @@ OPTIONS
Show file names of pinned maps.
-n, --nomount
Do not automatically attempt to mount any virtual file system
(such as tracefs or BPF virtual file system) when necessary.
Do not automatically attempt to mount any virtual file system (such as
tracefs or BPF virtual file system) when necessary.
EXAMPLES
========

48
tools/bpf/bpftool/Documentation/bpftool-net.rst
View File

@ -18,8 +18,7 @@ SYNOPSIS
*OPTIONS* := { |COMMON_OPTIONS| }
*COMMANDS* :=
{ **show** | **list** | **attach** | **detach** | **help** }
*COMMANDS* := { **show** | **list** | **attach** | **detach** | **help** }
NET COMMANDS
============
@ -39,32 +38,31 @@ DESCRIPTION
Currently, device driver xdp attachments, tcx, netkit and old-style tc
classifier/action attachments, flow_dissector as well as netfilter
attachments are implemented, i.e., for
program types **BPF_PROG_TYPE_XDP**, **BPF_PROG_TYPE_SCHED_CLS**,
**BPF_PROG_TYPE_SCHED_ACT**, **BPF_PROG_TYPE_FLOW_DISSECTOR**,
**BPF_PROG_TYPE_NETFILTER**.
attachments are implemented, i.e., for program types **BPF_PROG_TYPE_XDP**,
**BPF_PROG_TYPE_SCHED_CLS**, **BPF_PROG_TYPE_SCHED_ACT**,
**BPF_PROG_TYPE_FLOW_DISSECTOR**, **BPF_PROG_TYPE_NETFILTER**.
For programs attached to a particular cgroup, e.g.,
**BPF_PROG_TYPE_CGROUP_SKB**, **BPF_PROG_TYPE_CGROUP_SOCK**,
**BPF_PROG_TYPE_SOCK_OPS** and **BPF_PROG_TYPE_CGROUP_SOCK_ADDR**,
users can use **bpftool cgroup** to dump cgroup attachments.
For sk_{filter, skb, msg, reuseport} and lwt/seg6
bpf programs, users should consult other tools, e.g., iproute2.
**BPF_PROG_TYPE_SOCK_OPS** and **BPF_PROG_TYPE_CGROUP_SOCK_ADDR**, users
can use **bpftool cgroup** to dump cgroup attachments. For sk_{filter, skb,
msg, reuseport} and lwt/seg6 bpf programs, users should consult other
tools, e.g., iproute2.
The current output will start with all xdp program attachments, followed by
all tcx, netkit, then tc class/qdisc bpf program attachments, then flow_dissector
and finally netfilter programs. Both xdp programs and tcx/netkit/tc programs are
ordered based on ifindex number. If multiple bpf programs attached
to the same networking device through **tc**, the order will be first
all bpf programs attached to tcx, netkit, then tc classes, then all bpf programs
attached to non clsact qdiscs, and finally all bpf programs attached
to root and clsact qdisc.
all tcx, netkit, then tc class/qdisc bpf program attachments, then
flow_dissector and finally netfilter programs. Both xdp programs and
tcx/netkit/tc programs are ordered based on ifindex number. If multiple bpf
programs attached to the same networking device through **tc**, the order
will be first all bpf programs attached to tcx, netkit, then tc classes,
then all bpf programs attached to non clsact qdiscs, and finally all bpf
programs attached to root and clsact qdisc.
**bpftool** **net attach** *ATTACH_TYPE* *PROG* **dev** *NAME* [ **overwrite** ]
Attach bpf program *PROG* to network interface *NAME* with
type specified by *ATTACH_TYPE*. Previously attached bpf program
can be replaced by the command used with **overwrite** option.
Currently, only XDP-related modes are supported for *ATTACH_TYPE*.
Attach bpf program *PROG* to network interface *NAME* with type specified
by *ATTACH_TYPE*. Previously attached bpf program can be replaced by the
command used with **overwrite** option. Currently, only XDP-related modes
are supported for *ATTACH_TYPE*.
*ATTACH_TYPE* can be of:
**xdp** - try native XDP and fallback to generic XDP if NIC driver does not support it;
@ -73,10 +71,10 @@ DESCRIPTION
**xdpoffload** - Offload XDP. runs directly on NIC on each packet reception;
**bpftool** **net detach** *ATTACH_TYPE* **dev** *NAME*
Detach bpf program attached to network interface *NAME* with
type specified by *ATTACH_TYPE*. To detach bpf program, same
*ATTACH_TYPE* previously used for attach must be specified.
Currently, only XDP-related modes are supported for *ATTACH_TYPE*.
Detach bpf program attached to network interface *NAME* with type specified
by *ATTACH_TYPE*. To detach bpf program, same *ATTACH_TYPE* previously used
for attach must be specified. Currently, only XDP-related modes are
supported for *ATTACH_TYPE*.
**bpftool net help**
Print short help message.

6
tools/bpf/bpftool/Documentation/bpftool-perf.rst
View File

@ -35,9 +35,9 @@ DESCRIPTION
Output will start with process id and file descriptor in that process,
followed by bpf program id, attachment information, and attachment point.
The attachment point for raw_tracepoint/tracepoint is the trace probe name.
The attachment point for k[ret]probe is either symbol name and offset,
or a kernel virtual address.
The attachment point for u[ret]probe is the file name and the file offset.
The attachment point for k[ret]probe is either symbol name and offset, or a
kernel virtual address. The attachment point for u[ret]probe is the file
name and the file offset.
**bpftool perf help**
Print short help message.

244
tools/bpf/bpftool/Documentation/bpftool-prog.rst
View File

@ -68,164 +68,143 @@ PROG COMMANDS
DESCRIPTION
===========
**bpftool prog { show | list }** [*PROG*]
Show information about loaded programs. If *PROG* is
specified show information only about given programs,
otherwise list all programs currently loaded on the system.
In case of **tag** or **name**, *PROG* may match several
programs which will all be shown.
Show information about loaded programs. If *PROG* is specified show
information only about given programs, otherwise list all programs
currently loaded on the system. In case of **tag** or **name**, *PROG* may
match several programs which will all be shown.
Output will start with program ID followed by program type and
zero or more named attributes (depending on kernel version).
Output will start with program ID followed by program type and zero or more
named attributes (depending on kernel version).
Since Linux 5.1 the kernel can collect statistics on BPF
programs (such as the total time spent running the program,
and the number of times it was run). If available, bpftool
shows such statistics. However, the kernel does not collect
them by defaults, as it slightly impacts performance on each
program run. Activation or deactivation of the feature is
performed via the **kernel.bpf_stats_enabled** sysctl knob.
Since Linux 5.1 the kernel can collect statistics on BPF programs (such as
the total time spent running the program, and the number of times it was
run). If available, bpftool shows such statistics. However, the kernel does
not collect them by defaults, as it slightly impacts performance on each
program run. Activation or deactivation of the feature is performed via the
**kernel.bpf_stats_enabled** sysctl knob.
Since Linux 5.8 bpftool is able to discover information about
processes that hold open file descriptors (FDs) against BPF
programs. On such kernels bpftool will automatically emit this
information as well.
Since Linux 5.8 bpftool is able to discover information about processes
that hold open file descriptors (FDs) against BPF programs. On such kernels
bpftool will automatically emit this information as well.
**bpftool prog dump xlated** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] [**visual**] }]
Dump eBPF instructions of the programs from the kernel. By
default, eBPF will be disassembled and printed to standard
output in human-readable format. In this case, **opcodes**
controls if raw opcodes should be printed as well.
Dump eBPF instructions of the programs from the kernel. By default, eBPF
will be disassembled and printed to standard output in human-readable
format. In this case, **opcodes** controls if raw opcodes should be printed
as well.
In case of **tag** or **name**, *PROG* may match several
programs which will all be dumped. However, if **file** or
**visual** is specified, *PROG* must match a single program.
In case of **tag** or **name**, *PROG* may match several programs which
will all be dumped. However, if **file** or **visual** is specified,
*PROG* must match a single program.
If **file** is specified, the binary image will instead be
written to *FILE*.
If **file** is specified, the binary image will instead be written to
*FILE*.
If **visual** is specified, control flow graph (CFG) will be
built instead, and eBPF instructions will be presented with
CFG in DOT format, on standard output.
If **visual** is specified, control flow graph (CFG) will be built instead,
and eBPF instructions will be presented with CFG in DOT format, on standard
output.
If the programs have line_info available, the source line will
be displayed. If **linum** is specified, the filename, line
number and line column will also be displayed.
If the programs have line_info available, the source line will be
displayed. If **linum** is specified, the filename, line number and line
column will also be displayed.
**bpftool prog dump jited** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] }]
Dump jited image (host machine code) of the program.
If *FILE* is specified image will be written to a file,
otherwise it will be disassembled and printed to stdout.
*PROG* must match a single program when **file** is specified.
If *FILE* is specified image will be written to a file, otherwise it will
be disassembled and printed to stdout. *PROG* must match a single program
when **file** is specified.
**opcodes** controls if raw opcodes will be printed.
If the prog has line_info available, the source line will
be displayed. If **linum** is specified, the filename, line
number and line column will also be displayed.
If the prog has line_info available, the source line will be displayed. If
**linum** is specified, the filename, line number and line column will also
be displayed.
**bpftool prog pin** *PROG* *FILE*
Pin program *PROG* as *FILE*.
Note: *FILE* must be located in *bpffs* mount. It must not
contain a dot character ('.'), which is reserved for future
extensions of *bpffs*.
Note: *FILE* must be located in *bpffs* mount. It must not contain a dot
character ('.'), which is reserved for future extensions of *bpffs*.
**bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** { **idx** *IDX* | **name** *NAME* } *MAP*] [{ **offload_dev** | **xdpmeta_dev** } *NAME*] [**pinmaps** *MAP_DIR*] [**autoattach**]
Load bpf program(s) from binary *OBJ* and pin as *PATH*.
**bpftool prog load** pins only the first program from the
*OBJ* as *PATH*. **bpftool prog loadall** pins all programs
from the *OBJ* under *PATH* directory.
**type** is optional, if not specified program type will be
inferred from section names.
By default bpftool will create new maps as declared in the ELF
object being loaded. **map** parameter allows for the reuse
of existing maps. It can be specified multiple times, each
time for a different map. *IDX* refers to index of the map
to be replaced in the ELF file counting from 0, while *NAME*
allows to replace a map by name. *MAP* specifies the map to
use, referring to it by **id** or through a **pinned** file.
If **offload_dev** *NAME* is specified program will be loaded
onto given networking device (offload).
If **xdpmeta_dev** *NAME* is specified program will become
device-bound without offloading, this facilitates access
to XDP metadata.
Optional **pinmaps** argument can be provided to pin all
maps under *MAP_DIR* directory.
Load bpf program(s) from binary *OBJ* and pin as *PATH*. **bpftool prog
load** pins only the first program from the *OBJ* as *PATH*. **bpftool prog
loadall** pins all programs from the *OBJ* under *PATH* directory. **type**
is optional, if not specified program type will be inferred from section
names. By default bpftool will create new maps as declared in the ELF
object being loaded. **map** parameter allows for the reuse of existing
maps. It can be specified multiple times, each time for a different map.
*IDX* refers to index of the map to be replaced in the ELF file counting
from 0, while *NAME* allows to replace a map by name. *MAP* specifies the
map to use, referring to it by **id** or through a **pinned** file. If
**offload_dev** *NAME* is specified program will be loaded onto given
networking device (offload). If **xdpmeta_dev** *NAME* is specified program
will become device-bound without offloading, this facilitates access to XDP
metadata. Optional **pinmaps** argument can be provided to pin all maps
under *MAP_DIR* directory.
If **autoattach** is specified program will be attached
before pin. In that case, only the link (representing the
program attached to its hook) is pinned, not the program as
such, so the path won't show in **bpftool prog show -f**,
only show in **bpftool link show -f**. Also, this only works
when bpftool (libbpf) is able to infer all necessary
information from the object file, in particular, it's not
supported for all program types. If a program does not
support autoattach, bpftool falls back to regular pinning
If **autoattach** is specified program will be attached before pin. In that
case, only the link (representing the program attached to its hook) is
pinned, not the program as such, so the path won't show in **bpftool prog
show -f**, only show in **bpftool link show -f**. Also, this only works
when bpftool (libbpf) is able to infer all necessary information from the
object file, in particular, it's not supported for all program types. If a
program does not support autoattach, bpftool falls back to regular pinning
for that program instead.
Note: *PATH* must be located in *bpffs* mount. It must not
contain a dot character ('.'), which is reserved for future
extensions of *bpffs*.
Note: *PATH* must be located in *bpffs* mount. It must not contain a dot
character ('.'), which is reserved for future extensions of *bpffs*.
**bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
Attach bpf program *PROG* (with type specified by
*ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
parameter, with the exception of *flow_dissector* which is
attached to current networking name space.
Attach bpf program *PROG* (with type specified by *ATTACH_TYPE*). Most
*ATTACH_TYPEs* require a *MAP* parameter, with the exception of
*flow_dissector* which is attached to current networking name space.
**bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
Detach bpf program *PROG* (with type specified by
*ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
parameter, with the exception of *flow_dissector* which is
detached from the current networking name space.
Detach bpf program *PROG* (with type specified by *ATTACH_TYPE*). Most
*ATTACH_TYPEs* require a *MAP* parameter, with the exception of
*flow_dissector* which is detached from the current networking name space.
**bpftool prog tracelog**
Dump the trace pipe of the system to the console (stdout).
Hit <Ctrl+C> to stop printing. BPF programs can write to this
trace pipe at runtime with the **bpf_trace_printk**\ () helper.
This should be used only for debugging purposes. For
streaming data from BPF programs to user space, one can use
Dump the trace pipe of the system to the console (stdout). Hit <Ctrl+C> to
stop printing. BPF programs can write to this trace pipe at runtime with
the **bpf_trace_printk**\ () helper. This should be used only for debugging
purposes. For streaming data from BPF programs to user space, one can use
perf events (see also **bpftool-map**\ (8)).
**bpftool prog run** *PROG* **data_in** *FILE* [**data_out** *FILE* [**data_size_out** *L*]] [**ctx_in** *FILE* [**ctx_out** *FILE* [**ctx_size_out** *M*]]] [**repeat** *N*]
Run BPF program *PROG* in the kernel testing infrastructure
for BPF, meaning that the program works on the data and
context provided by the user, and not on actual packets or
monitored functions etc. Return value and duration for the
test run are printed out to the console.
Run BPF program *PROG* in the kernel testing infrastructure for BPF,
meaning that the program works on the data and context provided by the
user, and not on actual packets or monitored functions etc. Return value
and duration for the test run are printed out to the console.
Input data is read from the *FILE* passed with **data_in**.
If this *FILE* is "**-**", input data is read from standard
input. Input context, if any, is read from *FILE* passed with
**ctx_in**. Again, "**-**" can be used to read from standard
input, but only if standard input is not already in use for
input data. If a *FILE* is passed with **data_out**, output
data is written to that file. Similarly, output context is
written to the *FILE* passed with **ctx_out**. For both
output flows, "**-**" can be used to print to the standard
output (as plain text, or JSON if relevant option was
passed). If output keywords are omitted, output data and
context are discarded. Keywords **data_size_out** and
**ctx_size_out** are used to pass the size (in bytes) for the
output buffers to the kernel, although the default of 32 kB
should be more than enough for most cases.
Input data is read from the *FILE* passed with **data_in**. If this *FILE*
is "**-**", input data is read from standard input. Input context, if any,
is read from *FILE* passed with **ctx_in**. Again, "**-**" can be used to
read from standard input, but only if standard input is not already in use
for input data. If a *FILE* is passed with **data_out**, output data is
written to that file. Similarly, output context is written to the *FILE*
passed with **ctx_out**. For both output flows, "**-**" can be used to
print to the standard output (as plain text, or JSON if relevant option was
passed). If output keywords are omitted, output data and context are
discarded. Keywords **data_size_out** and **ctx_size_out** are used to pass
the size (in bytes) for the output buffers to the kernel, although the
default of 32 kB should be more than enough for most cases.
Keyword **repeat** is used to indicate the number of
consecutive runs to perform. Note that output data and
context printed to files correspond to the last of those
runs. The duration printed out at the end of the runs is an
average over all runs performed by the command.
Keyword **repeat** is used to indicate the number of consecutive runs to
perform. Note that output data and context printed to files correspond to
the last of those runs. The duration printed out at the end of the runs is
an average over all runs performed by the command.
Not all program types support test run. Among those which do,
not all of them can take the **ctx_in**/**ctx_out**
arguments. bpftool does not perform checks on program types.
Not all program types support test run. Among those which do, not all of
them can take the **ctx_in**/**ctx_out** arguments. bpftool does not
perform checks on program types.
**bpftool prog profile** *PROG* [**duration** *DURATION*] *METRICs*
Profile *METRICs* for bpf program *PROG* for *DURATION*
seconds or until user hits <Ctrl+C>. *DURATION* is optional.
If *DURATION* is not specified, the profiling will run up to
**UINT_MAX** seconds.
Profile *METRICs* for bpf program *PROG* for *DURATION* seconds or until
user hits <Ctrl+C>. *DURATION* is optional. If *DURATION* is not specified,
the profiling will run up to **UINT_MAX** seconds.
**bpftool prog help**
Print short help message.
@ -235,29 +214,26 @@ OPTIONS
.. include:: common_options.rst
-f, --bpffs
When showing BPF programs, show file names of pinned
programs.
When showing BPF programs, show file names of pinned programs.
-m, --mapcompat
Allow loading maps with unknown map definitions.
-n, --nomount
Do not automatically attempt to mount any virtual file system
(such as tracefs or BPF virtual file system) when necessary.
Do not automatically attempt to mount any virtual file system (such as
tracefs or BPF virtual file system) when necessary.
-L, --use-loader
Load program as a "loader" program. This is useful to debug
the generation of such programs. When this option is in
use, bpftool attempts to load the programs from the object
file into the kernel, but does not pin them (therefore, the
*PATH* must not be provided).
Load program as a "loader" program. This is useful to debug the generation
of such programs. When this option is in use, bpftool attempts to load the
programs from the object file into the kernel, but does not pin them
(therefore, the *PATH* must not be provided).
When combined with the **-d**\ \|\ **--debug** option,
additional debug messages are generated, and the execution
of the loader program will use the **bpf_trace_printk**\ ()
helper to log each step of loading BTF, creating the maps,
and loading the programs (see **bpftool prog tracelog** as
a way to dump those messages).
When combined with the **-d**\ \|\ **--debug** option, additional debug
messages are generated, and the execution of the loader program will use
the **bpf_trace_printk**\ () helper to log each step of loading BTF,
creating the maps, and loading the programs (see **bpftool prog tracelog**
as a way to dump those messages).
EXAMPLES
========

33
tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
View File

@ -37,28 +37,27 @@ STRUCT_OPS COMMANDS
DESCRIPTION
===========
**bpftool struct_ops { show | list }** [*STRUCT_OPS_MAP*]
Show brief information about the struct_ops in the system.
If *STRUCT_OPS_MAP* is specified, it shows information only
for the given struct_ops. Otherwise, it lists all struct_ops
currently existing in the system.
Show brief information about the struct_ops in the system. If
*STRUCT_OPS_MAP* is specified, it shows information only for the given
struct_ops. Otherwise, it lists all struct_ops currently existing in the
system.
Output will start with struct_ops map ID, followed by its map
name and its struct_ops's kernel type.
Output will start with struct_ops map ID, followed by its map name and its
struct_ops's kernel type.
**bpftool struct_ops dump** [*STRUCT_OPS_MAP*]
Dump details information about the struct_ops in the system.
If *STRUCT_OPS_MAP* is specified, it dumps information only
for the given struct_ops. Otherwise, it dumps all struct_ops
currently existing in the system.
Dump details information about the struct_ops in the system. If
*STRUCT_OPS_MAP* is specified, it dumps information only for the given
struct_ops. Otherwise, it dumps all struct_ops currently existing in the
system.
**bpftool struct_ops register** *OBJ* [*LINK_DIR*]
Register bpf struct_ops from *OBJ*. All struct_ops under
the ELF section ".struct_ops" and ".struct_ops.link" will
be registered to its kernel subsystem. For each
struct_ops in the ".struct_ops.link" section, a link
will be created. You can give *LINK_DIR* to provide a
directory path where these links will be pinned with the
same name as their corresponding map name.
Register bpf struct_ops from *OBJ*. All struct_ops under the ELF section
".struct_ops" and ".struct_ops.link" will be registered to its kernel
subsystem. For each struct_ops in the ".struct_ops.link" section, a link
will be created. You can give *LINK_DIR* to provide a directory path where
these links will be pinned with the same name as their corresponding map
name.
**bpftool struct_ops unregister** *STRUCT_OPS_MAP*
Unregister the *STRUCT_OPS_MAP* from the kernel subsystem.

12
tools/bpf/bpftool/Documentation/bpftool.rst
View File

@ -52,11 +52,11 @@ SYNOPSIS
DESCRIPTION
===========
*bpftool* allows for inspection and simple modification of BPF objects
on the system.
*bpftool* allows for inspection and simple modification of BPF objects on the
system.
Note that format of the output of all tools is not guaranteed to be
stable and should not be depended upon.
Note that format of the output of all tools is not guaranteed to be stable and
should not be depended upon.
OPTIONS
=======
@ -66,5 +66,5 @@ OPTIONS
Allow loading maps with unknown map definitions.
-n, --nomount
Do not automatically attempt to mount any virtual file system
(such as tracefs or BPF virtual file system) when necessary.
Do not automatically attempt to mount any virtual file system (such as
tracefs or BPF virtual file system) when necessary.

22
tools/bpf/bpftool/Documentation/common_options.rst
View File

@ -4,22 +4,20 @@
Print short help message (similar to **bpftool help**).
-V, --version
Print bpftool's version number (similar to **bpftool version**), the
number of the libbpf version in use, and optional features that were
included when bpftool was compiled. Optional features include linking
against LLVM or libbfd to provide the disassembler for JIT-ted
programs (**bpftool prog dump jited**) and usage of BPF skeletons
(some features like **bpftool prog profile** or showing pids
associated to BPF objects may rely on it).
Print bpftool's version number (similar to **bpftool version**), the number
of the libbpf version in use, and optional features that were included when
bpftool was compiled. Optional features include linking against LLVM or
libbfd to provide the disassembler for JIT-ted programs (**bpftool prog
dump jited**) and usage of BPF skeletons (some features like **bpftool prog
profile** or showing pids associated to BPF objects may rely on it).
-j, --json
Generate JSON output. For commands that cannot produce JSON, this
option has no effect.
Generate JSON output. For commands that cannot produce JSON, this option
has no effect.
-p, --pretty
Generate human-readable JSON output. Implies **-j**.
-d, --debug
Print all logs available, even debug-level information. This includes
logs from libbpf as well as from the verifier, when attempting to
load programs.
Print all logs available, even debug-level information. This includes logs
from libbpf as well as from the verifier, when attempting to load programs.