Andrii Nakryiko | ca25333 | 2019-04-25 15:30:09 -0700 | [diff] [blame] | 1 | ================ |
| 2 | bpftool-btf |
| 3 | ================ |
| 4 | ------------------------------------------------------------------------------- |
| 5 | tool for inspection of BTF data |
| 6 | ------------------------------------------------------------------------------- |
| 7 | |
| 8 | :Manual section: 8 |
| 9 | |
| 10 | SYNOPSIS |
| 11 | ======== |
| 12 | |
| 13 | **bpftool** [*OPTIONS*] **btf** *COMMAND* |
| 14 | |
| 15 | *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } |
| 16 | |
| 17 | *COMMANDS* := { **dump** | **help** } |
| 18 | |
| 19 | BTF COMMANDS |
| 20 | ============= |
| 21 | |
| 22 | | **bpftool** **btf dump** *BTF_SRC* |
| 23 | | **bpftool** **btf help** |
| 24 | | |
| 25 | | *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* } |
| 26 | | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } |
| 27 | | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } |
| 28 | |
| 29 | DESCRIPTION |
| 30 | =========== |
| 31 | **bpftool btf dump** *BTF_SRC* |
| 32 | Dump BTF entries from a given *BTF_SRC*. |
| 33 | |
| 34 | When **id** is specified, BTF object with that ID will be |
| 35 | loaded and all its BTF types emitted. |
| 36 | |
| 37 | When **map** is provided, it's expected that map has |
| 38 | associated BTF object with BTF types describing key and |
| 39 | value. It's possible to select whether to dump only BTF |
| 40 | type(s) associated with key (**key**), value (**value**), |
| 41 | both key and value (**kv**), or all BTF types present in |
| 42 | associated BTF object (**all**). If not specified, **kv** |
| 43 | is assumed. |
| 44 | |
| 45 | When **prog** is provided, it's expected that program has |
| 46 | associated BTF object with BTF types. |
| 47 | |
| 48 | When specifying *FILE*, an ELF file is expected, containing |
| 49 | .BTF section with well-defined BTF binary format data, |
| 50 | typically produced by clang or pahole. |
| 51 | |
| 52 | **bpftool btf help** |
| 53 | Print short help message. |
| 54 | |
| 55 | OPTIONS |
| 56 | ======= |
| 57 | -h, --help |
| 58 | Print short generic help message (similar to **bpftool help**). |
| 59 | |
| 60 | -V, --version |
| 61 | Print version number (similar to **bpftool version**). |
| 62 | |
| 63 | -j, --json |
| 64 | Generate JSON output. For commands that cannot produce JSON, this |
| 65 | option has no effect. |
| 66 | |
| 67 | -p, --pretty |
| 68 | Generate human-readable JSON output. Implies **-j**. |
| 69 | |
| 70 | EXAMPLES |
| 71 | ======== |
| 72 | **# bpftool btf dump id 1226** |
| 73 | :: |
| 74 | |
| 75 | [1] PTR '(anon)' type_id=2 |
| 76 | [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2 |
| 77 | 'pad' type_id=3 bits_offset=0 |
| 78 | 'sock' type_id=4 bits_offset=64 |
| 79 | [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none) |
| 80 | [4] PTR '(anon)' type_id=5 |
| 81 | [5] FWD 'sock' fwd_kind=union |
| 82 | |
| 83 | This gives an example of default output for all supported BTF kinds. |
| 84 | |
| 85 | **$ cat prog.c** |
| 86 | :: |
| 87 | |
| 88 | struct fwd_struct; |
| 89 | |
| 90 | enum my_enum { |
| 91 | VAL1 = 3, |
| 92 | VAL2 = 7, |
| 93 | }; |
| 94 | |
| 95 | typedef struct my_struct my_struct_t; |
| 96 | |
| 97 | struct my_struct { |
| 98 | const unsigned int const_int_field; |
| 99 | int bitfield_field: 4; |
| 100 | char arr_field[16]; |
| 101 | const struct fwd_struct *restrict fwd_field; |
| 102 | enum my_enum enum_field; |
| 103 | volatile my_struct_t *typedef_ptr_field; |
| 104 | }; |
| 105 | |
| 106 | union my_union { |
| 107 | int a; |
| 108 | struct my_struct b; |
| 109 | }; |
| 110 | |
| 111 | struct my_struct struct_global_var __attribute__((section("data_sec"))) = { |
| 112 | .bitfield_field = 3, |
| 113 | .enum_field = VAL1, |
| 114 | }; |
| 115 | int global_var __attribute__((section("data_sec"))) = 7; |
| 116 | |
| 117 | __attribute__((noinline)) |
| 118 | int my_func(union my_union *arg1, int arg2) |
| 119 | { |
| 120 | static int static_var __attribute__((section("data_sec"))) = 123; |
| 121 | static_var++; |
| 122 | return static_var; |
| 123 | } |
| 124 | |
| 125 | **$ bpftool btf dump file prog.o** |
| 126 | :: |
| 127 | |
| 128 | [1] PTR '(anon)' type_id=2 |
| 129 | [2] UNION 'my_union' size=48 vlen=2 |
| 130 | 'a' type_id=3 bits_offset=0 |
| 131 | 'b' type_id=4 bits_offset=0 |
| 132 | [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED |
| 133 | [4] STRUCT 'my_struct' size=48 vlen=6 |
| 134 | 'const_int_field' type_id=5 bits_offset=0 |
| 135 | 'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4 |
| 136 | 'arr_field' type_id=8 bits_offset=40 |
| 137 | 'fwd_field' type_id=10 bits_offset=192 |
| 138 | 'enum_field' type_id=14 bits_offset=256 |
| 139 | 'typedef_ptr_field' type_id=15 bits_offset=320 |
| 140 | [5] CONST '(anon)' type_id=6 |
| 141 | [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none) |
| 142 | [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED |
| 143 | [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16 |
| 144 | [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none) |
| 145 | [10] RESTRICT '(anon)' type_id=11 |
| 146 | [11] PTR '(anon)' type_id=12 |
| 147 | [12] CONST '(anon)' type_id=13 |
| 148 | [13] FWD 'fwd_struct' fwd_kind=union |
| 149 | [14] ENUM 'my_enum' size=4 vlen=2 |
| 150 | 'VAL1' val=3 |
| 151 | 'VAL2' val=7 |
| 152 | [15] PTR '(anon)' type_id=16 |
| 153 | [16] VOLATILE '(anon)' type_id=17 |
| 154 | [17] TYPEDEF 'my_struct_t' type_id=4 |
| 155 | [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2 |
| 156 | 'arg1' type_id=1 |
| 157 | 'arg2' type_id=3 |
| 158 | [19] FUNC 'my_func' type_id=18 |
| 159 | [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc |
| 160 | [21] VAR 'global_var' type_id=3, linkage=global-alloc |
| 161 | [22] VAR 'my_func.static_var' type_id=3, linkage=static |
| 162 | [23] DATASEC 'data_sec' size=0 vlen=3 |
| 163 | type_id=20 offset=0 size=48 |
| 164 | type_id=21 offset=0 size=4 |
| 165 | type_id=22 offset=52 size=4 |
| 166 | |
| 167 | The following commands print BTF types associated with specified map's key, |
| 168 | value, both key and value, and all BTF types, respectively. By default, both |
| 169 | key and value types will be printed. |
| 170 | |
| 171 | **# bpftool btf dump map id 123 key** |
| 172 | |
| 173 | :: |
| 174 | |
| 175 | [39] TYPEDEF 'u32' type_id=37 |
| 176 | |
| 177 | **# bpftool btf dump map id 123 value** |
| 178 | |
| 179 | :: |
| 180 | |
| 181 | [86] PTR '(anon)' type_id=87 |
| 182 | |
| 183 | **# bpftool btf dump map id 123 kv** |
| 184 | |
| 185 | :: |
| 186 | |
| 187 | [39] TYPEDEF 'u32' type_id=37 |
| 188 | [86] PTR '(anon)' type_id=87 |
| 189 | |
| 190 | **# bpftool btf dump map id 123 all** |
| 191 | |
| 192 | :: |
| 193 | |
| 194 | [1] PTR '(anon)' type_id=0 |
| 195 | . |
| 196 | . |
| 197 | . |
| 198 | [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4 |
| 199 | |
| 200 | All the standard ways to specify map or program are supported: |
| 201 | |
| 202 | **# bpftool btf dump map id 123** |
| 203 | |
| 204 | **# bpftool btf dump map pinned /sys/fs/bpf/map_name** |
| 205 | |
| 206 | **# bpftool btf dump prog id 456** |
| 207 | |
| 208 | **# bpftool btf dump prog tag b88e0a09b1d9759d** |
| 209 | |
| 210 | **# bpftool btf dump prog pinned /sys/fs/bpf/prog_name** |
| 211 | |
| 212 | SEE ALSO |
| 213 | ======== |
| 214 | **bpf**\ (2), |
| 215 | **bpf-helpers**\ (7), |
| 216 | **bpftool**\ (8), |
| 217 | **bpftool-map**\ (8), |
| 218 | **bpftool-prog**\ (8), |
| 219 | **bpftool-cgroup**\ (8), |
| 220 | **bpftool-feature**\ (8), |
| 221 | **bpftool-net**\ (8), |
| 222 | **bpftool-perf**\ (8) |