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

diff --git a/tools/bpf/bpftool/Documentation/bpftool-btf.rst b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
index ff4d327a582e6e7c39131f3eacc9f73f975cc150..1d37f38098428f78ebc2bfc4ee7a2a9338476a1f 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-btf.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
@@ -12,7 +12,7 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **btf** *COMMAND*
 
-       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | {**-d** | **--debug** } }
 
        *COMMANDS* := { **dump** | **help** }
 

diff --git a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
index baee8591ac76a4f9a869a558aac52fab37733e55..3e4395eede4f7b9894159e1da2bb77a25bd1d32c 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
@@ -12,7 +12,8 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **cgroup** *COMMAND*
 
-       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } |
+               { **-f** | **--bpffs** } }
 
        *COMMANDS* :=
        { **show** | **list** | **tree** | **attach** | **detach** | **help** }

diff --git a/tools/bpf/bpftool/Documentation/bpftool-feature.rst b/tools/bpf/bpftool/Documentation/bpftool-feature.rst
index dd3771bdbc5760b60ae1b13b3681a107ecac4648..ab9f57ee4c3ab0f9b4d7362c7f89eedfa618be9d 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-feature.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-feature.rst
@@ -12,7 +12,7 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **feature** *COMMAND*
 
-       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
 
        *COMMANDS* := { **probe** | **help** }
 

diff --git a/tools/bpf/bpftool/Documentation/bpftool-gen.rst b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
index 7cd6681137f388bf45e55d1d29a607e315fa1d25..709b93fe1da379a55dc401b29ebf1de5a8c1a026 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-gen.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-gen.rst
@@ -12,7 +12,7 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **gen** *COMMAND*
 
-       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
 
        *COMMAND* := { **object** | **skeleton** | **help** }
 

diff --git a/tools/bpf/bpftool/Documentation/bpftool-iter.rst b/tools/bpf/bpftool/Documentation/bpftool-iter.rst
index 51f49bead619ac37b256f39bb7cea7e9c3738926..471f363a725a973d0582296242964561bfdf9884 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-iter.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-iter.rst
@@ -12,6 +12,8 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **iter** *COMMAND*
 
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
+
        *COMMANDS* := { **pin** | **help** }
 
 ITER COMMANDS

diff --git a/tools/bpf/bpftool/Documentation/bpftool-link.rst b/tools/bpf/bpftool/Documentation/bpftool-link.rst
index 5f7db2a837cc87dd16afc9c384b6822c71d242e0..0de90f086238c6cfc71b8a8fdeb9893639bfbcb8 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-link.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-link.rst
@@ -12,7 +12,8 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **link** *COMMAND*
 
-       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } |
+               { **-f** | **--bpffs** } | { **-n** | **--nomount** } }
 
        *COMMANDS* := { **show** | **list** | **pin** | **help** }
 

diff --git a/tools/bpf/bpftool/Documentation/bpftool-map.rst b/tools/bpf/bpftool/Documentation/bpftool-map.rst
index 3d52256ba75f6950665c590bf0fa75478efb972a..d0c4abe08abab68e44c0d17492609179dc3fd62c 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-map.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-map.rst
@@ -12,7 +12,8 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **map** *COMMAND*
 
-       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } |
+               { **-f** | **--bpffs** } | { **-n** | **--nomount** } }
 
        *COMMANDS* :=
        { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext**

diff --git a/tools/bpf/bpftool/Documentation/bpftool-net.rst b/tools/bpf/bpftool/Documentation/bpftool-net.rst
index d8165d530937444b2ddc73419aceaff257c54f4e..1ae0375e8fea60581b1cb88a6b008e9d84daa579 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-net.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-net.rst
@@ -12,7 +12,7 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **net** *COMMAND*
 
-       *OPTIONS* := { [{ **-j** | **--json** }] [{ **-p** | **--pretty** }] }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
 
        *COMMANDS* :=
        { **show** | **list** | **attach** | **detach** | **help** }

diff --git a/tools/bpf/bpftool/Documentation/bpftool-perf.rst b/tools/bpf/bpftool/Documentation/bpftool-perf.rst
index e958ce91de72d7d018ac3b7d15b71791635660e7..ce52798a917d1b988e182a056c1caeb22ec26587 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-perf.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-perf.rst
@@ -12,7 +12,7 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **perf** *COMMAND*
 
-       *OPTIONS* := { [{ **-j** | **--json** }] [{ **-p** | **--pretty** }] }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
 
        *COMMANDS* :=
        { **show** | **list** | **help** }

diff --git a/tools/bpf/bpftool/Documentation/bpftool-prog.rst b/tools/bpf/bpftool/Documentation/bpftool-prog.rst
index abf5f4cd7d3e26e90c6ec4fee30c5b233b06bcca..4b8412fe2c60ba1232c0287c7d28fac52734be19 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-prog.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-prog.rst
@@ -12,7 +12,8 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **prog** *COMMAND*
 
-       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } |
+               { **-f** | **--bpffs** } | { **-m** | **--mapcompat** } | { **-n** | **--nomount** } }
 
        *COMMANDS* :=
        { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load**

diff --git a/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst b/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
index 506e70ee78e91d47dbe53087ebbf23f7a5bb2467..02afc0fc14cb3573992c0a385473f6babe7b178a 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool-struct_ops.rst
@@ -12,7 +12,7 @@ SYNOPSIS
 
        **bpftool** [*OPTIONS*] **struct_ops** *COMMAND*
 
-       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
+       *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
 
        *COMMANDS* :=
        { **show** | **list** | **dump** | **register** | **unregister** | **help** }

diff --git a/tools/bpf/bpftool/Documentation/bpftool.rst b/tools/bpf/bpftool/Documentation/bpftool.rst
index e7d9493349618dbc8fc03ccda12a333d6310ca3a..bb23f55bb05ad827d0a0664576a964f9969a4fd9 100644 (file)
--- a/tools/bpf/bpftool/Documentation/bpftool.rst
+++ b/tools/bpf/bpftool/Documentation/bpftool.rst
@@ -18,15 +18,15 @@ SYNOPSIS
 
        *OBJECT* := { **map** | **program** | **cgroup** | **perf** | **net** | **feature** }
 
-       *OPTIONS* := { { **-V** | **--version** } | { **-h** | **--help** }
-       | { **-j** | **--json** } [{ **-p** | **--pretty** }] }
+       *OPTIONS* := { { **-V** | **--version** } |
+               { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
 
        *MAP-COMMANDS* :=
-       { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext**
-       | **delete** | **pin** | **event_pipe** | **help** }
+       { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** |
+               **delete** | **pin** | **event_pipe** | **help** }
 
-       *PROG-COMMANDS* := { **show** | **list** | **dump jited** | **dump xlated** | **pin**
-       | **load** | **attach** | **detach** | **help** }
+       *PROG-COMMANDS* := { **show** | **list** | **dump jited** | **dump xlated** | **pin** |
+               **load** | **attach** | **detach** | **help** }
 
        *CGROUP-COMMANDS* := { **show** | **list** | **attach** | **detach** | **help** }
 

diff --git a/tools/bpf/bpftool/btf.c b/tools/bpf/bpftool/btf.c
index 0ce3643278d42c5e9c124ab048b7d8561a63fb84..3c5fc9b25c3076ba38975370050888bd833ebca0 100644 (file)
--- a/tools/bpf/bpftool/btf.c
+++ b/tools/bpf/bpftool/btf.c
@@ -981,7 +981,7 @@ static int do_help(int argc, char **argv)
                "       FORMAT  := { raw | c }\n"
                "       " HELP_SPEC_MAP "\n"
                "       " HELP_SPEC_PROGRAM "\n"
-               "       " HELP_SPEC_OPTIONS "\n"
+               "       " HELP_SPEC_OPTIONS " }\n"
                "",
                bin_name, "btf");
 

diff --git a/tools/bpf/bpftool/cgroup.c b/tools/bpf/bpftool/cgroup.c
index 6e53b1d393f4a497a700ee9d4da97361b109a3dd..c42f437a101575131b62ad96d4d30ae80971ff91 100644 (file)
--- a/tools/bpf/bpftool/cgroup.c
+++ b/tools/bpf/bpftool/cgroup.c
@@ -501,7 +501,8 @@ static int do_help(int argc, char **argv)
                HELP_SPEC_ATTACH_TYPES "\n"
                "       " HELP_SPEC_ATTACH_FLAGS "\n"
                "       " HELP_SPEC_PROGRAM "\n"
-               "       " HELP_SPEC_OPTIONS "\n"
+               "       " HELP_SPEC_OPTIONS " |\n"
+               "                    {-f|--bpffs} }
                "",
                bin_name, argv[-2]);
 

diff --git a/tools/bpf/bpftool/feature.c b/tools/bpf/bpftool/feature.c
index 40a88df275f95485fc399e3c41b815bc092a1a95..7f36385aa9e2e3773b0c8c2bb092bdd9bb84d097 100644 (file)
--- a/tools/bpf/bpftool/feature.c
+++ b/tools/bpf/bpftool/feature.c
@@ -1005,6 +1005,7 @@ static int do_help(int argc, char **argv)
                "       %1$s %2$s help\n"
                "\n"
                "       COMPONENT := { kernel | dev NAME }\n"
+               "       " HELP_SPEC_OPTIONS " }\n"
                "",
                bin_name, argv[-2]);
 

diff --git a/tools/bpf/bpftool/gen.c b/tools/bpf/bpftool/gen.c
index 1d71ff8c52fa3cf2feb5936e0ebf2be6f4e31ef0..d4225f7fbcee503a88c7e048689eccace5115959 100644 (file)
--- a/tools/bpf/bpftool/gen.c
+++ b/tools/bpf/bpftool/gen.c
@@ -1026,7 +1026,7 @@ static int do_help(int argc, char **argv)
                "       %1$s %2$s skeleton FILE [name OBJECT_NAME]\n"
                "       %1$s %2$s help\n"
                "\n"
-               "       " HELP_SPEC_OPTIONS "\n"
+               "       " HELP_SPEC_OPTIONS " }\n"
                "",
                bin_name, "gen");
 

diff --git a/tools/bpf/bpftool/iter.c b/tools/bpf/bpftool/iter.c
index 3b1aad7535dd816cdfec039830f41fe5ffd5d114..84a9b01d956dc358175534a8441c3e8573a74f60 100644 (file)
--- a/tools/bpf/bpftool/iter.c
+++ b/tools/bpf/bpftool/iter.c
@@ -97,7 +97,9 @@ static int do_help(int argc, char **argv)
        fprintf(stderr,
                "Usage: %1$s %2$s pin OBJ PATH [map MAP]\n"
                "       %1$s %2$s help\n"
+               "\n"
                "       " HELP_SPEC_MAP "\n"
+               "       " HELP_SPEC_OPTIONS " }\n"
                "",
                bin_name, "iter");
 

diff --git a/tools/bpf/bpftool/link.c b/tools/bpf/bpftool/link.c
index e77e1525d20ae0c6869fcc0fc5521f8c69369a57..8cc3e36f8cc6959d203ec9780313d0be0d053b06 100644 (file)
--- a/tools/bpf/bpftool/link.c
+++ b/tools/bpf/bpftool/link.c
@@ -401,7 +401,8 @@ static int do_help(int argc, char **argv)
                "       %1$s %2$s help\n"
                "\n"
                "       " HELP_SPEC_LINK "\n"
-               "       " HELP_SPEC_OPTIONS "\n"
+               "       " HELP_SPEC_OPTIONS " |\n"
+               "                    {-f|--bpffs} | {-n|--nomount} }\n"
                "",
                bin_name, argv[-2]);
 

diff --git a/tools/bpf/bpftool/main.c b/tools/bpf/bpftool/main.c
index 3ddfd4843738656add9ee06e0edae9c57b640836..02eaaf065f65153f920168530a334aee2245c7a6 100644 (file)
--- a/tools/bpf/bpftool/main.c
+++ b/tools/bpf/bpftool/main.c
@@ -64,7 +64,8 @@ static int do_help(int argc, char **argv)
                "       %s version\n"
                "\n"
                "       OBJECT := { prog | map | link | cgroup | perf | net | feature | btf | gen | struct_ops | iter }\n"
-               "       " HELP_SPEC_OPTIONS "\n"
+               "       " HELP_SPEC_OPTIONS " |\n"
+               "                    {-V|--version} }\n"
                "",
                bin_name, bin_name, bin_name);
 

diff --git a/tools/bpf/bpftool/main.h b/tools/bpf/bpftool/main.h
index c1cf29798b99264453af2611a39b564f786cdb94..90caa42aac4cf3f593eda32d61e7f61a4fdc2574 100644 (file)
--- a/tools/bpf/bpftool/main.h
+++ b/tools/bpf/bpftool/main.h
@@ -57,8 +57,7 @@ static inline void *u64_to_ptr(__u64 ptr)
 #define HELP_SPEC_PROGRAM                                              \
        "PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }"
 #define HELP_SPEC_OPTIONS                                              \
-       "OPTIONS := { {-j|--json} [{-p|--pretty}] | {-f|--bpffs} |\n"   \
-       "\t            {-m|--mapcompat} | {-n|--nomount} }"
+       "OPTIONS := { {-j|--json} [{-p|--pretty}] | {-d|--debug}"
 #define HELP_SPEC_MAP                                                  \
        "MAP := { id MAP_ID | pinned FILE | name MAP_NAME }"
 #define HELP_SPEC_LINK                                                 \

diff --git a/tools/bpf/bpftool/map.c b/tools/bpf/bpftool/map.c
index 7e7f748bb0be190ed970050adcc261f8520cb1c6..407071d54ab1ce6ba549480c2049e87b307e4e8c 100644 (file)
--- a/tools/bpf/bpftool/map.c
+++ b/tools/bpf/bpftool/map.c
@@ -1466,8 +1466,9 @@ static int do_help(int argc, char **argv)
                "                 devmap | devmap_hash | sockmap | cpumap | xskmap | sockhash |\n"
                "                 cgroup_storage | reuseport_sockarray | percpu_cgroup_storage |\n"
                "                 queue | stack | sk_storage | struct_ops | ringbuf | inode_storage |\n"
-               "                 task_storage }\n"
-               "       " HELP_SPEC_OPTIONS "\n"
+               "                 task_storage }\n"
+               "       " HELP_SPEC_OPTIONS " |\n"
+               "                    {-f|--bpffs} | {-n|--nomount} }\n"
                "",
                bin_name, argv[-2]);
 

diff --git a/tools/bpf/bpftool/net.c b/tools/bpf/bpftool/net.c
index f836d115d7d6a4789b0cf46e587d38a58d08305a..649053704bd7126db4955326b3ec83f457b431ec 100644 (file)
--- a/tools/bpf/bpftool/net.c
+++ b/tools/bpf/bpftool/net.c
@@ -729,6 +729,7 @@ static int do_help(int argc, char **argv)
                "\n"
                "       " HELP_SPEC_PROGRAM "\n"
                "       ATTACH_TYPE := { xdp | xdpgeneric | xdpdrv | xdpoffload }\n"
+               "       " HELP_SPEC_OPTIONS " }\n"
                "\n"
                "Note: Only xdp and tc attachments are supported now.\n"
                "      For progs attached to cgroups, use \"bpftool cgroup\"\n"

diff --git a/tools/bpf/bpftool/perf.c b/tools/bpf/bpftool/perf.c
index ad23934819c755f1faaea4459c275aacb43e3d51..50de087b0db72e529a3dbe693223664991423d4c 100644 (file)
--- a/tools/bpf/bpftool/perf.c
+++ b/tools/bpf/bpftool/perf.c
@@ -231,7 +231,10 @@ static int do_show(int argc, char **argv)
 static int do_help(int argc, char **argv)
 {
        fprintf(stderr,
-               "Usage: %1$s %2$s { show | list | help }\n"
+               "Usage: %1$s %2$s { show | list }\n"
+               "       %1$s %2$s help }\n"
+               "\n"
+               "       " HELP_SPEC_OPTIONS " }\n"
                "",
                bin_name, argv[-2]);
 

diff --git a/tools/bpf/bpftool/prog.c b/tools/bpf/bpftool/prog.c
index d98cfc973a1deca44c74a6c46b6a47ce48bc167f..a205f7124b3828059e1d4dd1006dc658f116f9cd 100644 (file)
--- a/tools/bpf/bpftool/prog.c
+++ b/tools/bpf/bpftool/prog.c
@@ -2259,7 +2259,8 @@ static int do_help(int argc, char **argv)
                "       ATTACH_TYPE := { msg_verdict | skb_verdict | stream_verdict |\n"
                "                        stream_parser | flow_dissector }\n"
                "       METRIC := { cycles | instructions | l1d_loads | llc_misses | itlb_misses | dtlb_misses }\n"
-               "       " HELP_SPEC_OPTIONS "\n"
+               "       " HELP_SPEC_OPTIONS " |\n"
+               "                    {-f|--bpffs} | {-m|--mapcompat} | {-n|--nomount} }\n"
                "",
                bin_name, argv[-2]);
 

diff --git a/tools/bpf/bpftool/struct_ops.c b/tools/bpf/bpftool/struct_ops.c
index b58b91f62ffb841710fcd94ce5716295209f2227..ab2d2290569a41bcd0a893abf2aa560a30a1f854 100644 (file)
--- a/tools/bpf/bpftool/struct_ops.c
+++ b/tools/bpf/bpftool/struct_ops.c
@@ -572,8 +572,8 @@ static int do_help(int argc, char **argv)
                "       %1$s %2$s unregister STRUCT_OPS_MAP\n"
                "       %1$s %2$s help\n"
                "\n"
-               "       OPTIONS := { {-j|--json} [{-p|--pretty}] }\n"
                "       STRUCT_OPS_MAP := [ id STRUCT_OPS_MAP_ID | name STRUCT_OPS_MAP_NAME ]\n"
+               "       " HELP_SPEC_OPTIONS " }\n"
                "",
                bin_name, argv[-2]);