Commit 0c0cad2c authored by Alexei Starovoitov's avatar Alexei Starovoitov
Browse files

Merge branch 'btf-dump' 



Andrii Nakryiko says:

====================
This patch set adds a new `bpftool btf dump` sub-command, which allows to dump
BTF contents (only types for now). Currently it only outputs low-level
content, almost 1:1 with binary BTF format, but follow up patches will add
ability to dump BTF types as a compilable C header file. JSON output is
supported as well.

Patch #1 adds `btf` sub-command, dumping BTF types in human-readable format.
It also implements reading .BTF data from ELF file.
Patch #2 adds minimal documentation with output format examples and different
ways to specify source of BTF data.
Patch #3 adds support for btf command in bash-completion/bpftool script.
Patch #4 fixes minor indentation issue in bash-completion script.

Output format is mostly following existing format of BPF verifier log, but
deviates from it in few places. More details are in commit message for patch 1.

Example of output for all supported BTF kinds are in patch #2 as part of
documentation. Some field names are quite verbose and I'd rather shorten them,
if we don't feel like being very close to BPF verifier names is a necessity,
but in this patch I left them exactly the same as in verifier log.

v3->v4:
  - reverse Christmas tree (Quentin)
  - better docs (Quentin)

v2->v3:
  - make map's key|value|kv|all suggestion more precise (Quentin)
  - fix default case indentations (Quentin)

v1->v2:
  - fix unnecessary trailing whitespaces in bpftool-btf.rst (Yonghong)
  - add btf in main.c for a list of possible OBJECTs
  - handle unknown keyword under `bpftool btf dump` (Yonghong)
====================

Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parents 77d76426 8ed1875b

tools/bpf/bpftool/Documentation/bpftool-btf.rst

0 → 100644
+222 −0
Original line number Diff line number Diff line 
================

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)

tools/bpf/bpftool/Documentation/bpftool-cgroup.rst

+2 −1
Original line number Diff line number Diff line
@@ -145,4 +145,5 @@ SEE ALSO 
	**bpftool-map**\ (8),

	**bpftool-feature**\ (8),

	**bpftool-net**\ (8),

	**bpftool-perf**\ (8)
 
	**bpftool-perf**\ (8),

	**bpftool-btf**\ (8)

tools/bpf/bpftool/Documentation/bpftool-feature.rst

+2 −1
Original line number Diff line number Diff line
@@ -82,4 +82,5 @@ SEE ALSO 
	**bpftool-map**\ (8),

	**bpftool-cgroup**\ (8),

	**bpftool-net**\ (8),

	**bpftool-perf**\ (8)
 
	**bpftool-perf**\ (8),

	**bpftool-btf**\ (8)

tools/bpf/bpftool/Documentation/bpftool-map.rst

+2 −1
Original line number Diff line number Diff line
@@ -258,4 +258,5 @@ SEE ALSO 
	**bpftool-cgroup**\ (8),

	**bpftool-feature**\ (8),

	**bpftool-net**\ (8),

	**bpftool-perf**\ (8)
 
	**bpftool-perf**\ (8),

	**bpftool-btf**\ (8)

tools/bpf/bpftool/Documentation/bpftool-net.rst

+2 −1
Original line number Diff line number Diff line
@@ -143,4 +143,5 @@ SEE ALSO 
	**bpftool-map**\ (8),

	**bpftool-cgroup**\ (8),

	**bpftool-feature**\ (8),

	**bpftool-perf**\ (8)
 
	**bpftool-perf**\ (8),

	**bpftool-btf**\ (8)

CRA Git | Maintained and supported by SUSTech CRA and CCSE