From 0641c3c890d480abeb237b92a5ee4b99a22319c6 Mon Sep 17 00:00:00 2001 From: Quentin Monnet Date: Mon, 23 Oct 2017 09:24:16 -0700 Subject: [PATCH] tools: bpftool: update documentation for --json and --pretty usage Update the documentation to provide help about JSON output generation, and add an example in bpftool-prog manual page. Also reintroduce an example that was left aside when the tool was moved from GitHub to the kernel sources, in order to show how to mount the bpffs file system (to pin programs) inside the bpftool-prog manual page. Signed-off-by: Quentin Monnet Acked-by: Daniel Borkmann Signed-off-by: David S. Miller --- tools/bpf/bpftool/Documentation/bpftool-map.rst | 11 ++++- tools/bpf/bpftool/Documentation/bpftool-prog.rst | 61 +++++++++++++++++++++++- tools/bpf/bpftool/Documentation/bpftool.rst | 12 ++++- tools/bpf/bpftool/main.c | 6 ++- tools/bpf/bpftool/main.h | 2 + tools/bpf/bpftool/map.c | 1 + tools/bpf/bpftool/prog.c | 1 + 7 files changed, 88 insertions(+), 6 deletions(-) diff --git a/tools/bpf/bpftool/Documentation/bpftool-map.rst b/tools/bpf/bpftool/Documentation/bpftool-map.rst index 3954b3e..abb9ee9 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-map.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-map.rst @@ -10,7 +10,9 @@ tool for inspection and simple manipulation of eBPF maps SYNOPSIS ======== - **bpftool** **map** *COMMAND* + **bpftool** [*OPTIONS*] **map** *COMMAND* + + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } *COMMANDS* := { **show** | **dump** | **update** | **lookup** | **getnext** | **delete** @@ -77,6 +79,13 @@ OPTIONS -v, --version Print version number (similar to **bpftool version**). + -j, --json + Generate JSON output. For commands that cannot produce JSON, this + option has no effect. + + -p, --pretty + Generate human-readable JSON output. Implies **-j**. + EXAMPLES ======== **# bpftool map show** diff --git a/tools/bpf/bpftool/Documentation/bpftool-prog.rst b/tools/bpf/bpftool/Documentation/bpftool-prog.rst index 685a19e..0f25d3c 100644 --- a/tools/bpf/bpftool/Documentation/bpftool-prog.rst +++ b/tools/bpf/bpftool/Documentation/bpftool-prog.rst @@ -10,6 +10,16 @@ tool for inspection and simple manipulation of eBPF progs SYNOPSIS ======== + **bpftool** [*OPTIONS*] **prog** *COMMAND* + + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } + + *COMMANDS* := + { **show** | **dump xlated** | **dump jited** | **pin** | **help** } + +MAP COMMANDS +============= + | **bpftool** **prog show** [*PROG*] | **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes**}] | **bpftool** **prog dump jited** *PROG* [{**file** *FILE* | **opcodes**}] @@ -58,6 +68,13 @@ OPTIONS -v, --version Print version number (similar to **bpftool version**). + -j, --json + Generate JSON output. For commands that cannot produce JSON, this + option has no effect. + + -p, --pretty + Generate human-readable JSON output. Implies **-j**. + EXAMPLES ======== **# bpftool prog show** @@ -67,13 +84,33 @@ EXAMPLES loaded_at Sep 29/20:11 uid 0 xlated 528B jited 370B memlock 4096B map_ids 10 +**# bpftool --json --pretty prog show** + +:: + + { + "programs": [{ + "id": 10, + "type": "xdp", + "tag": "005a3d2123620c8b", + "loaded_at": "Sep 29/20:11", + "uid": 0, + "bytes_xlated": 528, + "jited": true, + "bytes_jited": 370, + "bytes_memlock": 4096, + "map_ids": [10 + ] + } + ] + } + | | **# bpftool prog dump xlated id 10 file /tmp/t** | **# ls -l /tmp/t** | -rw------- 1 root root 560 Jul 22 01:42 /tmp/t -| -| **# bpftool prog dum jited pinned /sys/fs/bpf/prog** +**# bpftool prog dum jited tag 005a3d2123620c8b** :: @@ -83,6 +120,26 @@ EXAMPLES sub $0x28,%rbp mov %rbx,0x0(%rbp) +| +| **# mount -t bpf none /sys/fs/bpf/** +| **# bpftool prog pin id 10 /sys/fs/bpf/prog** +| **# ls -l /sys/fs/bpf/** +| -rw------- 1 root root 0 Jul 22 01:43 prog + +**# bpftool prog dum jited pinned /sys/fs/bpf/prog opcodes** + +:: + + push %rbp + 55 + mov %rsp,%rbp + 48 89 e5 + sub $0x228,%rsp + 48 81 ec 28 02 00 00 + sub $0x28,%rbp + 48 83 ed 28 + mov %rbx,0x0(%rbp) + 48 89 5d 00 SEE ALSO diff --git a/tools/bpf/bpftool/Documentation/bpftool.rst b/tools/bpf/bpftool/Documentation/bpftool.rst index 44e0779..926c03d 100644 --- a/tools/bpf/bpftool/Documentation/bpftool.rst +++ b/tools/bpf/bpftool/Documentation/bpftool.rst @@ -10,7 +10,7 @@ tool for inspection and simple manipulation of eBPF programs and maps SYNOPSIS ======== - **bpftool** *OBJECT* { *COMMAND* | **help** } + **bpftool** [*OPTIONS*] *OBJECT* { *COMMAND* | **help** } **bpftool** **batch file** *FILE* @@ -18,6 +18,9 @@ SYNOPSIS *OBJECT* := { **map** | **program** } + *OPTIONS* := { { **-V** | **--version** } | { **-h** | **--help** } + | { **-j** | **--json** } [{ **-p** | **--pretty** }] } + *MAP-COMMANDS* := { **show** | **dump** | **update** | **lookup** | **getnext** | **delete** | **pin** | **help** } @@ -41,6 +44,13 @@ OPTIONS -v, --version Print version number (similar to **bpftool version**). + -j, --json + Generate JSON output. For commands that cannot produce JSON, this + option has no effect. + + -p, --pretty + Generate human-readable JSON output. Implies **-j**. + SEE ALSO ======== **bpftool-map**\ (8), **bpftool-prog**\ (8) diff --git a/tools/bpf/bpftool/main.c b/tools/bpf/bpftool/main.c index 55ba0a0..78d9afb 100644 --- a/tools/bpf/bpftool/main.c +++ b/tools/bpf/bpftool/main.c @@ -70,11 +70,13 @@ static int do_help(int argc, char **argv) } fprintf(stderr, - "Usage: %s OBJECT { COMMAND | help }\n" + "Usage: %s [OPTIONS] OBJECT { COMMAND | help }\n" " %s batch file FILE\n" " %s version\n" "\n" - " OBJECT := { prog | map }\n", + " OBJECT := { prog | map }\n" + " " HELP_SPEC_OPTIONS "\n" + "", bin_name, bin_name, bin_name); return 0; diff --git a/tools/bpf/bpftool/main.h b/tools/bpf/bpftool/main.h index 04c88b5..2f94bed0 100644 --- a/tools/bpf/bpftool/main.h +++ b/tools/bpf/bpftool/main.h @@ -55,6 +55,8 @@ #define HELP_SPEC_PROGRAM \ "PROG := { id PROG_ID | pinned FILE | tag PROG_TAG }" +#define HELP_SPEC_OPTIONS \ + "OPTIONS := { {-j|--json} [{-p|--pretty}] }" enum bpf_obj_type { BPF_OBJ_UNKNOWN, diff --git a/tools/bpf/bpftool/map.c b/tools/bpf/bpftool/map.c index a611f31..e978ab2 100644 --- a/tools/bpf/bpftool/map.c +++ b/tools/bpf/bpftool/map.c @@ -850,6 +850,7 @@ static int do_help(int argc, char **argv) " " HELP_SPEC_PROGRAM "\n" " VALUE := { BYTES | MAP | PROG }\n" " UPDATE_FLAGS := { any | exist | noexist }\n" + " " HELP_SPEC_OPTIONS "\n" "", bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2], diff --git a/tools/bpf/bpftool/prog.c b/tools/bpf/bpftool/prog.c index e07f35f..250f80f 100644 --- a/tools/bpf/bpftool/prog.c +++ b/tools/bpf/bpftool/prog.c @@ -625,6 +625,7 @@ static int do_help(int argc, char **argv) " %s %s help\n" "\n" " " HELP_SPEC_PROGRAM "\n" + " " HELP_SPEC_OPTIONS "\n" "", bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2], bin_name, argv[-2]); -- 2.7.4