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 ff4d327..1d37f38 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 baee859..3e4395e 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 dd3771b..ab9f57e 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 7cd6681..709b93f 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 51f49be..471f363 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 5f7db2a..0de90f0 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 3d52256..d0c4abe 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 d8165d5..1ae0375 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 e958ce9..ce52798 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 abf5f4c..4b8412f 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 506e70e..02afc0f 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 e7d9493..bb23f55 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 0ce3643..3c5fc9b 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 6e53b1d..c42f437 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 40a88df..7f36385 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 1d71ff8..d4225f7 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 3b1aad7..84a9b01 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 e77e152..8cc3e36 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 3ddfd48..02eaaf0 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 c1cf297..90caa42 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 7e7f748..407071d 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 f836d11..6490537 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 ad23934..50de087 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 d98cfc9..a205f71 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 b58b91f..ab2d229 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]);