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

tools: bpftool: Update and synchronise option list in doc and help msg

All bpftool commands support the options for JSON output and debug from
libbpf. In addition, some commands support additional options
corresponding to specific use cases.

The list of options described in the man pages for the different
commands are not always accurate. The messages for interactive help are
mostly limited to HELP_SPEC_OPTIONS, and are even less representative of
the actual set of options supported for the commands.

Let's update the lists:

- HELP_SPEC_OPTIONS is modified to contain the "default" options (JSON
and debug), and to be extensible (no ending curly bracket).
- All commands use HELP_SPEC_OPTIONS in their help message, and then
complete the list with their specific options.
- The lists of options in the man pages are updated.
- The formatting of the list for bpftool.rst is adjusted to match
formatting for the other man pages. This is for consistency, and also
because it will be helpful in a future patch to automatically check
that the files are synchronised.

Signed-off-by: Quentin Monnet <quentin@isovalent.com>
Signed-off-by: Andrii Nakryiko <andrii@kernel.org>
Link: https://lore.kernel.org/bpf/20210730215435.7095-5-quentin@isovalent.com

authored by

Quentin Monnet and committed by
Andrii Nakryiko c07ba629 b544342e

+45 -28
+1 -1
tools/bpf/bpftool/Documentation/bpftool-btf.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **btf** *COMMAND* 14 14 15 - *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | {**-d** | **--debug** } } 16 16 17 17 *COMMANDS* := { **dump** | **help** } 18 18
+2 -1
tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **cgroup** *COMMAND* 14 14 15 - *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } | 16 + { **-f** | **--bpffs** } } 16 17 17 18 *COMMANDS* := 18 19 { **show** | **list** | **tree** | **attach** | **detach** | **help** }
+1 -1
tools/bpf/bpftool/Documentation/bpftool-feature.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **feature** *COMMAND* 14 14 15 - *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } } 16 16 17 17 *COMMANDS* := { **probe** | **help** } 18 18
+1 -1
tools/bpf/bpftool/Documentation/bpftool-gen.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **gen** *COMMAND* 14 14 15 - *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } } 16 16 17 17 *COMMAND* := { **object** | **skeleton** | **help** } 18 18
+2
tools/bpf/bpftool/Documentation/bpftool-iter.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **iter** *COMMAND* 14 14 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } } 16 + 15 17 *COMMANDS* := { **pin** | **help** } 16 18 17 19 ITER COMMANDS
+2 -1
tools/bpf/bpftool/Documentation/bpftool-link.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **link** *COMMAND* 14 14 15 - *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } | 16 + { **-f** | **--bpffs** } | { **-n** | **--nomount** } } 16 17 17 18 *COMMANDS* := { **show** | **list** | **pin** | **help** } 18 19
+2 -1
tools/bpf/bpftool/Documentation/bpftool-map.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **map** *COMMAND* 14 14 15 - *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } | 16 + { **-f** | **--bpffs** } | { **-n** | **--nomount** } } 16 17 17 18 *COMMANDS* := 18 19 { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext**
+1 -1
tools/bpf/bpftool/Documentation/bpftool-net.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **net** *COMMAND* 14 14 15 - *OPTIONS* := { [{ **-j** | **--json** }] [{ **-p** | **--pretty** }] } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } } 16 16 17 17 *COMMANDS* := 18 18 { **show** | **list** | **attach** | **detach** | **help** }
+1 -1
tools/bpf/bpftool/Documentation/bpftool-perf.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **perf** *COMMAND* 14 14 15 - *OPTIONS* := { [{ **-j** | **--json** }] [{ **-p** | **--pretty** }] } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } } 16 16 17 17 *COMMANDS* := 18 18 { **show** | **list** | **help** }
+2 -1
tools/bpf/bpftool/Documentation/bpftool-prog.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **prog** *COMMAND* 14 14 15 - *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } | 16 + { **-f** | **--bpffs** } | { **-m** | **--mapcompat** } | { **-n** | **--nomount** } } 16 17 17 18 *COMMANDS* := 18 19 { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load**
+1 -1
tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
··· 12 12 13 13 **bpftool** [*OPTIONS*] **struct_ops** *COMMAND* 14 14 15 - *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } 15 + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } } 16 16 17 17 *COMMANDS* := 18 18 { **show** | **list** | **dump** | **register** | **unregister** | **help** }
+6 -6
tools/bpf/bpftool/Documentation/bpftool.rst
··· 18 18 19 19 *OBJECT* := { **map** | **program** | **cgroup** | **perf** | **net** | **feature** } 20 20 21 - *OPTIONS* := { { **-V** | **--version** } | { **-h** | **--help** } 22 - | { **-j** | **--json** } [{ **-p** | **--pretty** }] } 21 + *OPTIONS* := { { **-V** | **--version** } | 22 + { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } } 23 23 24 24 *MAP-COMMANDS* := 25 - { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** 26 - | **delete** | **pin** | **event_pipe** | **help** } 25 + { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** | 26 + **delete** | **pin** | **event_pipe** | **help** } 27 27 28 - *PROG-COMMANDS* := { **show** | **list** | **dump jited** | **dump xlated** | **pin** 29 - | **load** | **attach** | **detach** | **help** } 28 + *PROG-COMMANDS* := { **show** | **list** | **dump jited** | **dump xlated** | **pin** | 29 + **load** | **attach** | **detach** | **help** } 30 30 31 31 *CGROUP-COMMANDS* := { **show** | **list** | **attach** | **detach** | **help** } 32 32
+1 -1
tools/bpf/bpftool/btf.c
··· 981 981 " FORMAT := { raw | c }\n" 982 982 " " HELP_SPEC_MAP "\n" 983 983 " " HELP_SPEC_PROGRAM "\n" 984 - " " HELP_SPEC_OPTIONS "\n" 984 + " " HELP_SPEC_OPTIONS " }\n" 985 985 "", 986 986 bin_name, "btf"); 987 987
+2 -1
tools/bpf/bpftool/cgroup.c
··· 501 501 HELP_SPEC_ATTACH_TYPES "\n" 502 502 " " HELP_SPEC_ATTACH_FLAGS "\n" 503 503 " " HELP_SPEC_PROGRAM "\n" 504 - " " HELP_SPEC_OPTIONS "\n" 504 + " " HELP_SPEC_OPTIONS " |\n" 505 + " {-f|--bpffs} } 505 506 "", 506 507 bin_name, argv[-2]); 507 508
+1
tools/bpf/bpftool/feature.c
··· 1005 1005 " %1$s %2$s help\n" 1006 1006 "\n" 1007 1007 " COMPONENT := { kernel | dev NAME }\n" 1008 + " " HELP_SPEC_OPTIONS " }\n" 1008 1009 "", 1009 1010 bin_name, argv[-2]); 1010 1011
+1 -1
tools/bpf/bpftool/gen.c
··· 1026 1026 " %1$s %2$s skeleton FILE [name OBJECT_NAME]\n" 1027 1027 " %1$s %2$s help\n" 1028 1028 "\n" 1029 - " " HELP_SPEC_OPTIONS "\n" 1029 + " " HELP_SPEC_OPTIONS " }\n" 1030 1030 "", 1031 1031 bin_name, "gen"); 1032 1032
+2
tools/bpf/bpftool/iter.c
··· 97 97 fprintf(stderr, 98 98 "Usage: %1$s %2$s pin OBJ PATH [map MAP]\n" 99 99 " %1$s %2$s help\n" 100 + "\n" 100 101 " " HELP_SPEC_MAP "\n" 102 + " " HELP_SPEC_OPTIONS " }\n" 101 103 "", 102 104 bin_name, "iter"); 103 105
+2 -1
tools/bpf/bpftool/link.c
··· 401 401 " %1$s %2$s help\n" 402 402 "\n" 403 403 " " HELP_SPEC_LINK "\n" 404 - " " HELP_SPEC_OPTIONS "\n" 404 + " " HELP_SPEC_OPTIONS " |\n" 405 + " {-f|--bpffs} | {-n|--nomount} }\n" 405 406 "", 406 407 bin_name, argv[-2]); 407 408
+2 -1
tools/bpf/bpftool/main.c
··· 64 64 " %s version\n" 65 65 "\n" 66 66 " OBJECT := { prog | map | link | cgroup | perf | net | feature | btf | gen | struct_ops | iter }\n" 67 - " " HELP_SPEC_OPTIONS "\n" 67 + " " HELP_SPEC_OPTIONS " |\n" 68 + " {-V|--version} }\n" 68 69 "", 69 70 bin_name, bin_name, bin_name); 70 71
+1 -2
tools/bpf/bpftool/main.h
··· 57 57 #define HELP_SPEC_PROGRAM \ 58 58 "PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }" 59 59 #define HELP_SPEC_OPTIONS \ 60 - "OPTIONS := { {-j|--json} [{-p|--pretty}] | {-f|--bpffs} |\n" \ 61 - "\t {-m|--mapcompat} | {-n|--nomount} }" 60 + "OPTIONS := { {-j|--json} [{-p|--pretty}] | {-d|--debug}" 62 61 #define HELP_SPEC_MAP \ 63 62 "MAP := { id MAP_ID | pinned FILE | name MAP_NAME }" 64 63 #define HELP_SPEC_LINK \
+3 -2
tools/bpf/bpftool/map.c
··· 1466 1466 " devmap | devmap_hash | sockmap | cpumap | xskmap | sockhash |\n" 1467 1467 " cgroup_storage | reuseport_sockarray | percpu_cgroup_storage |\n" 1468 1468 " queue | stack | sk_storage | struct_ops | ringbuf | inode_storage |\n" 1469 - " task_storage }\n" 1470 - " " HELP_SPEC_OPTIONS "\n" 1469 + " task_storage }\n" 1470 + " " HELP_SPEC_OPTIONS " |\n" 1471 + " {-f|--bpffs} | {-n|--nomount} }\n" 1471 1472 "", 1472 1473 bin_name, argv[-2]); 1473 1474
+1
tools/bpf/bpftool/net.c
··· 729 729 "\n" 730 730 " " HELP_SPEC_PROGRAM "\n" 731 731 " ATTACH_TYPE := { xdp | xdpgeneric | xdpdrv | xdpoffload }\n" 732 + " " HELP_SPEC_OPTIONS " }\n" 732 733 "\n" 733 734 "Note: Only xdp and tc attachments are supported now.\n" 734 735 " For progs attached to cgroups, use \"bpftool cgroup\"\n"
+4 -1
tools/bpf/bpftool/perf.c
··· 231 231 static int do_help(int argc, char **argv) 232 232 { 233 233 fprintf(stderr, 234 - "Usage: %1$s %2$s { show | list | help }\n" 234 + "Usage: %1$s %2$s { show | list }\n" 235 + " %1$s %2$s help }\n" 236 + "\n" 237 + " " HELP_SPEC_OPTIONS " }\n" 235 238 "", 236 239 bin_name, argv[-2]); 237 240
+2 -1
tools/bpf/bpftool/prog.c
··· 2259 2259 " ATTACH_TYPE := { msg_verdict | skb_verdict | stream_verdict |\n" 2260 2260 " stream_parser | flow_dissector }\n" 2261 2261 " METRIC := { cycles | instructions | l1d_loads | llc_misses | itlb_misses | dtlb_misses }\n" 2262 - " " HELP_SPEC_OPTIONS "\n" 2262 + " " HELP_SPEC_OPTIONS " |\n" 2263 + " {-f|--bpffs} | {-m|--mapcompat} | {-n|--nomount} }\n" 2263 2264 "", 2264 2265 bin_name, argv[-2]); 2265 2266
+1 -1
tools/bpf/bpftool/struct_ops.c
··· 572 572 " %1$s %2$s unregister STRUCT_OPS_MAP\n" 573 573 " %1$s %2$s help\n" 574 574 "\n" 575 - " OPTIONS := { {-j|--json} [{-p|--pretty}] }\n" 576 575 " STRUCT_OPS_MAP := [ id STRUCT_OPS_MAP_ID | name STRUCT_OPS_MAP_NAME ]\n" 576 + " " HELP_SPEC_OPTIONS " }\n" 577 577 "", 578 578 bin_name, argv[-2]); 579 579