bpftool: Use simpler indentation in source rST for documentation

+3 -3

tools/bpf/bpftool/Documentation/Makefile

··· 31 31 "\n" \ 32 32 "SEE ALSO\n" \ 33 33 "========\n" \ 34 - "\t**bpf**\ (2),\n" \ 35 - "\t**bpf-helpers**\\ (7)" \ 36 - $(foreach page,$(call list_pages,$(1)),",\n\t**$(page)**\\ (8)") \ 34 + "**bpf**\ (2),\n" \ 35 + "**bpf-helpers**\\ (7)" \ 36 + $(foreach page,$(call list_pages,$(1)),",\n**$(page)**\\ (8)") \ 37 37 "\n") 38 38 39 39 $(OUTPUT)%.8: %.rst

+47 -53

tools/bpf/bpftool/Documentation/bpftool-btf.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **btf** *COMMAND* 17 + **bpftool** [*OPTIONS*] **btf** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| | { **-B** | **--base-btf** } } 19 + *OPTIONS* := { |COMMON_OPTIONS| | { **-B** | **--base-btf** } } 20 20 21 - *COMMANDS* := { **dump** | **help** } 21 + *COMMANDS* := { **dump** | **help** } 22 22 23 23 BTF COMMANDS 24 24 ============= 25 25 26 - | **bpftool** **btf** { **show** | **list** } [**id** *BTF_ID*] 27 - | **bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*] 28 - | **bpftool** **btf help** 26 + | **bpftool** **btf** { **show** | **list** } [**id** *BTF_ID*] 27 + | **bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*] 28 + | **bpftool** **btf help** 29 29 | 30 - | *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* } 31 - | *FORMAT* := { **raw** | **c** } 32 - | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 33 - | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 30 + | *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* } 31 + | *FORMAT* := { **raw** | **c** } 32 + | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 33 + | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 34 34 35 35 DESCRIPTION 36 36 =========== 37 - **bpftool btf { show | list }** [**id** *BTF_ID*] 38 - Show information about loaded BTF objects. If a BTF ID is 39 - specified, show information only about given BTF object, 40 - otherwise list all BTF objects currently loaded on the 41 - system. 37 + **bpftool btf { show | list }** [**id** *BTF_ID*] 38 + Show information about loaded BTF objects. If a BTF ID is specified, show 39 + information only about given BTF object, otherwise list all BTF objects 40 + currently loaded on the system. 42 41 43 - Since Linux 5.8 bpftool is able to discover information about 44 - processes that hold open file descriptors (FDs) against BTF 45 - objects. On such kernels bpftool will automatically emit this 46 - information as well. 42 + Since Linux 5.8 bpftool is able to discover information about processes 43 + that hold open file descriptors (FDs) against BTF objects. On such kernels 44 + bpftool will automatically emit this information as well. 47 45 48 - **bpftool btf dump** *BTF_SRC* 49 - Dump BTF entries from a given *BTF_SRC*. 46 + **bpftool btf dump** *BTF_SRC* 47 + Dump BTF entries from a given *BTF_SRC*. 50 48 51 - When **id** is specified, BTF object with that ID will be 52 - loaded and all its BTF types emitted. 49 + When **id** is specified, BTF object with that ID will be loaded and all 50 + its BTF types emitted. 53 51 54 - When **map** is provided, it's expected that map has 55 - associated BTF object with BTF types describing key and 56 - value. It's possible to select whether to dump only BTF 57 - type(s) associated with key (**key**), value (**value**), 58 - both key and value (**kv**), or all BTF types present in 59 - associated BTF object (**all**). If not specified, **kv** 60 - is assumed. 52 + When **map** is provided, it's expected that map has associated BTF object 53 + with BTF types describing key and value. It's possible to select whether to 54 + dump only BTF type(s) associated with key (**key**), value (**value**), 55 + both key and value (**kv**), or all BTF types present in associated BTF 56 + object (**all**). If not specified, **kv** is assumed. 61 57 62 - When **prog** is provided, it's expected that program has 63 - associated BTF object with BTF types. 58 + When **prog** is provided, it's expected that program has associated BTF 59 + object with BTF types. 64 60 65 - When specifying *FILE*, an ELF file is expected, containing 66 - .BTF section with well-defined BTF binary format data, 67 - typically produced by clang or pahole. 61 + When specifying *FILE*, an ELF file is expected, containing .BTF section 62 + with well-defined BTF binary format data, typically produced by clang or 63 + pahole. 68 64 69 - **format** option can be used to override default (raw) 70 - output format. Raw (**raw**) or C-syntax (**c**) output 71 - formats are supported. 65 + **format** option can be used to override default (raw) output format. Raw 66 + (**raw**) or C-syntax (**c**) output formats are supported. 72 67 73 - **bpftool btf help** 74 - Print short help message. 68 + **bpftool btf help** 69 + Print short help message. 75 70 76 71 OPTIONS 77 72 ======= 78 - .. include:: common_options.rst 73 + .. include:: common_options.rst 79 74 80 - -B, --base-btf *FILE* 81 - Pass a base BTF object. Base BTF objects are typically used 82 - with BTF objects for kernel modules. To avoid duplicating 83 - all kernel symbols required by modules, BTF objects for 84 - modules are "split", they are built incrementally on top of 85 - the kernel (vmlinux) BTF object. So the base BTF reference 86 - should usually point to the kernel BTF. 75 + -B, --base-btf *FILE* 76 + Pass a base BTF object. Base BTF objects are typically used with BTF 77 + objects for kernel modules. To avoid duplicating all kernel symbols 78 + required by modules, BTF objects for modules are "split", they are 79 + built incrementally on top of the kernel (vmlinux) BTF object. So the 80 + base BTF reference should usually point to the kernel BTF. 87 81 88 - When the main BTF object to process (for example, the 89 - module BTF to dump) is passed as a *FILE*, bpftool attempts 90 - to autodetect the path for the base object, and passing 91 - this option is optional. When the main BTF object is passed 92 - through other handles, this option becomes necessary. 82 + When the main BTF object to process (for example, the module BTF to 83 + dump) is passed as a *FILE*, bpftool attempts to autodetect the path 84 + for the base object, and passing this option is optional. When the main 85 + BTF object is passed through other handles, this option becomes 86 + necessary. 93 87 94 88 EXAMPLES 95 89 ========

+97 -101

tools/bpf/bpftool/Documentation/bpftool-cgroup.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **cgroup** *COMMAND* 17 + **bpftool** [*OPTIONS*] **cgroup** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } } 19 + *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } } 20 20 21 - *COMMANDS* := 22 - { **show** | **list** | **tree** | **attach** | **detach** | **help** } 21 + *COMMANDS* := 22 + { **show** | **list** | **tree** | **attach** | **detach** | **help** } 23 23 24 24 CGROUP COMMANDS 25 25 =============== 26 26 27 - | **bpftool** **cgroup** { **show** | **list** } *CGROUP* [**effective**] 28 - | **bpftool** **cgroup tree** [*CGROUP_ROOT*] [**effective**] 29 - | **bpftool** **cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*] 30 - | **bpftool** **cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG* 31 - | **bpftool** **cgroup help** 27 + | **bpftool** **cgroup** { **show** | **list** } *CGROUP* [**effective**] 28 + | **bpftool** **cgroup tree** [*CGROUP_ROOT*] [**effective**] 29 + | **bpftool** **cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*] 30 + | **bpftool** **cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG* 31 + | **bpftool** **cgroup help** 32 32 | 33 - | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 34 - | *ATTACH_TYPE* := { **cgroup_inet_ingress** | **cgroup_inet_egress** | 35 - | **cgroup_inet_sock_create** | **cgroup_sock_ops** | 36 - | **cgroup_device** | **cgroup_inet4_bind** | **cgroup_inet6_bind** | 37 - | **cgroup_inet4_post_bind** | **cgroup_inet6_post_bind** | 38 - | **cgroup_inet4_connect** | **cgroup_inet6_connect** | 39 - | **cgroup_unix_connect** | **cgroup_inet4_getpeername** | 40 - | **cgroup_inet6_getpeername** | **cgroup_unix_getpeername** | 41 - | **cgroup_inet4_getsockname** | **cgroup_inet6_getsockname** | 42 - | **cgroup_unix_getsockname** | **cgroup_udp4_sendmsg** | 43 - | **cgroup_udp6_sendmsg** | **cgroup_unix_sendmsg** | 44 - | **cgroup_udp4_recvmsg** | **cgroup_udp6_recvmsg** | 45 - | **cgroup_unix_recvmsg** | **cgroup_sysctl** | 46 - | **cgroup_getsockopt** | **cgroup_setsockopt** | 47 - | **cgroup_inet_sock_release** } 48 - | *ATTACH_FLAGS* := { **multi** | **override** } 33 + | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 34 + | *ATTACH_TYPE* := { **cgroup_inet_ingress** | **cgroup_inet_egress** | 35 + | **cgroup_inet_sock_create** | **cgroup_sock_ops** | 36 + | **cgroup_device** | **cgroup_inet4_bind** | **cgroup_inet6_bind** | 37 + | **cgroup_inet4_post_bind** | **cgroup_inet6_post_bind** | 38 + | **cgroup_inet4_connect** | **cgroup_inet6_connect** | 39 + | **cgroup_unix_connect** | **cgroup_inet4_getpeername** | 40 + | **cgroup_inet6_getpeername** | **cgroup_unix_getpeername** | 41 + | **cgroup_inet4_getsockname** | **cgroup_inet6_getsockname** | 42 + | **cgroup_unix_getsockname** | **cgroup_udp4_sendmsg** | 43 + | **cgroup_udp6_sendmsg** | **cgroup_unix_sendmsg** | 44 + | **cgroup_udp4_recvmsg** | **cgroup_udp6_recvmsg** | 45 + | **cgroup_unix_recvmsg** | **cgroup_sysctl** | 46 + | **cgroup_getsockopt** | **cgroup_setsockopt** | 47 + | **cgroup_inet_sock_release** } 48 + | *ATTACH_FLAGS* := { **multi** | **override** } 49 49 50 50 DESCRIPTION 51 51 =========== 52 - **bpftool cgroup { show | list }** *CGROUP* [**effective**] 53 - List all programs attached to the cgroup *CGROUP*. 52 + **bpftool cgroup { show | list }** *CGROUP* [**effective**] 53 + List all programs attached to the cgroup *CGROUP*. 54 54 55 - Output will start with program ID followed by attach type, 56 - attach flags and program name. 55 + Output will start with program ID followed by attach type, attach flags and 56 + program name. 57 57 58 - If **effective** is specified retrieve effective programs that 59 - will execute for events within a cgroup. This includes 60 - inherited along with attached ones. 58 + If **effective** is specified retrieve effective programs that will execute 59 + for events within a cgroup. This includes inherited along with attached 60 + ones. 61 61 62 - **bpftool cgroup tree** [*CGROUP_ROOT*] [**effective**] 63 - Iterate over all cgroups in *CGROUP_ROOT* and list all 64 - attached programs. If *CGROUP_ROOT* is not specified, 65 - bpftool uses cgroup v2 mountpoint. 62 + **bpftool cgroup tree** [*CGROUP_ROOT*] [**effective**] 63 + Iterate over all cgroups in *CGROUP_ROOT* and list all attached programs. 64 + If *CGROUP_ROOT* is not specified, bpftool uses cgroup v2 mountpoint. 66 65 67 - The output is similar to the output of cgroup show/list 68 - commands: it starts with absolute cgroup path, followed by 69 - program ID, attach type, attach flags and program name. 66 + The output is similar to the output of cgroup show/list commands: it starts 67 + with absolute cgroup path, followed by program ID, attach type, attach 68 + flags and program name. 70 69 71 - If **effective** is specified retrieve effective programs that 72 - will execute for events within a cgroup. This includes 73 - inherited along with attached ones. 70 + If **effective** is specified retrieve effective programs that will execute 71 + for events within a cgroup. This includes inherited along with attached 72 + ones. 74 73 75 - **bpftool cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*] 76 - Attach program *PROG* to the cgroup *CGROUP* with attach type 77 - *ATTACH_TYPE* and optional *ATTACH_FLAGS*. 74 + **bpftool cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*] 75 + Attach program *PROG* to the cgroup *CGROUP* with attach type *ATTACH_TYPE* 76 + and optional *ATTACH_FLAGS*. 78 77 79 - *ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs 80 - some bpf program, the program in this cgroup yields to sub-cgroup 81 - program; **multi** if a sub-cgroup installs some bpf program, 82 - that cgroup program gets run in addition to the program in this 83 - cgroup. 78 + *ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs some 79 + bpf program, the program in this cgroup yields to sub-cgroup program; 80 + **multi** if a sub-cgroup installs some bpf program, that cgroup program 81 + gets run in addition to the program in this cgroup. 84 82 85 - Only one program is allowed to be attached to a cgroup with 86 - no attach flags or the **override** flag. Attaching another 87 - program will release old program and attach the new one. 83 + Only one program is allowed to be attached to a cgroup with no attach flags 84 + or the **override** flag. Attaching another program will release old 85 + program and attach the new one. 88 86 89 - Multiple programs are allowed to be attached to a cgroup with 90 - **multi**. They are executed in FIFO order (those that were 91 - attached first, run first). 87 + Multiple programs are allowed to be attached to a cgroup with **multi**. 88 + They are executed in FIFO order (those that were attached first, run 89 + first). 92 90 93 - Non-default *ATTACH_FLAGS* are supported by kernel version 4.14 94 - and later. 91 + Non-default *ATTACH_FLAGS* are supported by kernel version 4.14 and later. 95 92 96 - *ATTACH_TYPE* can be on of: 97 - **ingress** ingress path of the inet socket (since 4.10); 98 - **egress** egress path of the inet socket (since 4.10); 99 - **sock_create** opening of an inet socket (since 4.10); 100 - **sock_ops** various socket operations (since 4.12); 101 - **device** device access (since 4.15); 102 - **bind4** call to bind(2) for an inet4 socket (since 4.17); 103 - **bind6** call to bind(2) for an inet6 socket (since 4.17); 104 - **post_bind4** return from bind(2) for an inet4 socket (since 4.17); 105 - **post_bind6** return from bind(2) for an inet6 socket (since 4.17); 106 - **connect4** call to connect(2) for an inet4 socket (since 4.17); 107 - **connect6** call to connect(2) for an inet6 socket (since 4.17); 108 - **connect_unix** call to connect(2) for a unix socket (since 6.7); 109 - **sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an 110 - unconnected udp4 socket (since 4.18); 111 - **sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an 112 - unconnected udp6 socket (since 4.18); 113 - **sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for 114 - an unconnected unix socket (since 6.7); 115 - **recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for 116 - an unconnected udp4 socket (since 5.2); 117 - **recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for 118 - an unconnected udp6 socket (since 5.2); 119 - **recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for 120 - an unconnected unix socket (since 6.7); 121 - **sysctl** sysctl access (since 5.2); 122 - **getsockopt** call to getsockopt (since 5.3); 123 - **setsockopt** call to setsockopt (since 5.3); 124 - **getpeername4** call to getpeername(2) for an inet4 socket (since 5.8); 125 - **getpeername6** call to getpeername(2) for an inet6 socket (since 5.8); 126 - **getpeername_unix** call to getpeername(2) for a unix socket (since 6.7); 127 - **getsockname4** call to getsockname(2) for an inet4 socket (since 5.8); 128 - **getsockname6** call to getsockname(2) for an inet6 socket (since 5.8). 129 - **getsockname_unix** call to getsockname(2) for a unix socket (since 6.7); 130 - **sock_release** closing an userspace inet socket (since 5.9). 93 + *ATTACH_TYPE* can be on of: 94 + **ingress** ingress path of the inet socket (since 4.10); 95 + **egress** egress path of the inet socket (since 4.10); 96 + **sock_create** opening of an inet socket (since 4.10); 97 + **sock_ops** various socket operations (since 4.12); 98 + **device** device access (since 4.15); 99 + **bind4** call to bind(2) for an inet4 socket (since 4.17); 100 + **bind6** call to bind(2) for an inet6 socket (since 4.17); 101 + **post_bind4** return from bind(2) for an inet4 socket (since 4.17); 102 + **post_bind6** return from bind(2) for an inet6 socket (since 4.17); 103 + **connect4** call to connect(2) for an inet4 socket (since 4.17); 104 + **connect6** call to connect(2) for an inet6 socket (since 4.17); 105 + **connect_unix** call to connect(2) for a unix socket (since 6.7); 106 + **sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected 107 + udp4 socket (since 4.18); 108 + **sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected 109 + udp6 socket (since 4.18); 110 + **sendmsg_unix** call to sendto(2), sendmsg(2), sendmmsg(2) for an 111 + unconnected unix socket (since 6.7); 112 + **recvmsg4** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an 113 + unconnected udp4 socket (since 5.2); 114 + **recvmsg6** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an 115 + unconnected udp6 socket (since 5.2); 116 + **recvmsg_unix** call to recvfrom(2), recvmsg(2), recvmmsg(2) for an 117 + unconnected unix socket (since 6.7); 118 + **sysctl** sysctl access (since 5.2); 119 + **getsockopt** call to getsockopt (since 5.3); 120 + **setsockopt** call to setsockopt (since 5.3); 121 + **getpeername4** call to getpeername(2) for an inet4 socket (since 5.8); 122 + **getpeername6** call to getpeername(2) for an inet6 socket (since 5.8); 123 + **getpeername_unix** call to getpeername(2) for a unix socket (since 6.7); 124 + **getsockname4** call to getsockname(2) for an inet4 socket (since 5.8); 125 + **getsockname6** call to getsockname(2) for an inet6 socket (since 5.8). 126 + **getsockname_unix** call to getsockname(2) for a unix socket (since 6.7); 127 + **sock_release** closing an userspace inet socket (since 5.9). 131 128 132 - **bpftool cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG* 133 - Detach *PROG* from the cgroup *CGROUP* and attach type 134 - *ATTACH_TYPE*. 129 + **bpftool cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG* 130 + Detach *PROG* from the cgroup *CGROUP* and attach type *ATTACH_TYPE*. 135 131 136 - **bpftool prog help** 137 - Print short help message. 132 + **bpftool prog help** 133 + Print short help message. 138 134 139 135 OPTIONS 140 136 ======= 141 - .. include:: common_options.rst 137 + .. include:: common_options.rst 142 138 143 - -f, --bpffs 144 - Show file names of pinned programs. 139 + -f, --bpffs 140 + Show file names of pinned programs. 145 141 146 142 EXAMPLES 147 143 ========

+46 -53

tools/bpf/bpftool/Documentation/bpftool-feature.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **feature** *COMMAND* 17 + **bpftool** [*OPTIONS*] **feature** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| } 19 + *OPTIONS* := { |COMMON_OPTIONS| } 20 20 21 - *COMMANDS* := { **probe** | **help** } 21 + *COMMANDS* := { **probe** | **help** } 22 22 23 23 FEATURE COMMANDS 24 24 ================ 25 25 26 - | **bpftool** **feature probe** [*COMPONENT*] [**full**] [**unprivileged**] [**macros** [**prefix** *PREFIX*]] 27 - | **bpftool** **feature list_builtins** *GROUP* 28 - | **bpftool** **feature help** 26 + | **bpftool** **feature probe** [*COMPONENT*] [**full**] [**unprivileged**] [**macros** [**prefix** *PREFIX*]] 27 + | **bpftool** **feature list_builtins** *GROUP* 28 + | **bpftool** **feature help** 29 29 | 30 - | *COMPONENT* := { **kernel** | **dev** *NAME* } 31 - | *GROUP* := { **prog_types** | **map_types** | **attach_types** | **link_types** | **helpers** } 30 + | *COMPONENT* := { **kernel** | **dev** *NAME* } 31 + | *GROUP* := { **prog_types** | **map_types** | **attach_types** | **link_types** | **helpers** } 32 32 33 33 DESCRIPTION 34 34 =========== 35 - **bpftool feature probe** [**kernel**] [**full**] [**macros** [**prefix** *PREFIX*]] 36 - Probe the running kernel and dump a number of eBPF-related 37 - parameters, such as availability of the **bpf**\ () system call, 38 - JIT status, eBPF program types availability, eBPF helper 39 - functions availability, and more. 35 + **bpftool feature probe** [**kernel**] [**full**] [**macros** [**prefix** *PREFIX*]] 36 + Probe the running kernel and dump a number of eBPF-related parameters, such 37 + as availability of the **bpf**\ () system call, JIT status, eBPF program 38 + types availability, eBPF helper functions availability, and more. 40 39 41 - By default, bpftool **does not run probes** for 42 - **bpf_probe_write_user**\ () and **bpf_trace_printk**\() 43 - helpers which print warnings to kernel logs. To enable them 44 - and run all probes, the **full** keyword should be used. 40 + By default, bpftool **does not run probes** for **bpf_probe_write_user**\ 41 + () and **bpf_trace_printk**\() helpers which print warnings to kernel logs. 42 + To enable them and run all probes, the **full** keyword should be used. 45 43 46 - If the **macros** keyword (but not the **-j** option) is 47 - passed, a subset of the output is dumped as a list of 48 - **#define** macros that are ready to be included in a C 49 - header file, for example. If, additionally, **prefix** is 50 - used to define a *PREFIX*, the provided string will be used 51 - as a prefix to the names of the macros: this can be used to 52 - avoid conflicts on macro names when including the output of 53 - this command as a header file. 44 + If the **macros** keyword (but not the **-j** option) is passed, a subset 45 + of the output is dumped as a list of **#define** macros that are ready to 46 + be included in a C header file, for example. If, additionally, **prefix** 47 + is used to define a *PREFIX*, the provided string will be used as a prefix 48 + to the names of the macros: this can be used to avoid conflicts on macro 49 + names when including the output of this command as a header file. 54 50 55 - Keyword **kernel** can be omitted. If no probe target is 56 - specified, probing the kernel is the default behaviour. 51 + Keyword **kernel** can be omitted. If no probe target is specified, probing 52 + the kernel is the default behaviour. 57 53 58 - When the **unprivileged** keyword is used, bpftool will dump 59 - only the features available to a user who does not have the 60 - **CAP_SYS_ADMIN** capability set. The features available in 61 - that case usually represent a small subset of the parameters 62 - supported by the system. Unprivileged users MUST use the 63 - **unprivileged** keyword: This is to avoid misdetection if 64 - bpftool is inadvertently run as non-root, for example. This 65 - keyword is unavailable if bpftool was compiled without 66 - libcap. 54 + When the **unprivileged** keyword is used, bpftool will dump only the 55 + features available to a user who does not have the **CAP_SYS_ADMIN** 56 + capability set. The features available in that case usually represent a 57 + small subset of the parameters supported by the system. Unprivileged users 58 + MUST use the **unprivileged** keyword: This is to avoid misdetection if 59 + bpftool is inadvertently run as non-root, for example. This keyword is 60 + unavailable if bpftool was compiled without libcap. 67 61 68 - **bpftool feature probe dev** *NAME* [**full**] [**macros** [**prefix** *PREFIX*]] 69 - Probe network device for supported eBPF features and dump 70 - results to the console. 62 + **bpftool feature probe dev** *NAME* [**full**] [**macros** [**prefix** *PREFIX*]] 63 + Probe network device for supported eBPF features and dump results to the 64 + console. 71 65 72 - The keywords **full**, **macros** and **prefix** have the 73 - same role as when probing the kernel. 66 + The keywords **full**, **macros** and **prefix** have the same role as when 67 + probing the kernel. 74 68 75 - **bpftool feature list_builtins** *GROUP* 76 - List items known to bpftool. These can be BPF program types 77 - (**prog_types**), BPF map types (**map_types**), attach types 78 - (**attach_types**), link types (**link_types**), or BPF helper 79 - functions (**helpers**). The command does not probe the system, but 80 - simply lists the elements that bpftool knows from compilation time, 81 - as provided from libbpf (for all object types) or from the BPF UAPI 82 - header (list of helpers). This can be used in scripts to iterate over 83 - BPF types or helpers. 69 + **bpftool feature list_builtins** *GROUP* 70 + List items known to bpftool. These can be BPF program types 71 + (**prog_types**), BPF map types (**map_types**), attach types 72 + (**attach_types**), link types (**link_types**), or BPF helper functions 73 + (**helpers**). The command does not probe the system, but simply lists the 74 + elements that bpftool knows from compilation time, as provided from libbpf 75 + (for all object types) or from the BPF UAPI header (list of helpers). This 76 + can be used in scripts to iterate over BPF types or helpers. 84 77 85 - **bpftool feature help** 86 - Print short help message. 78 + **bpftool feature help** 79 + Print short help message. 87 80 88 81 OPTIONS 89 82 ======= 90 - .. include:: common_options.rst 83 + .. include:: common_options.rst

+131 -153

tools/bpf/bpftool/Documentation/bpftool-gen.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **gen** *COMMAND* 17 + **bpftool** [*OPTIONS*] **gen** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| | { **-L** | **--use-loader** } } 19 + *OPTIONS* := { |COMMON_OPTIONS| | { **-L** | **--use-loader** } } 20 20 21 - *COMMAND* := { **object** | **skeleton** | **help** } 21 + *COMMAND* := { **object** | **skeleton** | **help** } 22 22 23 23 GEN COMMANDS 24 24 ============= 25 25 26 - | **bpftool** **gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...] 27 - | **bpftool** **gen skeleton** *FILE* [**name** *OBJECT_NAME*] 28 - | **bpftool** **gen subskeleton** *FILE* [**name** *OBJECT_NAME*] 29 - | **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...] 30 - | **bpftool** **gen help** 26 + | **bpftool** **gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...] 27 + | **bpftool** **gen skeleton** *FILE* [**name** *OBJECT_NAME*] 28 + | **bpftool** **gen subskeleton** *FILE* [**name** *OBJECT_NAME*] 29 + | **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...] 30 + | **bpftool** **gen help** 31 31 32 32 DESCRIPTION 33 33 =========== 34 - **bpftool gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...] 35 - Statically link (combine) together one or more *INPUT_FILE*'s 36 - into a single resulting *OUTPUT_FILE*. All the files involved 37 - are BPF ELF object files. 34 + **bpftool gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...] 35 + Statically link (combine) together one or more *INPUT_FILE*'s into a single 36 + resulting *OUTPUT_FILE*. All the files involved are BPF ELF object files. 38 37 39 - The rules of BPF static linking are mostly the same as for 40 - user-space object files, but in addition to combining data 41 - and instruction sections, .BTF and .BTF.ext (if present in 42 - any of the input files) data are combined together. .BTF 43 - data is deduplicated, so all the common types across 44 - *INPUT_FILE*'s will only be represented once in the resulting 45 - BTF information. 38 + The rules of BPF static linking are mostly the same as for user-space 39 + object files, but in addition to combining data and instruction sections, 40 + .BTF and .BTF.ext (if present in any of the input files) data are combined 41 + together. .BTF data is deduplicated, so all the common types across 42 + *INPUT_FILE*'s will only be represented once in the resulting BTF 43 + information. 46 44 47 - BPF static linking allows to partition BPF source code into 48 - individually compiled files that are then linked into 49 - a single resulting BPF object file, which can be used to 50 - generated BPF skeleton (with **gen skeleton** command) or 51 - passed directly into **libbpf** (using **bpf_object__open()** 52 - family of APIs). 45 + BPF static linking allows to partition BPF source code into individually 46 + compiled files that are then linked into a single resulting BPF object 47 + file, which can be used to generated BPF skeleton (with **gen skeleton** 48 + command) or passed directly into **libbpf** (using **bpf_object__open()** 49 + family of APIs). 53 50 54 - **bpftool gen skeleton** *FILE* 55 - Generate BPF skeleton C header file for a given *FILE*. 51 + **bpftool gen skeleton** *FILE* 52 + Generate BPF skeleton C header file for a given *FILE*. 56 53 57 - BPF skeleton is an alternative interface to existing libbpf 58 - APIs for working with BPF objects. Skeleton code is intended 59 - to significantly shorten and simplify code to load and work 60 - with BPF programs from userspace side. Generated code is 61 - tailored to specific input BPF object *FILE*, reflecting its 62 - structure by listing out available maps, program, variables, 63 - etc. Skeleton eliminates the need to lookup mentioned 64 - components by name. Instead, if skeleton instantiation 65 - succeeds, they are populated in skeleton structure as valid 66 - libbpf types (e.g., **struct bpf_map** pointer) and can be 67 - passed to existing generic libbpf APIs. 54 + BPF skeleton is an alternative interface to existing libbpf APIs for 55 + working with BPF objects. Skeleton code is intended to significantly 56 + shorten and simplify code to load and work with BPF programs from userspace 57 + side. Generated code is tailored to specific input BPF object *FILE*, 58 + reflecting its structure by listing out available maps, program, variables, 59 + etc. Skeleton eliminates the need to lookup mentioned components by name. 60 + Instead, if skeleton instantiation succeeds, they are populated in skeleton 61 + structure as valid libbpf types (e.g., **struct bpf_map** pointer) and can 62 + be passed to existing generic libbpf APIs. 68 63 69 - In addition to simple and reliable access to maps and 70 - programs, skeleton provides a storage for BPF links (**struct 71 - bpf_link**) for each BPF program within BPF object. When 72 - requested, supported BPF programs will be automatically 73 - attached and resulting BPF links stored for further use by 74 - user in pre-allocated fields in skeleton struct. For BPF 75 - programs that can't be automatically attached by libbpf, 76 - user can attach them manually, but store resulting BPF link 77 - in per-program link field. All such set up links will be 78 - automatically destroyed on BPF skeleton destruction. This 79 - eliminates the need for users to manage links manually and 80 - rely on libbpf support to detach programs and free up 81 - resources. 64 + In addition to simple and reliable access to maps and programs, skeleton 65 + provides a storage for BPF links (**struct bpf_link**) for each BPF program 66 + within BPF object. When requested, supported BPF programs will be 67 + automatically attached and resulting BPF links stored for further use by 68 + user in pre-allocated fields in skeleton struct. For BPF programs that 69 + can't be automatically attached by libbpf, user can attach them manually, 70 + but store resulting BPF link in per-program link field. All such set up 71 + links will be automatically destroyed on BPF skeleton destruction. This 72 + eliminates the need for users to manage links manually and rely on libbpf 73 + support to detach programs and free up resources. 82 74 83 - Another facility provided by BPF skeleton is an interface to 84 - global variables of all supported kinds: mutable, read-only, 85 - as well as extern ones. This interface allows to pre-setup 86 - initial values of variables before BPF object is loaded and 87 - verified by kernel. For non-read-only variables, the same 88 - interface can be used to fetch values of global variables on 89 - userspace side, even if they are modified by BPF code. 75 + Another facility provided by BPF skeleton is an interface to global 76 + variables of all supported kinds: mutable, read-only, as well as extern 77 + ones. This interface allows to pre-setup initial values of variables before 78 + BPF object is loaded and verified by kernel. For non-read-only variables, 79 + the same interface can be used to fetch values of global variables on 80 + userspace side, even if they are modified by BPF code. 90 81 91 - During skeleton generation, contents of source BPF object 92 - *FILE* is embedded within generated code and is thus not 93 - necessary to keep around. This ensures skeleton and BPF 94 - object file are matching 1-to-1 and always stay in sync. 95 - Generated code is dual-licensed under LGPL-2.1 and 96 - BSD-2-Clause licenses. 82 + During skeleton generation, contents of source BPF object *FILE* is 83 + embedded within generated code and is thus not necessary to keep around. 84 + This ensures skeleton and BPF object file are matching 1-to-1 and always 85 + stay in sync. Generated code is dual-licensed under LGPL-2.1 and 86 + BSD-2-Clause licenses. 97 87 98 - It is a design goal and guarantee that skeleton interfaces 99 - are interoperable with generic libbpf APIs. User should 100 - always be able to use skeleton API to create and load BPF 101 - object, and later use libbpf APIs to keep working with 102 - specific maps, programs, etc. 88 + It is a design goal and guarantee that skeleton interfaces are 89 + interoperable with generic libbpf APIs. User should always be able to use 90 + skeleton API to create and load BPF object, and later use libbpf APIs to 91 + keep working with specific maps, programs, etc. 103 92 104 - As part of skeleton, few custom functions are generated. 105 - Each of them is prefixed with object name. Object name can 106 - either be derived from object file name, i.e., if BPF object 107 - file name is **example.o**, BPF object name will be 108 - **example**. Object name can be also specified explicitly 109 - through **name** *OBJECT_NAME* parameter. The following 110 - custom functions are provided (assuming **example** as 111 - the object name): 93 + As part of skeleton, few custom functions are generated. Each of them is 94 + prefixed with object name. Object name can either be derived from object 95 + file name, i.e., if BPF object file name is **example.o**, BPF object name 96 + will be **example**. Object name can be also specified explicitly through 97 + **name** *OBJECT_NAME* parameter. The following custom functions are 98 + provided (assuming **example** as the object name): 112 99 113 - - **example__open** and **example__open_opts**. 114 - These functions are used to instantiate skeleton. It 115 - corresponds to libbpf's **bpf_object__open**\ () API. 116 - **_opts** variants accepts extra **bpf_object_open_opts** 117 - options. 100 + - **example__open** and **example__open_opts**. 101 + These functions are used to instantiate skeleton. It corresponds to 102 + libbpf's **bpf_object__open**\ () API. **_opts** variants accepts extra 103 + **bpf_object_open_opts** options. 118 104 119 - - **example__load**. 120 - This function creates maps, loads and verifies BPF 121 - programs, initializes global data maps. It corresponds to 122 - libppf's **bpf_object__load**\ () API. 105 + - **example__load**. 106 + This function creates maps, loads and verifies BPF programs, initializes 107 + global data maps. It corresponds to libppf's **bpf_object__load**\ () 108 + API. 123 109 124 - - **example__open_and_load** combines **example__open** and 125 - **example__load** invocations in one commonly used 126 - operation. 110 + - **example__open_and_load** combines **example__open** and 111 + **example__load** invocations in one commonly used operation. 127 112 128 - - **example__attach** and **example__detach** 129 - This pair of functions allow to attach and detach, 130 - correspondingly, already loaded BPF object. Only BPF 131 - programs of types supported by libbpf for auto-attachment 132 - will be auto-attached and their corresponding BPF links 133 - instantiated. For other BPF programs, user can manually 134 - create a BPF link and assign it to corresponding fields in 135 - skeleton struct. **example__detach** will detach both 136 - links created automatically, as well as those populated by 137 - user manually. 113 + - **example__attach** and **example__detach** 114 + This pair of functions allow to attach and detach, correspondingly, 115 + already loaded BPF object. Only BPF programs of types supported by libbpf 116 + for auto-attachment will be auto-attached and their corresponding BPF 117 + links instantiated. For other BPF programs, user can manually create a 118 + BPF link and assign it to corresponding fields in skeleton struct. 119 + **example__detach** will detach both links created automatically, as well 120 + as those populated by user manually. 138 121 139 - - **example__destroy** 140 - Detach and unload BPF programs, free up all the resources 141 - used by skeleton and BPF object. 122 + - **example__destroy** 123 + Detach and unload BPF programs, free up all the resources used by 124 + skeleton and BPF object. 142 125 143 - If BPF object has global variables, corresponding structs 144 - with memory layout corresponding to global data data section 145 - layout will be created. Currently supported ones are: *.data*, 146 - *.bss*, *.rodata*, and *.kconfig* structs/data sections. 147 - These data sections/structs can be used to set up initial 148 - values of variables, if set before **example__load**. 149 - Afterwards, if target kernel supports memory-mapped BPF 150 - arrays, same structs can be used to fetch and update 151 - (non-read-only) data from userspace, with same simplicity 152 - as for BPF side. 126 + If BPF object has global variables, corresponding structs with memory 127 + layout corresponding to global data data section layout will be created. 128 + Currently supported ones are: *.data*, *.bss*, *.rodata*, and *.kconfig* 129 + structs/data sections. These data sections/structs can be used to set up 130 + initial values of variables, if set before **example__load**. Afterwards, 131 + if target kernel supports memory-mapped BPF arrays, same structs can be 132 + used to fetch and update (non-read-only) data from userspace, with same 133 + simplicity as for BPF side. 153 134 154 - **bpftool gen subskeleton** *FILE* 155 - Generate BPF subskeleton C header file for a given *FILE*. 135 + **bpftool gen subskeleton** *FILE* 136 + Generate BPF subskeleton C header file for a given *FILE*. 156 137 157 - Subskeletons are similar to skeletons, except they do not own 158 - the corresponding maps, programs, or global variables. They 159 - require that the object file used to generate them is already 160 - loaded into a *bpf_object* by some other means. 138 + Subskeletons are similar to skeletons, except they do not own the 139 + corresponding maps, programs, or global variables. They require that the 140 + object file used to generate them is already loaded into a *bpf_object* by 141 + some other means. 161 142 162 - This functionality is useful when a library is included into a 163 - larger BPF program. A subskeleton for the library would have 164 - access to all objects and globals defined in it, without 165 - having to know about the larger program. 143 + This functionality is useful when a library is included into a larger BPF 144 + program. A subskeleton for the library would have access to all objects and 145 + globals defined in it, without having to know about the larger program. 166 146 167 - Consequently, there are only two functions defined 168 - for subskeletons: 147 + Consequently, there are only two functions defined for subskeletons: 169 148 170 - - **example__open(bpf_object\*)** 171 - Instantiates a subskeleton from an already opened (but not 172 - necessarily loaded) **bpf_object**. 149 + - **example__open(bpf_object\*)** 150 + Instantiates a subskeleton from an already opened (but not necessarily 151 + loaded) **bpf_object**. 173 152 174 - - **example__destroy()** 175 - Frees the storage for the subskeleton but *does not* unload 176 - any BPF programs or maps. 153 + - **example__destroy()** 154 + Frees the storage for the subskeleton but *does not* unload any BPF 155 + programs or maps. 177 156 178 - **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...] 179 - Generate a minimum BTF file as *OUTPUT*, derived from a given 180 - *INPUT* BTF file, containing all needed BTF types so one, or 181 - more, given eBPF objects CO-RE relocations may be satisfied. 157 + **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...] 158 + Generate a minimum BTF file as *OUTPUT*, derived from a given *INPUT* BTF 159 + file, containing all needed BTF types so one, or more, given eBPF objects 160 + CO-RE relocations may be satisfied. 182 161 183 - When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF, 184 - libbpf, when loading an eBPF object, has to rely on external 185 - BTF files to be able to calculate CO-RE relocations. 162 + When kernels aren't compiled with CONFIG_DEBUG_INFO_BTF, libbpf, when 163 + loading an eBPF object, has to rely on external BTF files to be able to 164 + calculate CO-RE relocations. 186 165 187 - Usually, an external BTF file is built from existing kernel 188 - DWARF data using pahole. It contains all the types used by 189 - its respective kernel image and, because of that, is big. 166 + Usually, an external BTF file is built from existing kernel DWARF data 167 + using pahole. It contains all the types used by its respective kernel image 168 + and, because of that, is big. 190 169 191 - The min_core_btf feature builds smaller BTF files, customized 192 - to one or multiple eBPF objects, so they can be distributed 193 - together with an eBPF CO-RE based application, turning the 194 - application portable to different kernel versions. 170 + The min_core_btf feature builds smaller BTF files, customized to one or 171 + multiple eBPF objects, so they can be distributed together with an eBPF 172 + CO-RE based application, turning the application portable to different 173 + kernel versions. 195 174 196 - Check examples bellow for more information how to use it. 175 + Check examples bellow for more information how to use it. 197 176 198 - **bpftool gen help** 199 - Print short help message. 177 + **bpftool gen help** 178 + Print short help message. 200 179 201 180 OPTIONS 202 181 ======= 203 - .. include:: common_options.rst 182 + .. include:: common_options.rst 204 183 205 - -L, --use-loader 206 - For skeletons, generate a "light" skeleton (also known as "loader" 207 - skeleton). A light skeleton contains a loader eBPF program. It does 208 - not use the majority of the libbpf infrastructure, and does not need 209 - libelf. 184 + -L, --use-loader 185 + For skeletons, generate a "light" skeleton (also known as "loader" 186 + skeleton). A light skeleton contains a loader eBPF program. It does not use 187 + the majority of the libbpf infrastructure, and does not need libelf. 210 188 211 189 EXAMPLES 212 190 ========

+23 -27

tools/bpf/bpftool/Documentation/bpftool-iter.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **iter** *COMMAND* 17 + **bpftool** [*OPTIONS*] **iter** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| } 19 + *OPTIONS* := { |COMMON_OPTIONS| } 20 20 21 - *COMMANDS* := { **pin** | **help** } 21 + *COMMANDS* := { **pin** | **help** } 22 22 23 23 ITER COMMANDS 24 24 =================== 25 25 26 - | **bpftool** **iter pin** *OBJ* *PATH* [**map** *MAP*] 27 - | **bpftool** **iter help** 26 + | **bpftool** **iter pin** *OBJ* *PATH* [**map** *MAP*] 27 + | **bpftool** **iter help** 28 28 | 29 - | *OBJ* := /a/file/of/bpf_iter_target.o 30 - | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 29 + | *OBJ* := /a/file/of/bpf_iter_target.o 30 + | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 31 31 32 32 DESCRIPTION 33 33 =========== 34 - **bpftool iter pin** *OBJ* *PATH* [**map** *MAP*] 35 - A bpf iterator combines a kernel iterating of 36 - particular kernel data (e.g., tasks, bpf_maps, etc.) 37 - and a bpf program called for each kernel data object 38 - (e.g., one task, one bpf_map, etc.). User space can 39 - *read* kernel iterator output through *read()* syscall. 34 + **bpftool iter pin** *OBJ* *PATH* [**map** *MAP*] 35 + A bpf iterator combines a kernel iterating of particular kernel data (e.g., 36 + tasks, bpf_maps, etc.) and a bpf program called for each kernel data object 37 + (e.g., one task, one bpf_map, etc.). User space can *read* kernel iterator 38 + output through *read()* syscall. 40 39 41 - The *pin* command creates a bpf iterator from *OBJ*, 42 - and pin it to *PATH*. The *PATH* should be located 43 - in *bpffs* mount. It must not contain a dot 44 - character ('.'), which is reserved for future extensions 45 - of *bpffs*. 40 + The *pin* command creates a bpf iterator from *OBJ*, and pin it to *PATH*. 41 + The *PATH* should be located in *bpffs* mount. It must not contain a dot 42 + character ('.'), which is reserved for future extensions of *bpffs*. 46 43 47 - Map element bpf iterator requires an additional parameter 48 - *MAP* so bpf program can iterate over map elements for 49 - that map. User can have a bpf program in kernel to run 50 - with each map element, do checking, filtering, aggregation, 51 - etc. without copying data to user space. 44 + Map element bpf iterator requires an additional parameter *MAP* so bpf 45 + program can iterate over map elements for that map. User can have a bpf 46 + program in kernel to run with each map element, do checking, filtering, 47 + aggregation, etc. without copying data to user space. 52 48 53 - User can then *cat PATH* to see the bpf iterator output. 49 + User can then *cat PATH* to see the bpf iterator output. 54 50 55 - **bpftool iter help** 56 - Print short help message. 51 + **bpftool iter help** 52 + Print short help message. 57 53 58 54 OPTIONS 59 55 ======= 60 - .. include:: common_options.rst 56 + .. include:: common_options.rst 61 57 62 58 EXAMPLES 63 59 ========

+34 -39

tools/bpf/bpftool/Documentation/bpftool-link.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **link** *COMMAND* 17 + **bpftool** [*OPTIONS*] **link** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } } 19 + *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } } 20 20 21 - *COMMANDS* := { **show** | **list** | **pin** | **help** } 21 + *COMMANDS* := { **show** | **list** | **pin** | **help** } 22 22 23 23 LINK COMMANDS 24 24 ============= 25 25 26 - | **bpftool** **link { show | list }** [*LINK*] 27 - | **bpftool** **link pin** *LINK* *FILE* 28 - | **bpftool** **link detach** *LINK* 29 - | **bpftool** **link help** 26 + | **bpftool** **link { show | list }** [*LINK*] 27 + | **bpftool** **link pin** *LINK* *FILE* 28 + | **bpftool** **link detach** *LINK* 29 + | **bpftool** **link help** 30 30 | 31 - | *LINK* := { **id** *LINK_ID* | **pinned** *FILE* } 31 + | *LINK* := { **id** *LINK_ID* | **pinned** *FILE* } 32 32 33 33 34 34 DESCRIPTION 35 35 =========== 36 - **bpftool link { show | list }** [*LINK*] 37 - Show information about active links. If *LINK* is 38 - specified show information only about given link, 39 - otherwise list all links currently active on the system. 36 + **bpftool link { show | list }** [*LINK*] 37 + Show information about active links. If *LINK* is specified show 38 + information only about given link, otherwise list all links currently 39 + active on the system. 40 40 41 - Output will start with link ID followed by link type and 42 - zero or more named attributes, some of which depend on type 43 - of link. 41 + Output will start with link ID followed by link type and zero or more named 42 + attributes, some of which depend on type of link. 44 43 45 - Since Linux 5.8 bpftool is able to discover information about 46 - processes that hold open file descriptors (FDs) against BPF 47 - links. On such kernels bpftool will automatically emit this 48 - information as well. 44 + Since Linux 5.8 bpftool is able to discover information about processes 45 + that hold open file descriptors (FDs) against BPF links. On such kernels 46 + bpftool will automatically emit this information as well. 49 47 50 - **bpftool link pin** *LINK* *FILE* 51 - Pin link *LINK* as *FILE*. 48 + **bpftool link pin** *LINK* *FILE* 49 + Pin link *LINK* as *FILE*. 52 50 53 - Note: *FILE* must be located in *bpffs* mount. It must not 54 - contain a dot character ('.'), which is reserved for future 55 - extensions of *bpffs*. 51 + Note: *FILE* must be located in *bpffs* mount. It must not contain a dot 52 + character ('.'), which is reserved for future extensions of *bpffs*. 56 53 57 - **bpftool link detach** *LINK* 58 - Force-detach link *LINK*. BPF link and its underlying BPF 59 - program will stay valid, but they will be detached from the 60 - respective BPF hook and BPF link will transition into 61 - a defunct state until last open file descriptor for that 62 - link is closed. 54 + **bpftool link detach** *LINK* 55 + Force-detach link *LINK*. BPF link and its underlying BPF program will stay 56 + valid, but they will be detached from the respective BPF hook and BPF link 57 + will transition into a defunct state until last open file descriptor for 58 + that link is closed. 63 59 64 - **bpftool link help** 65 - Print short help message. 60 + **bpftool link help** 61 + Print short help message. 66 62 67 63 OPTIONS 68 64 ======= 69 - .. include:: common_options.rst 65 + .. include:: common_options.rst 70 66 71 - -f, --bpffs 72 - When showing BPF links, show file names of pinned 73 - links. 67 + -f, --bpffs 68 + When showing BPF links, show file names of pinned links. 74 69 75 - -n, --nomount 76 - Do not automatically attempt to mount any virtual file system 77 - (such as tracefs or BPF virtual file system) when necessary. 70 + -n, --nomount 71 + Do not automatically attempt to mount any virtual file system (such as 72 + tracefs or BPF virtual file system) when necessary. 78 73 79 74 EXAMPLES 80 75 ========

+113 -119

tools/bpf/bpftool/Documentation/bpftool-map.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **map** *COMMAND* 17 + **bpftool** [*OPTIONS*] **map** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } } 19 + *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } } 20 20 21 - *COMMANDS* := 22 - { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** | 23 - **delete** | **pin** | **help** } 21 + *COMMANDS* := 22 + { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** | 23 + **delete** | **pin** | **help** } 24 24 25 25 MAP COMMANDS 26 26 ============= 27 27 28 - | **bpftool** **map** { **show** | **list** } [*MAP*] 29 - | **bpftool** **map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \ 30 - | **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] \ 31 - | [**offload_dev** *NAME*] 32 - | **bpftool** **map dump** *MAP* 33 - | **bpftool** **map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 34 - | **bpftool** **map lookup** *MAP* [**key** *DATA*] 35 - | **bpftool** **map getnext** *MAP* [**key** *DATA*] 36 - | **bpftool** **map delete** *MAP* **key** *DATA* 37 - | **bpftool** **map pin** *MAP* *FILE* 38 - | **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 39 - | **bpftool** **map peek** *MAP* 40 - | **bpftool** **map push** *MAP* **value** *VALUE* 41 - | **bpftool** **map pop** *MAP* 42 - | **bpftool** **map enqueue** *MAP* **value** *VALUE* 43 - | **bpftool** **map dequeue** *MAP* 44 - | **bpftool** **map freeze** *MAP* 45 - | **bpftool** **map help** 28 + | **bpftool** **map** { **show** | **list** } [*MAP*] 29 + | **bpftool** **map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \ 30 + | **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] \ 31 + | [**offload_dev** *NAME*] 32 + | **bpftool** **map dump** *MAP* 33 + | **bpftool** **map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 34 + | **bpftool** **map lookup** *MAP* [**key** *DATA*] 35 + | **bpftool** **map getnext** *MAP* [**key** *DATA*] 36 + | **bpftool** **map delete** *MAP* **key** *DATA* 37 + | **bpftool** **map pin** *MAP* *FILE* 38 + | **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 39 + | **bpftool** **map peek** *MAP* 40 + | **bpftool** **map push** *MAP* **value** *VALUE* 41 + | **bpftool** **map pop** *MAP* 42 + | **bpftool** **map enqueue** *MAP* **value** *VALUE* 43 + | **bpftool** **map dequeue** *MAP* 44 + | **bpftool** **map freeze** *MAP* 45 + | **bpftool** **map help** 46 46 | 47 - | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* | **name** *MAP_NAME* } 48 - | *DATA* := { [**hex**] *BYTES* } 49 - | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* } 50 - | *VALUE* := { *DATA* | *MAP* | *PROG* } 51 - | *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } 52 - | *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** 53 - | | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash** 54 - | | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** 55 - | | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash** 56 - | | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** 57 - | | **queue** | **stack** | **sk_storage** | **struct_ops** | **ringbuf** | **inode_storage** 58 - | | **task_storage** | **bloom_filter** | **user_ringbuf** | **cgrp_storage** | **arena** } 47 + | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* | **name** *MAP_NAME* } 48 + | *DATA* := { [**hex**] *BYTES* } 49 + | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* } 50 + | *VALUE* := { *DATA* | *MAP* | *PROG* } 51 + | *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } 52 + | *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** 53 + | | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash** 54 + | | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** 55 + | | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash** 56 + | | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** 57 + | | **queue** | **stack** | **sk_storage** | **struct_ops** | **ringbuf** | **inode_storage** 58 + | | **task_storage** | **bloom_filter** | **user_ringbuf** | **cgrp_storage** | **arena** } 59 59 60 60 DESCRIPTION 61 61 =========== 62 - **bpftool map { show | list }** [*MAP*] 63 - Show information about loaded maps. If *MAP* is specified 64 - show information only about given maps, otherwise list all 65 - maps currently loaded on the system. In case of **name**, 66 - *MAP* may match several maps which will all be shown. 62 + **bpftool map { show | list }** [*MAP*] 63 + Show information about loaded maps. If *MAP* is specified show information 64 + only about given maps, otherwise list all maps currently loaded on the 65 + system. In case of **name**, *MAP* may match several maps which will all 66 + be shown. 67 67 68 - Output will start with map ID followed by map type and 69 - zero or more named attributes (depending on kernel version). 68 + Output will start with map ID followed by map type and zero or more named 69 + attributes (depending on kernel version). 70 70 71 - Since Linux 5.8 bpftool is able to discover information about 72 - processes that hold open file descriptors (FDs) against BPF 73 - maps. On such kernels bpftool will automatically emit this 74 - information as well. 71 + Since Linux 5.8 bpftool is able to discover information about processes 72 + that hold open file descriptors (FDs) against BPF maps. On such kernels 73 + bpftool will automatically emit this information as well. 75 74 76 - **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*] 77 - Create a new map with given parameters and pin it to *bpffs* 78 - as *FILE*. 75 + **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*] 76 + Create a new map with given parameters and pin it to *bpffs* as *FILE*. 79 77 80 - *FLAGS* should be an integer which is the combination of 81 - desired flags, e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h 82 - UAPI header for existing flags). 78 + *FLAGS* should be an integer which is the combination of desired flags, 79 + e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h UAPI header for existing 80 + flags). 83 81 84 - To create maps of type array-of-maps or hash-of-maps, the 85 - **inner_map** keyword must be used to pass an inner map. The 86 - kernel needs it to collect metadata related to the inner maps 87 - that the new map will work with. 82 + To create maps of type array-of-maps or hash-of-maps, the **inner_map** 83 + keyword must be used to pass an inner map. The kernel needs it to collect 84 + metadata related to the inner maps that the new map will work with. 88 85 89 - Keyword **offload_dev** expects a network interface name, 90 - and is used to request hardware offload for the map. 86 + Keyword **offload_dev** expects a network interface name, and is used to 87 + request hardware offload for the map. 91 88 92 - **bpftool map dump** *MAP* 93 - Dump all entries in a given *MAP*. In case of **name**, 94 - *MAP* may match several maps which will all be dumped. 89 + **bpftool map dump** *MAP* 90 + Dump all entries in a given *MAP*. In case of **name**, *MAP* may match 91 + several maps which will all be dumped. 95 92 96 - **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 97 - Update map entry for a given *KEY*. 93 + **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 94 + Update map entry for a given *KEY*. 98 95 99 - *UPDATE_FLAGS* can be one of: **any** update existing entry 100 - or add if doesn't exit; **exist** update only if entry already 101 - exists; **noexist** update only if entry doesn't exist. 96 + *UPDATE_FLAGS* can be one of: **any** update existing entry or add if 97 + doesn't exit; **exist** update only if entry already exists; **noexist** 98 + update only if entry doesn't exist. 102 99 103 - If the **hex** keyword is provided in front of the bytes 104 - sequence, the bytes are parsed as hexadecimal values, even if 105 - no "0x" prefix is added. If the keyword is not provided, then 106 - the bytes are parsed as decimal values, unless a "0x" prefix 107 - (for hexadecimal) or a "0" prefix (for octal) is provided. 100 + If the **hex** keyword is provided in front of the bytes sequence, the 101 + bytes are parsed as hexadecimal values, even if no "0x" prefix is added. If 102 + the keyword is not provided, then the bytes are parsed as decimal values, 103 + unless a "0x" prefix (for hexadecimal) or a "0" prefix (for octal) is 104 + provided. 108 105 109 - **bpftool map lookup** *MAP* [**key** *DATA*] 110 - Lookup **key** in the map. 106 + **bpftool map lookup** *MAP* [**key** *DATA*] 107 + Lookup **key** in the map. 111 108 112 - **bpftool map getnext** *MAP* [**key** *DATA*] 113 - Get next key. If *key* is not specified, get first key. 109 + **bpftool map getnext** *MAP* [**key** *DATA*] 110 + Get next key. If *key* is not specified, get first key. 114 111 115 - **bpftool map delete** *MAP* **key** *DATA* 116 - Remove entry from the map. 112 + **bpftool map delete** *MAP* **key** *DATA* 113 + Remove entry from the map. 117 114 118 - **bpftool map pin** *MAP* *FILE* 119 - Pin map *MAP* as *FILE*. 115 + **bpftool map pin** *MAP* *FILE* 116 + Pin map *MAP* as *FILE*. 120 117 121 - Note: *FILE* must be located in *bpffs* mount. It must not 122 - contain a dot character ('.'), which is reserved for future 123 - extensions of *bpffs*. 118 + Note: *FILE* must be located in *bpffs* mount. It must not contain a dot 119 + character ('.'), which is reserved for future extensions of *bpffs*. 124 120 125 - **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 126 - Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map. 121 + **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 122 + Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map. 127 123 128 - Install perf rings into a perf event array map and dump 129 - output of any **bpf_perf_event_output**\ () call in the kernel. 130 - By default read the number of CPUs on the system and 131 - install perf ring for each CPU in the corresponding index 132 - in the array. 124 + Install perf rings into a perf event array map and dump output of any 125 + **bpf_perf_event_output**\ () call in the kernel. By default read the 126 + number of CPUs on the system and install perf ring for each CPU in the 127 + corresponding index in the array. 133 128 134 - If **cpu** and **index** are specified, install perf ring 135 - for given **cpu** at **index** in the array (single ring). 129 + If **cpu** and **index** are specified, install perf ring for given **cpu** 130 + at **index** in the array (single ring). 136 131 137 - Note that installing a perf ring into an array will silently 138 - replace any existing ring. Any other application will stop 139 - receiving events if it installed its rings earlier. 132 + Note that installing a perf ring into an array will silently replace any 133 + existing ring. Any other application will stop receiving events if it 134 + installed its rings earlier. 140 135 141 - **bpftool map peek** *MAP* 142 - Peek next value in the queue or stack. 136 + **bpftool map peek** *MAP* 137 + Peek next value in the queue or stack. 143 138 144 - **bpftool map push** *MAP* **value** *VALUE* 145 - Push *VALUE* onto the stack. 139 + **bpftool map push** *MAP* **value** *VALUE* 140 + Push *VALUE* onto the stack. 146 141 147 - **bpftool map pop** *MAP* 148 - Pop and print value from the stack. 142 + **bpftool map pop** *MAP* 143 + Pop and print value from the stack. 149 144 150 - **bpftool map enqueue** *MAP* **value** *VALUE* 151 - Enqueue *VALUE* into the queue. 145 + **bpftool map enqueue** *MAP* **value** *VALUE* 146 + Enqueue *VALUE* into the queue. 152 147 153 - **bpftool map dequeue** *MAP* 154 - Dequeue and print value from the queue. 148 + **bpftool map dequeue** *MAP* 149 + Dequeue and print value from the queue. 155 150 156 - **bpftool map freeze** *MAP* 157 - Freeze the map as read-only from user space. Entries from a 158 - frozen map can not longer be updated or deleted with the 159 - **bpf**\ () system call. This operation is not reversible, 160 - and the map remains immutable from user space until its 161 - destruction. However, read and write permissions for BPF 162 - programs to the map remain unchanged. 151 + **bpftool map freeze** *MAP* 152 + Freeze the map as read-only from user space. Entries from a frozen map can 153 + not longer be updated or deleted with the **bpf**\ () system call. This 154 + operation is not reversible, and the map remains immutable from user space 155 + until its destruction. However, read and write permissions for BPF programs 156 + to the map remain unchanged. 163 157 164 - **bpftool map help** 165 - Print short help message. 158 + **bpftool map help** 159 + Print short help message. 166 160 167 161 OPTIONS 168 162 ======= 169 - .. include:: common_options.rst 163 + .. include:: common_options.rst 170 164 171 - -f, --bpffs 172 - Show file names of pinned maps. 165 + -f, --bpffs 166 + Show file names of pinned maps. 173 167 174 - -n, --nomount 175 - Do not automatically attempt to mount any virtual file system 176 - (such as tracefs or BPF virtual file system) when necessary. 168 + -n, --nomount 169 + Do not automatically attempt to mount any virtual file system (such as 170 + tracefs or BPF virtual file system) when necessary. 177 171 178 172 EXAMPLES 179 173 ========

+48 -50

tools/bpf/bpftool/Documentation/bpftool-net.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **net** *COMMAND* 17 + **bpftool** [*OPTIONS*] **net** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| } 19 + *OPTIONS* := { |COMMON_OPTIONS| } 20 20 21 - *COMMANDS* := 22 - { **show** | **list** | **attach** | **detach** | **help** } 21 + *COMMANDS* := { **show** | **list** | **attach** | **detach** | **help** } 23 22 24 23 NET COMMANDS 25 24 ============ 26 25 27 - | **bpftool** **net** { **show** | **list** } [ **dev** *NAME* ] 28 - | **bpftool** **net attach** *ATTACH_TYPE* *PROG* **dev** *NAME* [ **overwrite** ] 29 - | **bpftool** **net detach** *ATTACH_TYPE* **dev** *NAME* 30 - | **bpftool** **net help** 26 + | **bpftool** **net** { **show** | **list** } [ **dev** *NAME* ] 27 + | **bpftool** **net attach** *ATTACH_TYPE* *PROG* **dev** *NAME* [ **overwrite** ] 28 + | **bpftool** **net detach** *ATTACH_TYPE* **dev** *NAME* 29 + | **bpftool** **net help** 31 30 | 32 - | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 33 - | *ATTACH_TYPE* := { **xdp** | **xdpgeneric** | **xdpdrv** | **xdpoffload** } 31 + | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 32 + | *ATTACH_TYPE* := { **xdp** | **xdpgeneric** | **xdpdrv** | **xdpoffload** } 34 33 35 34 DESCRIPTION 36 35 =========== 37 - **bpftool net { show | list }** [ **dev** *NAME* ] 38 - List bpf program attachments in the kernel networking subsystem. 36 + **bpftool net { show | list }** [ **dev** *NAME* ] 37 + List bpf program attachments in the kernel networking subsystem. 39 38 40 - Currently, device driver xdp attachments, tcx, netkit and old-style tc 41 - classifier/action attachments, flow_dissector as well as netfilter 42 - attachments are implemented, i.e., for 43 - program types **BPF_PROG_TYPE_XDP**, **BPF_PROG_TYPE_SCHED_CLS**, 44 - **BPF_PROG_TYPE_SCHED_ACT**, **BPF_PROG_TYPE_FLOW_DISSECTOR**, 45 - **BPF_PROG_TYPE_NETFILTER**. 39 + Currently, device driver xdp attachments, tcx, netkit and old-style tc 40 + classifier/action attachments, flow_dissector as well as netfilter 41 + attachments are implemented, i.e., for program types **BPF_PROG_TYPE_XDP**, 42 + **BPF_PROG_TYPE_SCHED_CLS**, **BPF_PROG_TYPE_SCHED_ACT**, 43 + **BPF_PROG_TYPE_FLOW_DISSECTOR**, **BPF_PROG_TYPE_NETFILTER**. 46 44 47 - For programs attached to a particular cgroup, e.g., 48 - **BPF_PROG_TYPE_CGROUP_SKB**, **BPF_PROG_TYPE_CGROUP_SOCK**, 49 - **BPF_PROG_TYPE_SOCK_OPS** and **BPF_PROG_TYPE_CGROUP_SOCK_ADDR**, 50 - users can use **bpftool cgroup** to dump cgroup attachments. 51 - For sk_{filter, skb, msg, reuseport} and lwt/seg6 52 - bpf programs, users should consult other tools, e.g., iproute2. 45 + For programs attached to a particular cgroup, e.g., 46 + **BPF_PROG_TYPE_CGROUP_SKB**, **BPF_PROG_TYPE_CGROUP_SOCK**, 47 + **BPF_PROG_TYPE_SOCK_OPS** and **BPF_PROG_TYPE_CGROUP_SOCK_ADDR**, users 48 + can use **bpftool cgroup** to dump cgroup attachments. For sk_{filter, skb, 49 + msg, reuseport} and lwt/seg6 bpf programs, users should consult other 50 + tools, e.g., iproute2. 53 51 54 - The current output will start with all xdp program attachments, followed by 55 - all tcx, netkit, then tc class/qdisc bpf program attachments, then flow_dissector 56 - and finally netfilter programs. Both xdp programs and tcx/netkit/tc programs are 57 - ordered based on ifindex number. If multiple bpf programs attached 58 - to the same networking device through **tc**, the order will be first 59 - all bpf programs attached to tcx, netkit, then tc classes, then all bpf programs 60 - attached to non clsact qdiscs, and finally all bpf programs attached 61 - to root and clsact qdisc. 52 + The current output will start with all xdp program attachments, followed by 53 + all tcx, netkit, then tc class/qdisc bpf program attachments, then 54 + flow_dissector and finally netfilter programs. Both xdp programs and 55 + tcx/netkit/tc programs are ordered based on ifindex number. If multiple bpf 56 + programs attached to the same networking device through **tc**, the order 57 + will be first all bpf programs attached to tcx, netkit, then tc classes, 58 + then all bpf programs attached to non clsact qdiscs, and finally all bpf 59 + programs attached to root and clsact qdisc. 62 60 63 - **bpftool** **net attach** *ATTACH_TYPE* *PROG* **dev** *NAME* [ **overwrite** ] 64 - Attach bpf program *PROG* to network interface *NAME* with 65 - type specified by *ATTACH_TYPE*. Previously attached bpf program 66 - can be replaced by the command used with **overwrite** option. 67 - Currently, only XDP-related modes are supported for *ATTACH_TYPE*. 61 + **bpftool** **net attach** *ATTACH_TYPE* *PROG* **dev** *NAME* [ **overwrite** ] 62 + Attach bpf program *PROG* to network interface *NAME* with type specified 63 + by *ATTACH_TYPE*. Previously attached bpf program can be replaced by the 64 + command used with **overwrite** option. Currently, only XDP-related modes 65 + are supported for *ATTACH_TYPE*. 68 66 69 - *ATTACH_TYPE* can be of: 70 - **xdp** - try native XDP and fallback to generic XDP if NIC driver does not support it; 71 - **xdpgeneric** - Generic XDP. runs at generic XDP hook when packet already enters receive path as skb; 72 - **xdpdrv** - Native XDP. runs earliest point in driver's receive path; 73 - **xdpoffload** - Offload XDP. runs directly on NIC on each packet reception; 67 + *ATTACH_TYPE* can be of: 68 + **xdp** - try native XDP and fallback to generic XDP if NIC driver does not support it; 69 + **xdpgeneric** - Generic XDP. runs at generic XDP hook when packet already enters receive path as skb; 70 + **xdpdrv** - Native XDP. runs earliest point in driver's receive path; 71 + **xdpoffload** - Offload XDP. runs directly on NIC on each packet reception; 74 72 75 - **bpftool** **net detach** *ATTACH_TYPE* **dev** *NAME* 76 - Detach bpf program attached to network interface *NAME* with 77 - type specified by *ATTACH_TYPE*. To detach bpf program, same 78 - *ATTACH_TYPE* previously used for attach must be specified. 79 - Currently, only XDP-related modes are supported for *ATTACH_TYPE*. 73 + **bpftool** **net detach** *ATTACH_TYPE* **dev** *NAME* 74 + Detach bpf program attached to network interface *NAME* with type specified 75 + by *ATTACH_TYPE*. To detach bpf program, same *ATTACH_TYPE* previously used 76 + for attach must be specified. Currently, only XDP-related modes are 77 + supported for *ATTACH_TYPE*. 80 78 81 - **bpftool net help** 82 - Print short help message. 79 + **bpftool net help** 80 + Print short help message. 83 81 84 82 OPTIONS 85 83 ======= 86 - .. include:: common_options.rst 84 + .. include:: common_options.rst 87 85 88 86 EXAMPLES 89 87 ========

+17 -17

tools/bpf/bpftool/Documentation/bpftool-perf.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **perf** *COMMAND* 17 + **bpftool** [*OPTIONS*] **perf** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| } 19 + *OPTIONS* := { |COMMON_OPTIONS| } 20 20 21 - *COMMANDS* := 22 - { **show** | **list** | **help** } 21 + *COMMANDS* := 22 + { **show** | **list** | **help** } 23 23 24 24 PERF COMMANDS 25 25 ============= 26 26 27 - | **bpftool** **perf** { **show** | **list** } 28 - | **bpftool** **perf help** 27 + | **bpftool** **perf** { **show** | **list** } 28 + | **bpftool** **perf help** 29 29 30 30 DESCRIPTION 31 31 =========== 32 - **bpftool perf { show | list }** 33 - List all raw_tracepoint, tracepoint, kprobe attachment in the system. 32 + **bpftool perf { show | list }** 33 + List all raw_tracepoint, tracepoint, kprobe attachment in the system. 34 34 35 - Output will start with process id and file descriptor in that process, 36 - followed by bpf program id, attachment information, and attachment point. 37 - The attachment point for raw_tracepoint/tracepoint is the trace probe name. 38 - The attachment point for k[ret]probe is either symbol name and offset, 39 - or a kernel virtual address. 40 - The attachment point for u[ret]probe is the file name and the file offset. 35 + Output will start with process id and file descriptor in that process, 36 + followed by bpf program id, attachment information, and attachment point. 37 + The attachment point for raw_tracepoint/tracepoint is the trace probe name. 38 + The attachment point for k[ret]probe is either symbol name and offset, or a 39 + kernel virtual address. The attachment point for u[ret]probe is the file 40 + name and the file offset. 41 41 42 - **bpftool perf help** 43 - Print short help message. 42 + **bpftool perf help** 43 + Print short help message. 44 44 45 45 OPTIONS 46 46 ======= 47 - .. include:: common_options.rst 47 + .. include:: common_options.rst 48 48 49 49 EXAMPLES 50 50 ========

+175 -199

tools/bpf/bpftool/Documentation/bpftool-prog.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **prog** *COMMAND* 17 + **bpftool** [*OPTIONS*] **prog** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| | 20 - { **-f** | **--bpffs** } | { **-m** | **--mapcompat** } | { **-n** | **--nomount** } | 21 - { **-L** | **--use-loader** } } 19 + *OPTIONS* := { |COMMON_OPTIONS| | 20 + { **-f** | **--bpffs** } | { **-m** | **--mapcompat** } | { **-n** | **--nomount** } | 21 + { **-L** | **--use-loader** } } 22 22 23 - *COMMANDS* := 24 - { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load** | 25 - **loadall** | **help** } 23 + *COMMANDS* := 24 + { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load** | 25 + **loadall** | **help** } 26 26 27 27 PROG COMMANDS 28 28 ============= 29 29 30 - | **bpftool** **prog** { **show** | **list** } [*PROG*] 31 - | **bpftool** **prog dump xlated** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] [**visual**] }] 32 - | **bpftool** **prog dump jited** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] }] 33 - | **bpftool** **prog pin** *PROG* *FILE* 34 - | **bpftool** **prog** { **load** | **loadall** } *OBJ* *PATH* [**type** *TYPE*] [**map** { **idx** *IDX* | **name** *NAME* } *MAP*] [{ **offload_dev** | **xdpmeta_dev** } *NAME*] [**pinmaps** *MAP_DIR*] [**autoattach**] 35 - | **bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*] 36 - | **bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*] 37 - | **bpftool** **prog tracelog** 38 - | **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*] 39 - | **bpftool** **prog profile** *PROG* [**duration** *DURATION*] *METRICs* 40 - | **bpftool** **prog help** 30 + | **bpftool** **prog** { **show** | **list** } [*PROG*] 31 + | **bpftool** **prog dump xlated** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] [**visual**] }] 32 + | **bpftool** **prog dump jited** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] }] 33 + | **bpftool** **prog pin** *PROG* *FILE* 34 + | **bpftool** **prog** { **load** | **loadall** } *OBJ* *PATH* [**type** *TYPE*] [**map** { **idx** *IDX* | **name** *NAME* } *MAP*] [{ **offload_dev** | **xdpmeta_dev** } *NAME*] [**pinmaps** *MAP_DIR*] [**autoattach**] 35 + | **bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*] 36 + | **bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*] 37 + | **bpftool** **prog tracelog** 38 + | **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*] 39 + | **bpftool** **prog profile** *PROG* [**duration** *DURATION*] *METRICs* 40 + | **bpftool** **prog help** 41 41 | 42 - | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 43 - | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* } 44 - | *TYPE* := { 45 - | **socket** | **kprobe** | **kretprobe** | **classifier** | **action** | 46 - | **tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** | 47 - | **cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** | 48 - | **lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** | 49 - | **cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** | 50 - | **cgroup/connect4** | **cgroup/connect6** | **cgroup/connect_unix** | 51 - | **cgroup/getpeername4** | **cgroup/getpeername6** | **cgroup/getpeername_unix** | 52 - | **cgroup/getsockname4** | **cgroup/getsockname6** | **cgroup/getsockname_unix** | 53 - | **cgroup/sendmsg4** | **cgroup/sendmsg6** | **cgroup/sendmsg_unix** | 54 - | **cgroup/recvmsg4** | **cgroup/recvmsg6** | **cgroup/recvmsg_unix** | **cgroup/sysctl** | 55 - | **cgroup/getsockopt** | **cgroup/setsockopt** | **cgroup/sock_release** | 56 - | **struct_ops** | **fentry** | **fexit** | **freplace** | **sk_lookup** 57 - | } 58 - | *ATTACH_TYPE* := { 59 - | **sk_msg_verdict** | **sk_skb_verdict** | **sk_skb_stream_verdict** | 60 - | **sk_skb_stream_parser** | **flow_dissector** 61 - | } 62 - | *METRICs* := { 63 - | **cycles** | **instructions** | **l1d_loads** | **llc_misses** | 64 - | **itlb_misses** | **dtlb_misses** 65 - | } 42 + | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 43 + | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* } 44 + | *TYPE* := { 45 + | **socket** | **kprobe** | **kretprobe** | **classifier** | **action** | 46 + | **tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** | 47 + | **cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** | 48 + | **lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** | 49 + | **cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** | 50 + | **cgroup/connect4** | **cgroup/connect6** | **cgroup/connect_unix** | 51 + | **cgroup/getpeername4** | **cgroup/getpeername6** | **cgroup/getpeername_unix** | 52 + | **cgroup/getsockname4** | **cgroup/getsockname6** | **cgroup/getsockname_unix** | 53 + | **cgroup/sendmsg4** | **cgroup/sendmsg6** | **cgroup/sendmsg_unix** | 54 + | **cgroup/recvmsg4** | **cgroup/recvmsg6** | **cgroup/recvmsg_unix** | **cgroup/sysctl** | 55 + | **cgroup/getsockopt** | **cgroup/setsockopt** | **cgroup/sock_release** | 56 + | **struct_ops** | **fentry** | **fexit** | **freplace** | **sk_lookup** 57 + | } 58 + | *ATTACH_TYPE* := { 59 + | **sk_msg_verdict** | **sk_skb_verdict** | **sk_skb_stream_verdict** | 60 + | **sk_skb_stream_parser** | **flow_dissector** 61 + | } 62 + | *METRICs* := { 63 + | **cycles** | **instructions** | **l1d_loads** | **llc_misses** | 64 + | **itlb_misses** | **dtlb_misses** 65 + | } 66 66 67 67 68 68 DESCRIPTION 69 69 =========== 70 - **bpftool prog { show | list }** [*PROG*] 71 - Show information about loaded programs. If *PROG* is 72 - specified show information only about given programs, 73 - otherwise list all programs currently loaded on the system. 74 - In case of **tag** or **name**, *PROG* may match several 75 - programs which will all be shown. 70 + **bpftool prog { show | list }** [*PROG*] 71 + Show information about loaded programs. If *PROG* is specified show 72 + information only about given programs, otherwise list all programs 73 + currently loaded on the system. In case of **tag** or **name**, *PROG* may 74 + match several programs which will all be shown. 76 75 77 - Output will start with program ID followed by program type and 78 - zero or more named attributes (depending on kernel version). 76 + Output will start with program ID followed by program type and zero or more 77 + named attributes (depending on kernel version). 79 78 80 - Since Linux 5.1 the kernel can collect statistics on BPF 81 - programs (such as the total time spent running the program, 82 - and the number of times it was run). If available, bpftool 83 - shows such statistics. However, the kernel does not collect 84 - them by defaults, as it slightly impacts performance on each 85 - program run. Activation or deactivation of the feature is 86 - performed via the **kernel.bpf_stats_enabled** sysctl knob. 79 + Since Linux 5.1 the kernel can collect statistics on BPF programs (such as 80 + the total time spent running the program, and the number of times it was 81 + run). If available, bpftool shows such statistics. However, the kernel does 82 + not collect them by defaults, as it slightly impacts performance on each 83 + program run. Activation or deactivation of the feature is performed via the 84 + **kernel.bpf_stats_enabled** sysctl knob. 87 85 88 - Since Linux 5.8 bpftool is able to discover information about 89 - processes that hold open file descriptors (FDs) against BPF 90 - programs. On such kernels bpftool will automatically emit this 91 - information as well. 86 + Since Linux 5.8 bpftool is able to discover information about processes 87 + that hold open file descriptors (FDs) against BPF programs. On such kernels 88 + bpftool will automatically emit this information as well. 92 89 93 - **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] [**visual**] }] 94 - Dump eBPF instructions of the programs from the kernel. By 95 - default, eBPF will be disassembled and printed to standard 96 - output in human-readable format. In this case, **opcodes** 97 - controls if raw opcodes should be printed as well. 90 + **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] [**visual**] }] 91 + Dump eBPF instructions of the programs from the kernel. By default, eBPF 92 + will be disassembled and printed to standard output in human-readable 93 + format. In this case, **opcodes** controls if raw opcodes should be printed 94 + as well. 98 95 99 - In case of **tag** or **name**, *PROG* may match several 100 - programs which will all be dumped. However, if **file** or 101 - **visual** is specified, *PROG* must match a single program. 96 + In case of **tag** or **name**, *PROG* may match several programs which 97 + will all be dumped. However, if **file** or **visual** is specified, 98 + *PROG* must match a single program. 102 99 103 - If **file** is specified, the binary image will instead be 104 - written to *FILE*. 100 + If **file** is specified, the binary image will instead be written to 101 + *FILE*. 105 102 106 - If **visual** is specified, control flow graph (CFG) will be 107 - built instead, and eBPF instructions will be presented with 108 - CFG in DOT format, on standard output. 103 + If **visual** is specified, control flow graph (CFG) will be built instead, 104 + and eBPF instructions will be presented with CFG in DOT format, on standard 105 + output. 109 106 110 - If the programs have line_info available, the source line will 111 - be displayed. If **linum** is specified, the filename, line 112 - number and line column will also be displayed. 107 + If the programs have line_info available, the source line will be 108 + displayed. If **linum** is specified, the filename, line number and line 109 + column will also be displayed. 113 110 114 - **bpftool prog dump jited** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] }] 115 - Dump jited image (host machine code) of the program. 111 + **bpftool prog dump jited** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] }] 112 + Dump jited image (host machine code) of the program. 116 113 117 - If *FILE* is specified image will be written to a file, 118 - otherwise it will be disassembled and printed to stdout. 119 - *PROG* must match a single program when **file** is specified. 114 + If *FILE* is specified image will be written to a file, otherwise it will 115 + be disassembled and printed to stdout. *PROG* must match a single program 116 + when **file** is specified. 120 117 121 - **opcodes** controls if raw opcodes will be printed. 118 + **opcodes** controls if raw opcodes will be printed. 122 119 123 - If the prog has line_info available, the source line will 124 - be displayed. If **linum** is specified, the filename, line 125 - number and line column will also be displayed. 120 + If the prog has line_info available, the source line will be displayed. If 121 + **linum** is specified, the filename, line number and line column will also 122 + be displayed. 126 123 127 - **bpftool prog pin** *PROG* *FILE* 128 - Pin program *PROG* as *FILE*. 124 + **bpftool prog pin** *PROG* *FILE* 125 + Pin program *PROG* as *FILE*. 129 126 130 - Note: *FILE* must be located in *bpffs* mount. It must not 131 - contain a dot character ('.'), which is reserved for future 132 - extensions of *bpffs*. 127 + Note: *FILE* must be located in *bpffs* mount. It must not contain a dot 128 + character ('.'), which is reserved for future extensions of *bpffs*. 133 129 134 - **bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** { **idx** *IDX* | **name** *NAME* } *MAP*] [{ **offload_dev** | **xdpmeta_dev** } *NAME*] [**pinmaps** *MAP_DIR*] [**autoattach**] 135 - Load bpf program(s) from binary *OBJ* and pin as *PATH*. 136 - **bpftool prog load** pins only the first program from the 137 - *OBJ* as *PATH*. **bpftool prog loadall** pins all programs 138 - from the *OBJ* under *PATH* directory. 139 - **type** is optional, if not specified program type will be 140 - inferred from section names. 141 - By default bpftool will create new maps as declared in the ELF 142 - object being loaded. **map** parameter allows for the reuse 143 - of existing maps. It can be specified multiple times, each 144 - time for a different map. *IDX* refers to index of the map 145 - to be replaced in the ELF file counting from 0, while *NAME* 146 - allows to replace a map by name. *MAP* specifies the map to 147 - use, referring to it by **id** or through a **pinned** file. 148 - If **offload_dev** *NAME* is specified program will be loaded 149 - onto given networking device (offload). 150 - If **xdpmeta_dev** *NAME* is specified program will become 151 - device-bound without offloading, this facilitates access 152 - to XDP metadata. 153 - Optional **pinmaps** argument can be provided to pin all 154 - maps under *MAP_DIR* directory. 130 + **bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** { **idx** *IDX* | **name** *NAME* } *MAP*] [{ **offload_dev** | **xdpmeta_dev** } *NAME*] [**pinmaps** *MAP_DIR*] [**autoattach**] 131 + Load bpf program(s) from binary *OBJ* and pin as *PATH*. **bpftool prog 132 + load** pins only the first program from the *OBJ* as *PATH*. **bpftool prog 133 + loadall** pins all programs from the *OBJ* under *PATH* directory. **type** 134 + is optional, if not specified program type will be inferred from section 135 + names. By default bpftool will create new maps as declared in the ELF 136 + object being loaded. **map** parameter allows for the reuse of existing 137 + maps. It can be specified multiple times, each time for a different map. 138 + *IDX* refers to index of the map to be replaced in the ELF file counting 139 + from 0, while *NAME* allows to replace a map by name. *MAP* specifies the 140 + map to use, referring to it by **id** or through a **pinned** file. If 141 + **offload_dev** *NAME* is specified program will be loaded onto given 142 + networking device (offload). If **xdpmeta_dev** *NAME* is specified program 143 + will become device-bound without offloading, this facilitates access to XDP 144 + metadata. Optional **pinmaps** argument can be provided to pin all maps 145 + under *MAP_DIR* directory. 155 146 156 - If **autoattach** is specified program will be attached 157 - before pin. In that case, only the link (representing the 158 - program attached to its hook) is pinned, not the program as 159 - such, so the path won't show in **bpftool prog show -f**, 160 - only show in **bpftool link show -f**. Also, this only works 161 - when bpftool (libbpf) is able to infer all necessary 162 - information from the object file, in particular, it's not 163 - supported for all program types. If a program does not 164 - support autoattach, bpftool falls back to regular pinning 165 - for that program instead. 147 + If **autoattach** is specified program will be attached before pin. In that 148 + case, only the link (representing the program attached to its hook) is 149 + pinned, not the program as such, so the path won't show in **bpftool prog 150 + show -f**, only show in **bpftool link show -f**. Also, this only works 151 + when bpftool (libbpf) is able to infer all necessary information from the 152 + object file, in particular, it's not supported for all program types. If a 153 + program does not support autoattach, bpftool falls back to regular pinning 154 + for that program instead. 166 155 167 - Note: *PATH* must be located in *bpffs* mount. It must not 168 - contain a dot character ('.'), which is reserved for future 169 - extensions of *bpffs*. 156 + Note: *PATH* must be located in *bpffs* mount. It must not contain a dot 157 + character ('.'), which is reserved for future extensions of *bpffs*. 170 158 171 - **bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*] 172 - Attach bpf program *PROG* (with type specified by 173 - *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP* 174 - parameter, with the exception of *flow_dissector* which is 175 - attached to current networking name space. 159 + **bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*] 160 + Attach bpf program *PROG* (with type specified by *ATTACH_TYPE*). Most 161 + *ATTACH_TYPEs* require a *MAP* parameter, with the exception of 162 + *flow_dissector* which is attached to current networking name space. 176 163 177 - **bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*] 178 - Detach bpf program *PROG* (with type specified by 179 - *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP* 180 - parameter, with the exception of *flow_dissector* which is 181 - detached from the current networking name space. 164 + **bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*] 165 + Detach bpf program *PROG* (with type specified by *ATTACH_TYPE*). Most 166 + *ATTACH_TYPEs* require a *MAP* parameter, with the exception of 167 + *flow_dissector* which is detached from the current networking name space. 182 168 183 - **bpftool prog tracelog** 184 - Dump the trace pipe of the system to the console (stdout). 185 - Hit <Ctrl+C> to stop printing. BPF programs can write to this 186 - trace pipe at runtime with the **bpf_trace_printk**\ () helper. 187 - This should be used only for debugging purposes. For 188 - streaming data from BPF programs to user space, one can use 189 - perf events (see also **bpftool-map**\ (8)). 169 + **bpftool prog tracelog** 170 + Dump the trace pipe of the system to the console (stdout). Hit <Ctrl+C> to 171 + stop printing. BPF programs can write to this trace pipe at runtime with 172 + the **bpf_trace_printk**\ () helper. This should be used only for debugging 173 + purposes. For streaming data from BPF programs to user space, one can use 174 + perf events (see also **bpftool-map**\ (8)). 190 175 191 - **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*] 192 - Run BPF program *PROG* in the kernel testing infrastructure 193 - for BPF, meaning that the program works on the data and 194 - context provided by the user, and not on actual packets or 195 - monitored functions etc. Return value and duration for the 196 - test run are printed out to the console. 176 + **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*] 177 + Run BPF program *PROG* in the kernel testing infrastructure for BPF, 178 + meaning that the program works on the data and context provided by the 179 + user, and not on actual packets or monitored functions etc. Return value 180 + and duration for the test run are printed out to the console. 197 181 198 - Input data is read from the *FILE* passed with **data_in**. 199 - If this *FILE* is "**-**", input data is read from standard 200 - input. Input context, if any, is read from *FILE* passed with 201 - **ctx_in**. Again, "**-**" can be used to read from standard 202 - input, but only if standard input is not already in use for 203 - input data. If a *FILE* is passed with **data_out**, output 204 - data is written to that file. Similarly, output context is 205 - written to the *FILE* passed with **ctx_out**. For both 206 - output flows, "**-**" can be used to print to the standard 207 - output (as plain text, or JSON if relevant option was 208 - passed). If output keywords are omitted, output data and 209 - context are discarded. Keywords **data_size_out** and 210 - **ctx_size_out** are used to pass the size (in bytes) for the 211 - output buffers to the kernel, although the default of 32 kB 212 - should be more than enough for most cases. 182 + Input data is read from the *FILE* passed with **data_in**. If this *FILE* 183 + is "**-**", input data is read from standard input. Input context, if any, 184 + is read from *FILE* passed with **ctx_in**. Again, "**-**" can be used to 185 + read from standard input, but only if standard input is not already in use 186 + for input data. If a *FILE* is passed with **data_out**, output data is 187 + written to that file. Similarly, output context is written to the *FILE* 188 + passed with **ctx_out**. For both output flows, "**-**" can be used to 189 + print to the standard output (as plain text, or JSON if relevant option was 190 + passed). If output keywords are omitted, output data and context are 191 + discarded. Keywords **data_size_out** and **ctx_size_out** are used to pass 192 + the size (in bytes) for the output buffers to the kernel, although the 193 + default of 32 kB should be more than enough for most cases. 213 194 214 - Keyword **repeat** is used to indicate the number of 215 - consecutive runs to perform. Note that output data and 216 - context printed to files correspond to the last of those 217 - runs. The duration printed out at the end of the runs is an 218 - average over all runs performed by the command. 195 + Keyword **repeat** is used to indicate the number of consecutive runs to 196 + perform. Note that output data and context printed to files correspond to 197 + the last of those runs. The duration printed out at the end of the runs is 198 + an average over all runs performed by the command. 219 199 220 - Not all program types support test run. Among those which do, 221 - not all of them can take the **ctx_in**/**ctx_out** 222 - arguments. bpftool does not perform checks on program types. 200 + Not all program types support test run. Among those which do, not all of 201 + them can take the **ctx_in**/**ctx_out** arguments. bpftool does not 202 + perform checks on program types. 223 203 224 - **bpftool prog profile** *PROG* [**duration** *DURATION*] *METRICs* 225 - Profile *METRICs* for bpf program *PROG* for *DURATION* 226 - seconds or until user hits <Ctrl+C>. *DURATION* is optional. 227 - If *DURATION* is not specified, the profiling will run up to 228 - **UINT_MAX** seconds. 204 + **bpftool prog profile** *PROG* [**duration** *DURATION*] *METRICs* 205 + Profile *METRICs* for bpf program *PROG* for *DURATION* seconds or until 206 + user hits <Ctrl+C>. *DURATION* is optional. If *DURATION* is not specified, 207 + the profiling will run up to **UINT_MAX** seconds. 229 208 230 - **bpftool prog help** 231 - Print short help message. 209 + **bpftool prog help** 210 + Print short help message. 232 211 233 212 OPTIONS 234 213 ======= 235 - .. include:: common_options.rst 214 + .. include:: common_options.rst 236 215 237 - -f, --bpffs 238 - When showing BPF programs, show file names of pinned 239 - programs. 216 + -f, --bpffs 217 + When showing BPF programs, show file names of pinned programs. 240 218 241 - -m, --mapcompat 242 - Allow loading maps with unknown map definitions. 219 + -m, --mapcompat 220 + Allow loading maps with unknown map definitions. 243 221 244 - -n, --nomount 245 - Do not automatically attempt to mount any virtual file system 246 - (such as tracefs or BPF virtual file system) when necessary. 222 + -n, --nomount 223 + Do not automatically attempt to mount any virtual file system (such as 224 + tracefs or BPF virtual file system) when necessary. 247 225 248 - -L, --use-loader 249 - Load program as a "loader" program. This is useful to debug 250 - the generation of such programs. When this option is in 251 - use, bpftool attempts to load the programs from the object 252 - file into the kernel, but does not pin them (therefore, the 253 - *PATH* must not be provided). 226 + -L, --use-loader 227 + Load program as a "loader" program. This is useful to debug the generation 228 + of such programs. When this option is in use, bpftool attempts to load the 229 + programs from the object file into the kernel, but does not pin them 230 + (therefore, the *PATH* must not be provided). 254 231 255 - When combined with the **-d**\ \|\ **--debug** option, 256 - additional debug messages are generated, and the execution 257 - of the loader program will use the **bpf_trace_printk**\ () 258 - helper to log each step of loading BTF, creating the maps, 259 - and loading the programs (see **bpftool prog tracelog** as 260 - a way to dump those messages). 232 + When combined with the **-d**\ \|\ **--debug** option, additional debug 233 + messages are generated, and the execution of the loader program will use 234 + the **bpf_trace_printk**\ () helper to log each step of loading BTF, 235 + creating the maps, and loading the programs (see **bpftool prog tracelog** 236 + as a way to dump those messages). 261 237 262 238 EXAMPLES 263 239 ========

+35 -36

tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] **struct_ops** *COMMAND* 17 + **bpftool** [*OPTIONS*] **struct_ops** *COMMAND* 18 18 19 - *OPTIONS* := { |COMMON_OPTIONS| } 19 + *OPTIONS* := { |COMMON_OPTIONS| } 20 20 21 - *COMMANDS* := 22 - { **show** | **list** | **dump** | **register** | **unregister** | **help** } 21 + *COMMANDS* := 22 + { **show** | **list** | **dump** | **register** | **unregister** | **help** } 23 23 24 24 STRUCT_OPS COMMANDS 25 25 =================== 26 26 27 - | **bpftool** **struct_ops { show | list }** [*STRUCT_OPS_MAP*] 28 - | **bpftool** **struct_ops dump** [*STRUCT_OPS_MAP*] 29 - | **bpftool** **struct_ops register** *OBJ* [*LINK_DIR*] 30 - | **bpftool** **struct_ops unregister** *STRUCT_OPS_MAP* 31 - | **bpftool** **struct_ops help** 27 + | **bpftool** **struct_ops { show | list }** [*STRUCT_OPS_MAP*] 28 + | **bpftool** **struct_ops dump** [*STRUCT_OPS_MAP*] 29 + | **bpftool** **struct_ops register** *OBJ* [*LINK_DIR*] 30 + | **bpftool** **struct_ops unregister** *STRUCT_OPS_MAP* 31 + | **bpftool** **struct_ops help** 32 32 | 33 - | *STRUCT_OPS_MAP* := { **id** *STRUCT_OPS_MAP_ID* | **name** *STRUCT_OPS_MAP_NAME* } 34 - | *OBJ* := /a/file/of/bpf_struct_ops.o 33 + | *STRUCT_OPS_MAP* := { **id** *STRUCT_OPS_MAP_ID* | **name** *STRUCT_OPS_MAP_NAME* } 34 + | *OBJ* := /a/file/of/bpf_struct_ops.o 35 35 36 36 37 37 DESCRIPTION 38 38 =========== 39 - **bpftool struct_ops { show | list }** [*STRUCT_OPS_MAP*] 40 - Show brief information about the struct_ops in the system. 41 - If *STRUCT_OPS_MAP* is specified, it shows information only 42 - for the given struct_ops. Otherwise, it lists all struct_ops 43 - currently existing in the system. 39 + **bpftool struct_ops { show | list }** [*STRUCT_OPS_MAP*] 40 + Show brief information about the struct_ops in the system. If 41 + *STRUCT_OPS_MAP* is specified, it shows information only for the given 42 + struct_ops. Otherwise, it lists all struct_ops currently existing in the 43 + system. 44 44 45 - Output will start with struct_ops map ID, followed by its map 46 - name and its struct_ops's kernel type. 45 + Output will start with struct_ops map ID, followed by its map name and its 46 + struct_ops's kernel type. 47 47 48 - **bpftool struct_ops dump** [*STRUCT_OPS_MAP*] 49 - Dump details information about the struct_ops in the system. 50 - If *STRUCT_OPS_MAP* is specified, it dumps information only 51 - for the given struct_ops. Otherwise, it dumps all struct_ops 52 - currently existing in the system. 48 + **bpftool struct_ops dump** [*STRUCT_OPS_MAP*] 49 + Dump details information about the struct_ops in the system. If 50 + *STRUCT_OPS_MAP* is specified, it dumps information only for the given 51 + struct_ops. Otherwise, it dumps all struct_ops currently existing in the 52 + system. 53 53 54 - **bpftool struct_ops register** *OBJ* [*LINK_DIR*] 55 - Register bpf struct_ops from *OBJ*. All struct_ops under 56 - the ELF section ".struct_ops" and ".struct_ops.link" will 57 - be registered to its kernel subsystem. For each 58 - struct_ops in the ".struct_ops.link" section, a link 59 - will be created. You can give *LINK_DIR* to provide a 60 - directory path where these links will be pinned with the 61 - same name as their corresponding map name. 54 + **bpftool struct_ops register** *OBJ* [*LINK_DIR*] 55 + Register bpf struct_ops from *OBJ*. All struct_ops under the ELF section 56 + ".struct_ops" and ".struct_ops.link" will be registered to its kernel 57 + subsystem. For each struct_ops in the ".struct_ops.link" section, a link 58 + will be created. You can give *LINK_DIR* to provide a directory path where 59 + these links will be pinned with the same name as their corresponding map 60 + name. 62 61 63 - **bpftool struct_ops unregister** *STRUCT_OPS_MAP* 64 - Unregister the *STRUCT_OPS_MAP* from the kernel subsystem. 62 + **bpftool struct_ops unregister** *STRUCT_OPS_MAP* 63 + Unregister the *STRUCT_OPS_MAP* from the kernel subsystem. 65 64 66 - **bpftool struct_ops help** 67 - Print short help message. 65 + **bpftool struct_ops help** 66 + Print short help message. 68 67 69 68 OPTIONS 70 69 ======= 71 - .. include:: common_options.rst 70 + .. include:: common_options.rst 72 71 73 72 EXAMPLES 74 73 ========

+30 -30

tools/bpf/bpftool/Documentation/bpftool.rst

··· 14 14 SYNOPSIS 15 15 ======== 16 16 17 - **bpftool** [*OPTIONS*] *OBJECT* { *COMMAND* | **help** } 17 + **bpftool** [*OPTIONS*] *OBJECT* { *COMMAND* | **help** } 18 18 19 - **bpftool** **batch file** *FILE* 19 + **bpftool** **batch file** *FILE* 20 20 21 - **bpftool** **version** 21 + **bpftool** **version** 22 22 23 - *OBJECT* := { **map** | **prog** | **link** | **cgroup** | **perf** | **net** | **feature** | 24 - **btf** | **gen** | **struct_ops** | **iter** } 23 + *OBJECT* := { **map** | **prog** | **link** | **cgroup** | **perf** | **net** | **feature** | 24 + **btf** | **gen** | **struct_ops** | **iter** } 25 25 26 - *OPTIONS* := { { **-V** | **--version** } | |COMMON_OPTIONS| } 26 + *OPTIONS* := { { **-V** | **--version** } | |COMMON_OPTIONS| } 27 27 28 - *MAP-COMMANDS* := 29 - { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** | 30 - **delete** | **pin** | **event_pipe** | **help** } 28 + *MAP-COMMANDS* := 29 + { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** | 30 + **delete** | **pin** | **event_pipe** | **help** } 31 31 32 - *PROG-COMMANDS* := { **show** | **list** | **dump jited** | **dump xlated** | **pin** | 33 - **load** | **attach** | **detach** | **help** } 32 + *PROG-COMMANDS* := { **show** | **list** | **dump jited** | **dump xlated** | **pin** | 33 + **load** | **attach** | **detach** | **help** } 34 34 35 - *LINK-COMMANDS* := { **show** | **list** | **pin** | **detach** | **help** } 35 + *LINK-COMMANDS* := { **show** | **list** | **pin** | **detach** | **help** } 36 36 37 - *CGROUP-COMMANDS* := { **show** | **list** | **attach** | **detach** | **help** } 37 + *CGROUP-COMMANDS* := { **show** | **list** | **attach** | **detach** | **help** } 38 38 39 - *PERF-COMMANDS* := { **show** | **list** | **help** } 39 + *PERF-COMMANDS* := { **show** | **list** | **help** } 40 40 41 - *NET-COMMANDS* := { **show** | **list** | **help** } 41 + *NET-COMMANDS* := { **show** | **list** | **help** } 42 42 43 - *FEATURE-COMMANDS* := { **probe** | **help** } 43 + *FEATURE-COMMANDS* := { **probe** | **help** } 44 44 45 - *BTF-COMMANDS* := { **show** | **list** | **dump** | **help** } 45 + *BTF-COMMANDS* := { **show** | **list** | **dump** | **help** } 46 46 47 - *GEN-COMMANDS* := { **object** | **skeleton** | **min_core_btf** | **help** } 47 + *GEN-COMMANDS* := { **object** | **skeleton** | **min_core_btf** | **help** } 48 48 49 - *STRUCT-OPS-COMMANDS* := { **show** | **list** | **dump** | **register** | **unregister** | **help** } 49 + *STRUCT-OPS-COMMANDS* := { **show** | **list** | **dump** | **register** | **unregister** | **help** } 50 50 51 - *ITER-COMMANDS* := { **pin** | **help** } 51 + *ITER-COMMANDS* := { **pin** | **help** } 52 52 53 53 DESCRIPTION 54 54 =========== 55 - *bpftool* allows for inspection and simple modification of BPF objects 56 - on the system. 55 + *bpftool* allows for inspection and simple modification of BPF objects on the 56 + system. 57 57 58 - Note that format of the output of all tools is not guaranteed to be 59 - stable and should not be depended upon. 58 + Note that format of the output of all tools is not guaranteed to be stable and 59 + should not be depended upon. 60 60 61 61 OPTIONS 62 62 ======= 63 - .. include:: common_options.rst 63 + .. include:: common_options.rst 64 64 65 - -m, --mapcompat 66 - Allow loading maps with unknown map definitions. 65 + -m, --mapcompat 66 + Allow loading maps with unknown map definitions. 67 67 68 - -n, --nomount 69 - Do not automatically attempt to mount any virtual file system 70 - (such as tracefs or BPF virtual file system) when necessary. 68 + -n, --nomount 69 + Do not automatically attempt to mount any virtual file system (such as 70 + tracefs or BPF virtual file system) when necessary.

+12 -14

tools/bpf/bpftool/Documentation/common_options.rst

··· 1 1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 2 2 3 3 -h, --help 4 - Print short help message (similar to **bpftool help**). 4 + Print short help message (similar to **bpftool help**). 5 5 6 6 -V, --version 7 - Print bpftool's version number (similar to **bpftool version**), the 8 - number of the libbpf version in use, and optional features that were 9 - included when bpftool was compiled. Optional features include linking 10 - against LLVM or libbfd to provide the disassembler for JIT-ted 11 - programs (**bpftool prog dump jited**) and usage of BPF skeletons 12 - (some features like **bpftool prog profile** or showing pids 13 - associated to BPF objects may rely on it). 7 + Print bpftool's version number (similar to **bpftool version**), the number 8 + of the libbpf version in use, and optional features that were included when 9 + bpftool was compiled. Optional features include linking against LLVM or 10 + libbfd to provide the disassembler for JIT-ted programs (**bpftool prog 11 + dump jited**) and usage of BPF skeletons (some features like **bpftool prog 12 + profile** or showing pids associated to BPF objects may rely on it). 14 13 15 14 -j, --json 16 - Generate JSON output. For commands that cannot produce JSON, this 17 - option has no effect. 15 + Generate JSON output. For commands that cannot produce JSON, this option 16 + has no effect. 18 17 19 18 -p, --pretty 20 - Generate human-readable JSON output. Implies **-j**. 19 + Generate human-readable JSON output. Implies **-j**. 21 20 22 21 -d, --debug 23 - Print all logs available, even debug-level information. This includes 24 - logs from libbpf as well as from the verifier, when attempting to 25 - load programs. 22 + Print all logs available, even debug-level information. This includes logs 23 + from libbpf as well as from the verifier, when attempting to load programs.