blob: 2dbc1413fabd8caa116ffff4df999d3ec0c4dece [file] [log] [blame]
Andrii Nakryikoca253332019-04-25 15:30:09 -07001================
2bpftool-btf
3================
4-------------------------------------------------------------------------------
5tool for inspection of BTF data
6-------------------------------------------------------------------------------
7
8:Manual section: 8
9
10SYNOPSIS
11========
12
13 **bpftool** [*OPTIONS*] **btf** *COMMAND*
14
15 *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
16
17 *COMMANDS* := { **dump** | **help** }
18
19BTF 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
29DESCRIPTION
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
55OPTIONS
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
70EXAMPLES
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
83This 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
167The following commands print BTF types associated with specified map's key,
168value, both key and value, and all BTF types, respectively. By default, both
169key 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
200All 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
212SEE 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)