On Wed, Apr 24, 2019 at 10:21 AM Yonghong Song <yhs@xxxxxx> wrote:
>
>
>
> On 4/23/19 10:22 PM, andrii.nakryiko@xxxxxxxxx wrote:
> > From: Andrii Nakryiko <andriin@xxxxxx>
> >
> > Document usage and sample output format for `btf dump` sub-command.
>
> When applying the patch, I see a few trailing spaces.
>
> ===
> p2.txt:113: trailing whitespace.
>
> p2.txt:118: trailing whitespace.
>
> p2.txt:120: trailing whitespace.
>
> p2.txt:129: trailing whitespace.
>
> p2.txt:134: trailing whitespace.
> ===
>
> You may want to take a look.
I assumed they are necessary for single code block in ReST. But I just
tried to remove them and it seems the resulting generated man page
looks the same, so I'll remove them.
>
> Could you add bash completion as well?
Yeah, sure, I'll add it as third patch in v2.
>
> >
> > Cc: Daniel Borkmann <daniel@xxxxxxxxxxxxx>
> > Cc: Alexei Starovoitov <ast@xxxxxx>
> > Cc: Yonghong Song <yhs@xxxxxx>
> > Cc: Martin KaFai Lau <kafai@xxxxxx>
> > Cc: Song Liu <songliubraving@xxxxxx>
> > Cc: Arnaldo Carvalho de Melo <acme@xxxxxxxxxx>
> > Signed-off-by: Andrii Nakryiko <andriin@xxxxxx>
> > ---
> > .../bpf/bpftool/Documentation/bpftool-btf.rst | 205 ++++++++++++++++++
> > .../bpftool/Documentation/bpftool-cgroup.rst | 3 +-
> > .../bpftool/Documentation/bpftool-feature.rst | 3 +-
> > .../bpf/bpftool/Documentation/bpftool-map.rst | 3 +-
> > .../bpf/bpftool/Documentation/bpftool-net.rst | 3 +-
> > .../bpftool/Documentation/bpftool-perf.rst | 3 +-
> > .../bpftool/Documentation/bpftool-prog.rst | 3 +-
> > tools/bpf/bpftool/Documentation/bpftool.rst | 3 +-
> > 8 files changed, 219 insertions(+), 7 deletions(-)
> > create mode 100644 tools/bpf/bpftool/Documentation/bpftool-btf.rst
> >
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-btf.rst b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
> > new file mode 100644
> > index 000000000000..955aaaba93a0
> > --- /dev/null
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
> > @@ -0,0 +1,205 @@
> > +================
> > +bpftool-btf
> > +================
> > +-------------------------------------------------------------------------------
> > +tool for inspection of BTF data
> > +-------------------------------------------------------------------------------
> > +
> > +:Manual section: 8
> > +
> > +SYNOPSIS
> > +========
> > +
> > + **bpftool** [*OPTIONS*] **btf** *COMMAND*
> > +
> > + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
> > +
> > + *COMMANDS* :=
> > + { **dump** | **help** }
> > +
> > +MAP COMMANDS
> > +=============
> > +
> > +| **bpftool** **btf dump** *BTF_SRC*
> > +| **bpftool** **btf help**
> > +|
> > +| *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
> > +| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
> > +| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
> > +
> > +DESCRIPTION
> > +===========
> > + **bpftool map dump** *MAP*
> > + Dump BTF entries from a given *BTF_SRC*.
> > +
> > + **bpftool map help**
> > + Print short help message.
> > +
> > +OPTIONS
> > +=======
> > + -h, --help
> > + Print short generic help message (similar to **bpftool help**).
> > +
> > + -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 btf dump id 1226**
> > +::
> > +
> > + [1] PTR '(anon)' type_id=2
> > + [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
> > + 'pad' type_id=3 bits_offset=0
> > + 'sock' type_id=4 bits_offset=64
> > + [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
> > + [4] PTR '(anon)' type_id=5
> > + [5] FWD 'sock' fwd_kind=union
> > +
> > +This gives an example of default output for all supported BTF kinds.
> > +
> > +**$ cat prog.c**
> > +::
> > +
> > + struct fwd_struct;
> > +
> > + enum my_enum {
> > + VAL1 = 3,
> > + VAL2 = 7,
> > + };
> > +
> > + typedef struct my_struct my_struct_t;
> > +
> > + struct my_struct {
> > + const unsigned int const_int_field;
> > + int bitfield_field: 4;
> > + char arr_field[16];
> > + const struct fwd_struct *restrict fwd_field;
> > + enum my_enum enum_field;
> > + volatile my_struct_t *typedef_ptr_field;
> > + };
> > +
> > + union my_union {
> > + int a;
> > + struct my_struct b;
> > + };
> > +
> > + struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
> > + .bitfield_field = 3,
> > + .enum_field = VAL1,
> > + };
> > + int global_var __attribute__((section("data_sec"))) = 7;
> > +
> > + __attribute__((noinline))
> > + int my_func(union my_union *arg1, int arg2)
> > + {
> > + static int static_var __attribute__((section("data_sec"))) = 123;
> > + static_var++;
> > + return static_var;
> > + }
> > +
> > +**$ bpftool btf dump file prog.o**
> > +::
> > +
> > + [1] PTR '(anon)' type_id=2
> > + [2] UNION 'my_union' size=48 vlen=2
> > + 'a' type_id=3 bits_offset=0
> > + 'b' type_id=4 bits_offset=0
> > + [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
> > + [4] STRUCT 'my_struct' size=48 vlen=6
> > + 'const_int_field' type_id=5 bits_offset=0
> > + 'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
> > + 'arr_field' type_id=8 bits_offset=40
> > + 'fwd_field' type_id=10 bits_offset=192
> > + 'enum_field' type_id=14 bits_offset=256
> > + 'typedef_ptr_field' type_id=15 bits_offset=320
> > + [5] CONST '(anon)' type_id=6
> > + [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
> > + [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
> > + [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
> > + [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
> > + [10] RESTRICT '(anon)' type_id=11
> > + [11] PTR '(anon)' type_id=12
> > + [12] CONST '(anon)' type_id=13
> > + [13] FWD 'fwd_struct' fwd_kind=union
> > + [14] ENUM 'my_enum' size=4 vlen=2
> > + 'VAL1' val=3
> > + 'VAL2' val=7
> > + [15] PTR '(anon)' type_id=16
> > + [16] VOLATILE '(anon)' type_id=17
> > + [17] TYPEDEF 'my_struct_t' type_id=4
> > + [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
> > + 'arg1' type_id=1
> > + 'arg2' type_id=3
> > + [19] FUNC 'my_func' type_id=18
> > + [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
> > + [21] VAR 'global_var' type_id=3, linkage=global-alloc
> > + [22] VAR 'my_func.static_var' type_id=3, linkage=static
> > + [23] DATASEC 'data_sec' size=0 vlen=3
> > + type_id=20 offset=0 size=48
> > + type_id=21 offset=0 size=4
> > + type_id=22 offset=52 size=4
> > +
> > +The following commands print BTF types associated with specified map's key,
> > +value, both key and value, and all BTF types, respectively. By default, both
> > +key and value types will be printed.
> > +
> > +**# bpftool btf dump map id 123 key**
> > +
> > +::
> > +
> > + [39] TYPEDEF 'u32' type_id=37
> > +
> > +**# bpftool btf dump map id 123 value**
> > +
> > +::
> > +
> > + [86] PTR '(anon)' type_id=87
> > +
> > +**# bpftool btf dump map id 123 kv**
> > +
> > +::
> > +
> > + [39] TYPEDEF 'u32' type_id=37
> > + [86] PTR '(anon)' type_id=87
> > +
> > +**# bpftool btf dump map id 123 all**
> > +
> > +::
> > +
> > + [1] PTR '(anon)' type_id=0
> > + .
> > + .
> > + .
> > + [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
> > +
> > +All the standard ways to specify map or program is supported:
> > +
> > +**# bpftool btf dump map id 123**
> > +
> > +**# bpftool btf dump map pinned /sys/fs/bpf/map_name**
> > +
> > +**# bpftool btf dump prog id 456**
> > +
> > +**# bpftool btf dump prog tag b88e0a09b1d9759d**
> > +
> > +**# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
> > +
> > +SEE ALSO
> > +========
> > + **bpf**\ (2),
> > + **bpf-helpers**\ (7),
> > + **bpftool**\ (8),
> > + **bpftool-map**\ (8),
> > + **bpftool-prog**\ (8),
> > + **bpftool-cgroup**\ (8),
> > + **bpftool-feature**\ (8),
> > + **bpftool-net**\ (8),
> > + **bpftool-perf**\ (8)
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
> > index 89b6b10e2183..ac26876389c2 100644
> > --- a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
> > @@ -145,4 +145,5 @@ SEE ALSO
> > **bpftool-map**\ (8),
> > **bpftool-feature**\ (8),
> > **bpftool-net**\ (8),
> > - **bpftool-perf**\ (8)
> > + **bpftool-perf**\ (8),
> > + **bpftool-btf**\ (8)
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-feature.rst b/tools/bpf/bpftool/Documentation/bpftool-feature.rst
> > index 10177343b7ce..14180e887082 100644
> > --- a/tools/bpf/bpftool/Documentation/bpftool-feature.rst
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-feature.rst
> > @@ -82,4 +82,5 @@ SEE ALSO
> > **bpftool-map**\ (8),
> > **bpftool-cgroup**\ (8),
> > **bpftool-net**\ (8),
> > - **bpftool-perf**\ (8)
> > + **bpftool-perf**\ (8),
> > + **bpftool-btf**\ (8)
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-map.rst b/tools/bpf/bpftool/Documentation/bpftool-map.rst
> > index 55ecf80ca03e..13ef27b39f20 100644
> > --- a/tools/bpf/bpftool/Documentation/bpftool-map.rst
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-map.rst
> > @@ -258,4 +258,5 @@ SEE ALSO
> > **bpftool-cgroup**\ (8),
> > **bpftool-feature**\ (8),
> > **bpftool-net**\ (8),
> > - **bpftool-perf**\ (8)
> > + **bpftool-perf**\ (8),
> > + **bpftool-btf**\ (8)
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-net.rst b/tools/bpf/bpftool/Documentation/bpftool-net.rst
> > index 6b692b428373..934580850f42 100644
> > --- a/tools/bpf/bpftool/Documentation/bpftool-net.rst
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-net.rst
> > @@ -143,4 +143,5 @@ SEE ALSO
> > **bpftool-map**\ (8),
> > **bpftool-cgroup**\ (8),
> > **bpftool-feature**\ (8),
> > - **bpftool-perf**\ (8)
> > + **bpftool-perf**\ (8),
> > + **bpftool-btf**\ (8)
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-perf.rst b/tools/bpf/bpftool/Documentation/bpftool-perf.rst
> > index 86154740fabb..0c7576523a21 100644
> > --- a/tools/bpf/bpftool/Documentation/bpftool-perf.rst
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-perf.rst
> > @@ -85,4 +85,5 @@ SEE ALSO
> > **bpftool-map**\ (8),
> > **bpftool-cgroup**\ (8),
> > **bpftool-feature**\ (8),
> > - **bpftool-net**\ (8)
> > + **bpftool-net**\ (8),
> > + **bpftool-btf**\ (8)
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-prog.rst b/tools/bpf/bpftool/Documentation/bpftool-prog.rst
> > index 2f183ffd8351..e8118544d118 100644
> > --- a/tools/bpf/bpftool/Documentation/bpftool-prog.rst
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-prog.rst
> > @@ -271,4 +271,5 @@ SEE ALSO
> > **bpftool-cgroup**\ (8),
> > **bpftool-feature**\ (8),
> > **bpftool-net**\ (8),
> > - **bpftool-perf**\ (8)
> > + **bpftool-perf**\ (8),
> > + **bpftool-btf**\ (8)
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool.rst b/tools/bpf/bpftool/Documentation/bpftool.rst
> > index deb2ca911ddf..3e562d7fd56f 100644
> > --- a/tools/bpf/bpftool/Documentation/bpftool.rst
> > +++ b/tools/bpf/bpftool/Documentation/bpftool.rst
> > @@ -76,4 +76,5 @@ SEE ALSO
> > **bpftool-cgroup**\ (8),
> > **bpftool-feature**\ (8),
> > **bpftool-net**\ (8),
> > - **bpftool-perf**\ (8)
> > + **bpftool-perf**\ (8),
> > + **bpftool-btf**\ (8)
> >
