bpftool/docs: add btf sub-command documentation

Document usage and sample output format for `btf dump` sub-command.

Cc: Daniel Borkmann <daniel@iogearbox.net>
Cc: Alexei Starovoitov <ast@fb.com>
Cc: Yonghong Song <yhs@fb.com>
Cc: Martin KaFai Lau <kafai@fb.com>
Cc: Song Liu <songliubraving@fb.com>
Cc: Arnaldo Carvalho de Melo <acme@redhat.com>
Acked-by: Yonghong Song <yhs@fb.com>
Signed-off-by: Andrii Nakryiko <andriin@fb.com>
Signed-off-by: Alexei Starovoitov <ast@kernel.org>

8 files changed, 236 insertions, 7 deletions

diff --git a/tools/bpf/bpftool/Documentation/bpftool-btf.rst b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
new file mode 100644
index 000000000000..2dbc1413fabd
--- /dev/null
+++ b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
@@ -0,0 +1,222 @@
+================
+bpftool-btf
+================
+-------------------------------------------------------------------------------
+tool for inspection of BTF data
+-------------------------------------------------------------------------------
+
+:Manual section: 8
+
+SYNOPSIS
+========
+
+        **bpftool** [*OPTIONS*] **btf** *COMMAND*
+
+        *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
+
+        *COMMANDS* := { **dump** | **help** }
+
+BTF 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 btf dump** *BTF_SRC*
+                  Dump BTF entries from a given *BTF_SRC*.
+
+                  When **id** is specified, BTF object with that ID will be
+                  loaded and all its BTF types emitted.
+
+                  When **map** is provided, it's expected that map has
+                  associated BTF object with BTF types describing key and
+                  value. It's possible to select whether to dump only BTF
+                  type(s) associated with key (**key**), value (**value**),
+                  both key and value (**kv**), or all BTF types present in
+                  associated BTF object (**all**). If not specified, **kv**
+                  is assumed.
+
+                  When **prog** is provided, it's expected that program has
+                  associated BTF object with BTF types.
+
+                  When specifying *FILE*, an ELF file is expected, containing
+                  .BTF section with well-defined BTF binary format data,
+                  typically produced by clang or pahole.
+
+        **bpftool btf 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 are 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)