tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
fork atom

bpftool: Remove useless emphasis on command description in man pages

As it turns out, the terms in definition lists in the rST file are
already rendered with bold-ish formatting when generating the man pages;
all double-star sequences we have in the commands for the command
description are unnecessary, and can be removed to make the
documentation easier to read.

The rST files were automatically processed with:

sed -i '/DESCRIPTION/,/OPTIONS/ { /^\*/ s/\*\*//g }' b*.rst

Signed-off-by: Rameez Rehman <rameezrehman408@hotmail.com>
Signed-off-by: Quentin Monnet <qmo@kernel.org>
Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
Link: https://lore.kernel.org/bpf/20240331200346.29118-3-qmo@kernel.org

authored by

Rameez Rehman and committed by
Daniel Borkmann ea379b3c f7b68543

+61 -61
+3 -3
tools/bpf/bpftool/Documentation/bpftool-btf.rst
··· 34 34 35 35 DESCRIPTION 36 36 =========== 37 - **bpftool btf { show | list }** [**id** *BTF_ID*] 37 + bpftool btf { show | list } [id *BTF_ID*] 38 38 Show information about loaded BTF objects. If a BTF ID is specified, show 39 39 information only about given BTF object, otherwise list all BTF objects 40 40 currently loaded on the system. ··· 43 43 that hold open file descriptors (FDs) against BTF objects. On such kernels 44 44 bpftool will automatically emit this information as well. 45 45 46 - **bpftool btf dump** *BTF_SRC* 46 + bpftool btf dump *BTF_SRC* 47 47 Dump BTF entries from a given *BTF_SRC*. 48 48 49 49 When **id** is specified, BTF object with that ID will be loaded and all ··· 65 65 **format** option can be used to override default (raw) output format. Raw 66 66 (**raw**) or C-syntax (**c**) output formats are supported. 67 67 68 - **bpftool btf help** 68 + bpftool btf help 69 69 Print short help message. 70 70 71 71 OPTIONS
+5 -5
tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
··· 49 49 50 50 DESCRIPTION 51 51 =========== 52 - **bpftool cgroup { show | list }** *CGROUP* [**effective**] 52 + bpftool cgroup { show | list } *CGROUP* [effective] 53 53 List all programs attached to the cgroup *CGROUP*. 54 54 55 55 Output will start with program ID followed by attach type, attach flags and ··· 59 59 for events within a cgroup. This includes inherited along with attached 60 60 ones. 61 61 62 - **bpftool cgroup tree** [*CGROUP_ROOT*] [**effective**] 62 + bpftool cgroup tree [*CGROUP_ROOT*] [effective] 63 63 Iterate over all cgroups in *CGROUP_ROOT* and list all attached programs. 64 64 If *CGROUP_ROOT* is not specified, bpftool uses cgroup v2 mountpoint. 65 65 ··· 71 71 for events within a cgroup. This includes inherited along with attached 72 72 ones. 73 73 74 - **bpftool cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*] 74 + bpftool cgroup attach *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*] 75 75 Attach program *PROG* to the cgroup *CGROUP* with attach type *ATTACH_TYPE* 76 76 and optional *ATTACH_FLAGS*. 77 77 ··· 126 126 **getsockname_unix** call to getsockname(2) for a unix socket (since 6.7); 127 127 **sock_release** closing an userspace inet socket (since 5.9). 128 128 129 - **bpftool cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG* 129 + bpftool cgroup detach *CGROUP* *ATTACH_TYPE* *PROG* 130 130 Detach *PROG* from the cgroup *CGROUP* and attach type *ATTACH_TYPE*. 131 131 132 - **bpftool prog help** 132 + bpftool prog help 133 133 Print short help message. 134 134 135 135 OPTIONS
+4 -4
tools/bpf/bpftool/Documentation/bpftool-feature.rst
··· 32 32 33 33 DESCRIPTION 34 34 =========== 35 - **bpftool feature probe** [**kernel**] [**full**] [**macros** [**prefix** *PREFIX*]] 35 + bpftool feature probe [kernel] [full] [macros [prefix *PREFIX*]] 36 36 Probe the running kernel and dump a number of eBPF-related parameters, such 37 37 as availability of the **bpf**\ () system call, JIT status, eBPF program 38 38 types availability, eBPF helper functions availability, and more. ··· 59 59 bpftool is inadvertently run as non-root, for example. This keyword is 60 60 unavailable if bpftool was compiled without libcap. 61 61 62 - **bpftool feature probe dev** *NAME* [**full**] [**macros** [**prefix** *PREFIX*]] 62 + bpftool feature probe dev *NAME* [full] [macros [prefix *PREFIX*]] 63 63 Probe network device for supported eBPF features and dump results to the 64 64 console. 65 65 66 66 The keywords **full**, **macros** and **prefix** have the same role as when 67 67 probing the kernel. 68 68 69 - **bpftool feature list_builtins** *GROUP* 69 + bpftool feature list_builtins *GROUP* 70 70 List items known to bpftool. These can be BPF program types 71 71 (**prog_types**), BPF map types (**map_types**), attach types 72 72 (**attach_types**), link types (**link_types**), or BPF helper functions ··· 75 75 (for all object types) or from the BPF UAPI header (list of helpers). This 76 76 can be used in scripts to iterate over BPF types or helpers. 77 77 78 - **bpftool feature help** 78 + bpftool feature help 79 79 Print short help message. 80 80 81 81 OPTIONS
+5 -5
tools/bpf/bpftool/Documentation/bpftool-gen.rst
··· 31 31 32 32 DESCRIPTION 33 33 =========== 34 - **bpftool gen object** *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...] 34 + bpftool gen object *OUTPUT_FILE* *INPUT_FILE* [*INPUT_FILE*...] 35 35 Statically link (combine) together one or more *INPUT_FILE*'s into a single 36 36 resulting *OUTPUT_FILE*. All the files involved are BPF ELF object files. 37 37 ··· 48 48 command) or passed directly into **libbpf** (using **bpf_object__open()** 49 49 family of APIs). 50 50 51 - **bpftool gen skeleton** *FILE* 51 + bpftool gen skeleton *FILE* 52 52 Generate BPF skeleton C header file for a given *FILE*. 53 53 54 54 BPF skeleton is an alternative interface to existing libbpf APIs for ··· 132 132 used to fetch and update (non-read-only) data from userspace, with same 133 133 simplicity as for BPF side. 134 134 135 - **bpftool gen subskeleton** *FILE* 135 + bpftool gen subskeleton *FILE* 136 136 Generate BPF subskeleton C header file for a given *FILE*. 137 137 138 138 Subskeletons are similar to skeletons, except they do not own the ··· 154 154 Frees the storage for the subskeleton but *does not* unload any BPF 155 155 programs or maps. 156 156 157 - **bpftool** **gen min_core_btf** *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...] 157 + bpftool gen min_core_btf *INPUT* *OUTPUT* *OBJECT* [*OBJECT*...] 158 158 Generate a minimum BTF file as *OUTPUT*, derived from a given *INPUT* BTF 159 159 file, containing all needed BTF types so one, or more, given eBPF objects 160 160 CO-RE relocations may be satisfied. ··· 174 174 175 175 Check examples bellow for more information how to use it. 176 176 177 - **bpftool gen help** 177 + bpftool gen help 178 178 Print short help message. 179 179 180 180 OPTIONS
+2 -2
tools/bpf/bpftool/Documentation/bpftool-iter.rst
··· 31 31 32 32 DESCRIPTION 33 33 =========== 34 - **bpftool iter pin** *OBJ* *PATH* [**map** *MAP*] 34 + bpftool iter pin *OBJ* *PATH* [map *MAP*] 35 35 A bpf iterator combines a kernel iterating of particular kernel data (e.g., 36 36 tasks, bpf_maps, etc.) and a bpf program called for each kernel data object 37 37 (e.g., one task, one bpf_map, etc.). User space can *read* kernel iterator ··· 48 48 49 49 User can then *cat PATH* to see the bpf iterator output. 50 50 51 - **bpftool iter help** 51 + bpftool iter help 52 52 Print short help message. 53 53 54 54 OPTIONS
+4 -4
tools/bpf/bpftool/Documentation/bpftool-link.rst
··· 33 33 34 34 DESCRIPTION 35 35 =========== 36 - **bpftool link { show | list }** [*LINK*] 36 + bpftool link { show | list } [*LINK*] 37 37 Show information about active links. If *LINK* is specified show 38 38 information only about given link, otherwise list all links currently 39 39 active on the system. ··· 45 45 that hold open file descriptors (FDs) against BPF links. On such kernels 46 46 bpftool will automatically emit this information as well. 47 47 48 - **bpftool link pin** *LINK* *FILE* 48 + bpftool link pin *LINK* *FILE* 49 49 Pin link *LINK* as *FILE*. 50 50 51 51 Note: *FILE* must be located in *bpffs* mount. It must not contain a dot 52 52 character ('.'), which is reserved for future extensions of *bpffs*. 53 53 54 - **bpftool link detach** *LINK* 54 + bpftool link detach *LINK* 55 55 Force-detach link *LINK*. BPF link and its underlying BPF program will stay 56 56 valid, but they will be detached from the respective BPF hook and BPF link 57 57 will transition into a defunct state until last open file descriptor for 58 58 that link is closed. 59 59 60 - **bpftool link help** 60 + bpftool link help 61 61 Print short help message. 62 62 63 63 OPTIONS
+16 -16
tools/bpf/bpftool/Documentation/bpftool-map.rst
··· 59 59 60 60 DESCRIPTION 61 61 =========== 62 - **bpftool map { show | list }** [*MAP*] 62 + bpftool map { show | list } [*MAP*] 63 63 Show information about loaded maps. If *MAP* is specified show information 64 64 only about given maps, otherwise list all maps currently loaded on the 65 65 system. In case of **name**, *MAP* may match several maps which will all ··· 72 72 that hold open file descriptors (FDs) against BPF maps. On such kernels 73 73 bpftool will automatically emit this information as well. 74 74 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*] 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 76 Create a new map with given parameters and pin it to *bpffs* as *FILE*. 77 77 78 78 *FLAGS* should be an integer which is the combination of desired flags, ··· 86 86 Keyword **offload_dev** expects a network interface name, and is used to 87 87 request hardware offload for the map. 88 88 89 - **bpftool map dump** *MAP* 89 + bpftool map dump *MAP* 90 90 Dump all entries in a given *MAP*. In case of **name**, *MAP* may match 91 91 several maps which will all be dumped. 92 92 93 - **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 93 + bpftool map update *MAP* [key *DATA*] [value *VALUE*] [*UPDATE_FLAGS*] 94 94 Update map entry for a given *KEY*. 95 95 96 96 *UPDATE_FLAGS* can be one of: **any** update existing entry or add if ··· 103 103 unless a "0x" prefix (for hexadecimal) or a "0" prefix (for octal) is 104 104 provided. 105 105 106 - **bpftool map lookup** *MAP* [**key** *DATA*] 106 + bpftool map lookup *MAP* [key *DATA*] 107 107 Lookup **key** in the map. 108 108 109 - **bpftool map getnext** *MAP* [**key** *DATA*] 109 + bpftool map getnext *MAP* [key *DATA*] 110 110 Get next key. If *key* is not specified, get first key. 111 111 112 - **bpftool map delete** *MAP* **key** *DATA* 112 + bpftool map delete *MAP* key *DATA* 113 113 Remove entry from the map. 114 114 115 - **bpftool map pin** *MAP* *FILE* 115 + bpftool map pin *MAP* *FILE* 116 116 Pin map *MAP* as *FILE*. 117 117 118 118 Note: *FILE* must be located in *bpffs* mount. It must not contain a dot 119 119 character ('.'), which is reserved for future extensions of *bpffs*. 120 120 121 - **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 121 + bpftool map event_pipe *MAP* [cpu *N* index *M*] 122 122 Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map. 123 123 124 124 Install perf rings into a perf event array map and dump output of any ··· 133 133 existing ring. Any other application will stop receiving events if it 134 134 installed its rings earlier. 135 135 136 - **bpftool map peek** *MAP* 136 + bpftool map peek *MAP* 137 137 Peek next value in the queue or stack. 138 138 139 - **bpftool map push** *MAP* **value** *VALUE* 139 + bpftool map push *MAP* value *VALUE* 140 140 Push *VALUE* onto the stack. 141 141 142 - **bpftool map pop** *MAP* 142 + bpftool map pop *MAP* 143 143 Pop and print value from the stack. 144 144 145 - **bpftool map enqueue** *MAP* **value** *VALUE* 145 + bpftool map enqueue *MAP* value *VALUE* 146 146 Enqueue *VALUE* into the queue. 147 147 148 - **bpftool map dequeue** *MAP* 148 + bpftool map dequeue *MAP* 149 149 Dequeue and print value from the queue. 150 150 151 - **bpftool map freeze** *MAP* 151 + bpftool map freeze *MAP* 152 152 Freeze the map as read-only from user space. Entries from a frozen map can 153 153 not longer be updated or deleted with the **bpf**\ () system call. This 154 154 operation is not reversible, and the map remains immutable from user space 155 155 until its destruction. However, read and write permissions for BPF programs 156 156 to the map remain unchanged. 157 157 158 - **bpftool map help** 158 + bpftool map help 159 159 Print short help message. 160 160 161 161 OPTIONS
+4 -4
tools/bpf/bpftool/Documentation/bpftool-net.rst
··· 33 33 34 34 DESCRIPTION 35 35 =========== 36 - **bpftool net { show | list }** [ **dev** *NAME* ] 36 + bpftool net { show | list } [ dev *NAME* ] 37 37 List bpf program attachments in the kernel networking subsystem. 38 38 39 39 Currently, device driver xdp attachments, tcx, netkit and old-style tc ··· 58 58 then all bpf programs attached to non clsact qdiscs, and finally all bpf 59 59 programs attached to root and clsact qdisc. 60 60 61 - **bpftool** **net attach** *ATTACH_TYPE* *PROG* **dev** *NAME* [ **overwrite** ] 61 + bpftool net attach *ATTACH_TYPE* *PROG* dev *NAME* [ overwrite ] 62 62 Attach bpf program *PROG* to network interface *NAME* with type specified 63 63 by *ATTACH_TYPE*. Previously attached bpf program can be replaced by the 64 64 command used with **overwrite** option. Currently, only XDP-related modes ··· 70 70 **xdpdrv** - Native XDP. runs earliest point in driver's receive path; 71 71 **xdpoffload** - Offload XDP. runs directly on NIC on each packet reception; 72 72 73 - **bpftool** **net detach** *ATTACH_TYPE* **dev** *NAME* 73 + bpftool net detach *ATTACH_TYPE* dev *NAME* 74 74 Detach bpf program attached to network interface *NAME* with type specified 75 75 by *ATTACH_TYPE*. To detach bpf program, same *ATTACH_TYPE* previously used 76 76 for attach must be specified. Currently, only XDP-related modes are 77 77 supported for *ATTACH_TYPE*. 78 78 79 - **bpftool net help** 79 + bpftool net help 80 80 Print short help message. 81 81 82 82 OPTIONS
+2 -2
tools/bpf/bpftool/Documentation/bpftool-perf.rst
··· 29 29 30 30 DESCRIPTION 31 31 =========== 32 - **bpftool perf { show | list }** 32 + bpftool perf { show | list } 33 33 List all raw_tracepoint, tracepoint, kprobe attachment in the system. 34 34 35 35 Output will start with process id and file descriptor in that process, ··· 39 39 kernel virtual address. The attachment point for u[ret]probe is the file 40 40 name and the file offset. 41 41 42 - **bpftool perf help** 42 + bpftool perf help 43 43 Print short help message. 44 44 45 45 OPTIONS
+11 -11
tools/bpf/bpftool/Documentation/bpftool-prog.rst
··· 67 67 68 68 DESCRIPTION 69 69 =========== 70 - **bpftool prog { show | list }** [*PROG*] 70 + bpftool prog { show | list } [*PROG*] 71 71 Show information about loaded programs. If *PROG* is specified show 72 72 information only about given programs, otherwise list all programs 73 73 currently loaded on the system. In case of **tag** or **name**, *PROG* may ··· 87 87 that hold open file descriptors (FDs) against BPF programs. On such kernels 88 88 bpftool will automatically emit this information as well. 89 89 90 - **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] [**visual**] }] 90 + bpftool prog dump xlated *PROG* [{ file *FILE* | [opcodes] [linum] [visual] }] 91 91 Dump eBPF instructions of the programs from the kernel. By default, eBPF 92 92 will be disassembled and printed to standard output in human-readable 93 93 format. In this case, **opcodes** controls if raw opcodes should be printed ··· 108 108 displayed. If **linum** is specified, the filename, line number and line 109 109 column will also be displayed. 110 110 111 - **bpftool prog dump jited** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] }] 111 + bpftool prog dump jited *PROG* [{ file *FILE* | [opcodes] [linum] }] 112 112 Dump jited image (host machine code) of the program. 113 113 114 114 If *FILE* is specified image will be written to a file, otherwise it will ··· 121 121 **linum** is specified, the filename, line number and line column will also 122 122 be displayed. 123 123 124 - **bpftool prog pin** *PROG* *FILE* 124 + bpftool prog pin *PROG* *FILE* 125 125 Pin program *PROG* as *FILE*. 126 126 127 127 Note: *FILE* must be located in *bpffs* mount. It must not contain a dot 128 128 character ('.'), which is reserved for future extensions of *bpffs*. 129 129 130 - **bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** { **idx** *IDX* | **name** *NAME* } *MAP*] [{ **offload_dev** | **xdpmeta_dev** } *NAME*] [**pinmaps** *MAP_DIR*] [**autoattach**] 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 131 Load bpf program(s) from binary *OBJ* and pin as *PATH*. **bpftool prog 132 132 load** pins only the first program from the *OBJ* as *PATH*. **bpftool prog 133 133 loadall** pins all programs from the *OBJ* under *PATH* directory. **type** ··· 156 156 Note: *PATH* must be located in *bpffs* mount. It must not contain a dot 157 157 character ('.'), which is reserved for future extensions of *bpffs*. 158 158 159 - **bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*] 159 + bpftool prog attach *PROG* *ATTACH_TYPE* [*MAP*] 160 160 Attach bpf program *PROG* (with type specified by *ATTACH_TYPE*). Most 161 161 *ATTACH_TYPEs* require a *MAP* parameter, with the exception of 162 162 *flow_dissector* which is attached to current networking name space. 163 163 164 - **bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*] 164 + bpftool prog detach *PROG* *ATTACH_TYPE* [*MAP*] 165 165 Detach bpf program *PROG* (with type specified by *ATTACH_TYPE*). Most 166 166 *ATTACH_TYPEs* require a *MAP* parameter, with the exception of 167 167 *flow_dissector* which is detached from the current networking name space. 168 168 169 - **bpftool prog tracelog** 169 + bpftool prog tracelog 170 170 Dump the trace pipe of the system to the console (stdout). Hit <Ctrl+C> to 171 171 stop printing. BPF programs can write to this trace pipe at runtime with 172 172 the **bpf_trace_printk**\ () helper. This should be used only for debugging 173 173 purposes. For streaming data from BPF programs to user space, one can use 174 174 perf events (see also **bpftool-map**\ (8)). 175 175 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*] 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 177 Run BPF program *PROG* in the kernel testing infrastructure for BPF, 178 178 meaning that the program works on the data and context provided by the 179 179 user, and not on actual packets or monitored functions etc. Return value ··· 201 201 them can take the **ctx_in**/**ctx_out** arguments. bpftool does not 202 202 perform checks on program types. 203 203 204 - **bpftool prog profile** *PROG* [**duration** *DURATION*] *METRICs* 204 + bpftool prog profile *PROG* [duration *DURATION*] *METRICs* 205 205 Profile *METRICs* for bpf program *PROG* for *DURATION* seconds or until 206 206 user hits <Ctrl+C>. *DURATION* is optional. If *DURATION* is not specified, 207 207 the profiling will run up to **UINT_MAX** seconds. 208 208 209 - **bpftool prog help** 209 + bpftool prog help 210 210 Print short help message. 211 211 212 212 OPTIONS
+5 -5
tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
··· 36 36 37 37 DESCRIPTION 38 38 =========== 39 - **bpftool struct_ops { show | list }** [*STRUCT_OPS_MAP*] 39 + bpftool struct_ops { show | list } [*STRUCT_OPS_MAP*] 40 40 Show brief information about the struct_ops in the system. If 41 41 *STRUCT_OPS_MAP* is specified, it shows information only for the given 42 42 struct_ops. Otherwise, it lists all struct_ops currently existing in the ··· 45 45 Output will start with struct_ops map ID, followed by its map name and its 46 46 struct_ops's kernel type. 47 47 48 - **bpftool struct_ops dump** [*STRUCT_OPS_MAP*] 48 + bpftool struct_ops dump [*STRUCT_OPS_MAP*] 49 49 Dump details information about the struct_ops in the system. If 50 50 *STRUCT_OPS_MAP* is specified, it dumps information only for the given 51 51 struct_ops. Otherwise, it dumps all struct_ops currently existing in the 52 52 system. 53 53 54 - **bpftool struct_ops register** *OBJ* [*LINK_DIR*] 54 + bpftool struct_ops register *OBJ* [*LINK_DIR*] 55 55 Register bpf struct_ops from *OBJ*. All struct_ops under the ELF section 56 56 ".struct_ops" and ".struct_ops.link" will be registered to its kernel 57 57 subsystem. For each struct_ops in the ".struct_ops.link" section, a link ··· 59 59 these links will be pinned with the same name as their corresponding map 60 60 name. 61 61 62 - **bpftool struct_ops unregister** *STRUCT_OPS_MAP* 62 + bpftool struct_ops unregister *STRUCT_OPS_MAP* 63 63 Unregister the *STRUCT_OPS_MAP* from the kernel subsystem. 64 64 65 - **bpftool struct_ops help** 65 + bpftool struct_ops help 66 66 Print short help message. 67 67 68 68 OPTIONS