1BPFTOOL-BTF(8) BPFTOOL-BTF(8)
2
6 bpftool-btf - tool for inspection of BTF data
7
9 bpftool [OPTIONS] btf COMMAND
10 OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug }
12 | { -l | --legacy } | { -B | --base-btf } }
13 COMMANDS := { dump | help }
15
17 bpftool btf { show | list } [id BTF_ID]
18 bpftool btf dump BTF_SRC [format FORMAT]
19 bpftool btf help
20 BTF_SRC := { id BTF_ID | prog PROG | map MAP [{key | value | kv | all}] | file FILE }
22 FORMAT := { raw | c }
23 MAP := { id MAP_ID | pinned FILE }
24 PROG := { id PROG_ID | pinned FILE | tag PROG_TAG }
25
28 bpftool btf { show | list } [id BTF_ID]
29 Show information about loaded BTF objects. If a BTF ID is
30 specified, show information only about given BTF object, oth‐
31 erwise list all BTF objects currently loaded on the system.
32 Since Linux 5.8 bpftool is able to discover information about
34 processes that hold open file descriptors (FDs) against BTF
35 objects. On such kernels bpftool will automatically emit this
36 information as well.
37 bpftool btf dump BTF_SRC
39 Dump BTF entries from a given BTF_SRC.
40 When id is specified, BTF object with that ID will be loaded
42 and all its BTF types emitted.
43 When map is provided, it's expected that map has associated
45 BTF object with BTF types describing key and value. It's pos‐
46 sible to select whether to dump only BTF type(s) associated
47 with key (key), value (value), both key and value (kv), or
48 all BTF types present in associated BTF object (all). If not
49 specified, kv is assumed.
50 When prog is provided, it's expected that program has associ‐
52 ated BTF object with BTF types.
53 When specifying FILE, an ELF file is expected, containing
55 .BTF section with well-defined BTF binary format data, typi‐
56 cally produced by clang or pahole.
57 format option can be used to override default (raw) output
59 format. Raw (raw) or C-syntax (c) output formats are sup‐
60 ported.
61 bpftool btf help
63 Print short help message.
64
66 -h, --help
67 Print short help message (similar to bpftool help).
68 -V, --version
70 Print bpftool's version number (similar to bpftool version),
71 the number of the libbpf version in use, and optional fea‐
72 tures that were included when bpftool was compiled. Optional
73 features include linking against libbfd to provide the disas‐
74 sembler for JIT-ted programs (bpftool prog dump jited) and
75 usage of BPF skeletons (some features like bpftool prog pro‐
76 file or showing pids associated to BPF objects may rely on
77 it).
78 -j, --json
80 Generate JSON output. For commands that cannot produce JSON,
81 this option has no effect.
82 -p, --pretty
84 Generate human-readable JSON output. Implies -j.
85 -d, --debug
87 Print all logs available, even debug-level information. This
88 includes logs from libbpf as well as from the verifier, when
89 attempting to load programs.
90 -l, --legacy
92 Use legacy libbpf mode which has more relaxed BPF program re‐
93 quirements. By default, bpftool has more strict requirements
94 about section names, changes pinning logic and doesn't sup‐
95 port some of the older non-BTF map declarations.
96 See
98 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
99 for details.
100 -B, --base-btf FILE
102 Pass a base BTF object. Base BTF objects are typically used
103 with BTF objects for kernel modules. To avoid duplicating all
104 kernel symbols required by modules, BTF objects for modules
105 are "split", they are built incrementally on top of the ker‐
106 nel (vmlinux) BTF object. So the base BTF reference should
107 usually point to the kernel BTF.
108 When the main BTF object to process (for example, the module
110 BTF to dump) is passed as a FILE, bpftool attempts to autode‐
111 tect the path for the base object, and passing this option is
112 optional. When the main BTF object is passed through other
113 handles, this option becomes necessary.
114
116 # bpftool btf dump id 1226
117 [1] PTR '(anon)' type_id=2
119 [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
120 'pad' type_id=3 bits_offset=0
121 'sock' type_id=4 bits_offset=64
122 [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
123 [4] PTR '(anon)' type_id=5
124 [5] FWD 'sock' fwd_kind=union
125 This gives an example of default output for all supported BTF kinds.
127 $ cat prog.c
129 struct fwd_struct;
131 enum my_enum {
133 VAL1 = 3,
134 VAL2 = 7,
135 };
136 typedef struct my_struct my_struct_t;
138 struct my_struct {
140 const unsigned int const_int_field;
141 int bitfield_field: 4;
142 char arr_field[16];
143 const struct fwd_struct *restrict fwd_field;
144 enum my_enum enum_field;
145 volatile my_struct_t *typedef_ptr_field;
146 };
147 union my_union {
149 int a;
150 struct my_struct b;
151 };
152 struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
154 .bitfield_field = 3,
155 .enum_field = VAL1,
156 };
157 int global_var __attribute__((section("data_sec"))) = 7;
158 __attribute__((noinline))
160 int my_func(union my_union *arg1, int arg2)
161 {
162 static int static_var __attribute__((section("data_sec"))) = 123;
163 static_var++;
164 return static_var;
165 }
166 $ bpftool btf dump file prog.o
168 [1] PTR '(anon)' type_id=2
170 [2] UNION 'my_union' size=48 vlen=2
171 'a' type_id=3 bits_offset=0
172 'b' type_id=4 bits_offset=0
173 [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
174 [4] STRUCT 'my_struct' size=48 vlen=6
175 'const_int_field' type_id=5 bits_offset=0
176 'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
177 'arr_field' type_id=8 bits_offset=40
178 'fwd_field' type_id=10 bits_offset=192
179 'enum_field' type_id=14 bits_offset=256
180 'typedef_ptr_field' type_id=15 bits_offset=320
181 [5] CONST '(anon)' type_id=6
182 [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
183 [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
184 [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
185 [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
186 [10] RESTRICT '(anon)' type_id=11
187 [11] PTR '(anon)' type_id=12
188 [12] CONST '(anon)' type_id=13
189 [13] FWD 'fwd_struct' fwd_kind=union
190 [14] ENUM 'my_enum' size=4 vlen=2
191 'VAL1' val=3
192 'VAL2' val=7
193 [15] PTR '(anon)' type_id=16
194 [16] VOLATILE '(anon)' type_id=17
195 [17] TYPEDEF 'my_struct_t' type_id=4
196 [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
197 'arg1' type_id=1
198 'arg2' type_id=3
199 [19] FUNC 'my_func' type_id=18
200 [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
201 [21] VAR 'global_var' type_id=3, linkage=global-alloc
202 [22] VAR 'my_func.static_var' type_id=3, linkage=static
203 [23] DATASEC 'data_sec' size=0 vlen=3
204 type_id=20 offset=0 size=48
205 type_id=21 offset=0 size=4
206 type_id=22 offset=52 size=4
207 The following commands print BTF types associated with specified map's
209 key, value, both key and value, and all BTF types, respectively. By de‐
210 fault, both key and value types will be printed.
211 # bpftool btf dump map id 123 key
213 [39] TYPEDEF 'u32' type_id=37
215 # bpftool btf dump map id 123 value
217 [86] PTR '(anon)' type_id=87
219 # bpftool btf dump map id 123 kv
221 [39] TYPEDEF 'u32' type_id=37
223 [86] PTR '(anon)' type_id=87
224 # bpftool btf dump map id 123 all
226 [1] PTR '(anon)' type_id=0
228 .
229 .
230 .
231 [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
232 All the standard ways to specify map or program are supported:
234 # bpftool btf dump map id 123
236 # bpftool btf dump map pinned /sys/fs/bpf/map_name
238 # bpftool btf dump prog id 456
240 # bpftool btf dump prog tag b88e0a09b1d9759d
242 # bpftool btf dump prog pinned /sys/fs/bpf/prog_name
244 # bpftool btf dump file /sys/kernel/btf/i2c_smbus
246 (or)
247 # I2C_SMBUS_ID=$(bpftool btf show -p | jq '.[] | select(.name=="i2c_smbus").id')
248 # bpftool btf dump id ${I2C_SMBUS_ID} -B /sys/kernel/btf/vmlinux
249 [104848] STRUCT 'i2c_smbus_alert' size=40 vlen=2
252 'alert' type_id=393 bits_offset=0
253 'ara' type_id=56050 bits_offset=256
254 [104849] STRUCT 'alert_data' size=12 vlen=3
255 'addr' type_id=16 bits_offset=0
256 'type' type_id=56053 bits_offset=32
257 'data' type_id=7 bits_offset=64
258 [104850] PTR '(anon)' type_id=104848
259 [104851] PTR '(anon)' type_id=104849
260 [104852] FUNC 'i2c_register_spd' type_id=84745 linkage=static
261 [104853] FUNC 'smbalert_driver_init' type_id=1213 linkage=static
262 [104854] FUNC_PROTO '(anon)' ret_type_id=18 vlen=1
263 'ara' type_id=56050
264 [104855] FUNC 'i2c_handle_smbus_alert' type_id=104854 linkage=static
265 [104856] FUNC 'smbalert_remove' type_id=104854 linkage=static
266 [104857] FUNC_PROTO '(anon)' ret_type_id=18 vlen=2
267 'ara' type_id=56050
268 'id' type_id=56056
269 [104858] FUNC 'smbalert_probe' type_id=104857 linkage=static
270 [104859] FUNC 'smbalert_work' type_id=9695 linkage=static
271 [104860] FUNC 'smbus_alert' type_id=71367 linkage=static
272 [104861] FUNC 'smbus_do_alert' type_id=84827 linkage=static
273
275 bpf(2), bpf-helpers(7), bpftool(8), bpftool-cgroup(8), bpftool-fea‐
276 ture(8), bpftool-gen(8), bpftool-iter(8), bpftool-link(8),
277 bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-prog(8),
278 bpftool-struct_ops(8)
279 BPFTOOL-BTF(8)