1 .. SPDX-License-Identifier: (GPL-2.0-only OR B 1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2 2
3 ================ 3 ================
4 bpftool-btf 4 bpftool-btf
5 ================ 5 ================
6 ---------------------------------------------- 6 -------------------------------------------------------------------------------
7 tool for inspection of BTF data 7 tool for inspection of BTF data
8 ---------------------------------------------- 8 -------------------------------------------------------------------------------
9 9
10 :Manual section: 8 10 :Manual section: 8
11 11
12 .. include:: substitutions.rst 12 .. include:: substitutions.rst
13 13
14 SYNOPSIS 14 SYNOPSIS
15 ======== 15 ========
16 16
17 **bpftool** [*OPTIONS*] **btf** *COMMAND* !! 17 **bpftool** [*OPTIONS*] **btf** *COMMAND*
18 18
19 *OPTIONS* := { |COMMON_OPTIONS| | { **-B** | * !! 19 *OPTIONS* := { |COMMON_OPTIONS| | { **-B** | **--base-btf** } }
20 20
21 *COMMANDS* := { **dump** | **help** } !! 21 *COMMANDS* := { **dump** | **help** }
22 22
23 BTF COMMANDS 23 BTF COMMANDS
24 ============= 24 =============
25 25
26 | **bpftool** **btf** { **show** | **list** } !! 26 | **bpftool** **btf** { **show** | **list** } [**id** *BTF_ID*]
27 | **bpftool** **btf dump** *BTF_SRC* [**format !! 27 | **bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*]
28 | **bpftool** **btf help** !! 28 | **bpftool** **btf help**
29 | 29 |
30 | *BTF_SRC* := { **id** *BTF_ID* | **prog** *P !! 30 | *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
31 | *FORMAT* := { **raw** | **c** [**unsorted**] !! 31 | *FORMAT* := { **raw** | **c** }
32 | *MAP* := { **id** *MAP_ID* | **pinned** *FIL !! 32 | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
33 | *PROG* := { **id** *PROG_ID* | **pinned** *F !! 33 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
34 34
35 DESCRIPTION 35 DESCRIPTION
36 =========== 36 ===========
37 bpftool btf { show | list } [id *BTF_ID*] !! 37 **bpftool btf { show | list }** [**id** *BTF_ID*]
38 Show information about loaded BTF objects. !! 38 Show information about loaded BTF objects. If a BTF ID is
39 information only about given BTF object, o !! 39 specified, show information only about given BTF object,
40 currently loaded on the system. !! 40 otherwise list all BTF objects currently loaded on the
41 !! 41 system.
42 Since Linux 5.8 bpftool is able to discove !! 42
43 that hold open file descriptors (FDs) agai !! 43 Since Linux 5.8 bpftool is able to discover information about
44 bpftool will automatically emit this infor !! 44 processes that hold open file descriptors (FDs) against BTF
45 !! 45 objects. On such kernels bpftool will automatically emit this
46 bpftool btf dump *BTF_SRC* !! 46 information as well.
47 Dump BTF entries from a given *BTF_SRC*. !! 47
48 !! 48 **bpftool btf dump** *BTF_SRC*
49 When **id** is specified, BTF object with !! 49 Dump BTF entries from a given *BTF_SRC*.
50 its BTF types emitted. !! 50
51 !! 51 When **id** is specified, BTF object with that ID will be
52 When **map** is provided, it's expected th !! 52 loaded and all its BTF types emitted.
53 with BTF types describing key and value. I !! 53
54 dump only BTF type(s) associated with key !! 54 When **map** is provided, it's expected that map has
55 both key and value (**kv**), or all BTF ty !! 55 associated BTF object with BTF types describing key and
56 object (**all**). If not specified, **kv** !! 56 value. It's possible to select whether to dump only BTF
57 !! 57 type(s) associated with key (**key**), value (**value**),
58 When **prog** is provided, it's expected t !! 58 both key and value (**kv**), or all BTF types present in
59 object with BTF types. !! 59 associated BTF object (**all**). If not specified, **kv**
60 !! 60 is assumed.
61 When specifying *FILE*, an ELF file is exp !! 61
62 with well-defined BTF binary format data, !! 62 When **prog** is provided, it's expected that program has
63 pahole. !! 63 associated BTF object with BTF types.
64 !! 64
65 **format** option can be used to override !! 65 When specifying *FILE*, an ELF file is expected, containing
66 (**raw**) or C-syntax (**c**) output forma !! 66 .BTF section with well-defined BTF binary format data,
67 formatting, the output is sorted by defaul !! 67 typically produced by clang or pahole.
68 to avoid sorting the output. !! 68
>> 69 **format** option can be used to override default (raw)
>> 70 output format. Raw (**raw**) or C-syntax (**c**) output
>> 71 formats are supported.
69 72
70 bpftool btf help !! 73 **bpftool btf help**
71 Print short help message. !! 74 Print short help message.
72 75
73 OPTIONS 76 OPTIONS
74 ======= 77 =======
75 .. include:: common_options.rst !! 78 .. include:: common_options.rst
76 79
77 -B, --base-btf *FILE* !! 80 -B, --base-btf *FILE*
78 Pass a base BTF object. Base BTF objects a !! 81 Pass a base BTF object. Base BTF objects are typically used
79 objects for kernel modules. To avoid dupli !! 82 with BTF objects for kernel modules. To avoid duplicating
80 required by modules, BTF objects for modul !! 83 all kernel symbols required by modules, BTF objects for
81 built incrementally on top of the kernel ( !! 84 modules are "split", they are built incrementally on top of
82 base BTF reference should usually point to !! 85 the kernel (vmlinux) BTF object. So the base BTF reference
83 !! 86 should usually point to the kernel BTF.
84 When the main BTF object to process (for e !! 87
85 dump) is passed as a *FILE*, bpftool attem !! 88 When the main BTF object to process (for example, the
86 for the base object, and passing this opti !! 89 module BTF to dump) is passed as a *FILE*, bpftool attempts
87 BTF object is passed through other handles !! 90 to autodetect the path for the base object, and passing
88 necessary. !! 91 this option is optional. When the main BTF object is passed
>> 92 through other handles, this option becomes necessary.
89 93
90 EXAMPLES 94 EXAMPLES
91 ======== 95 ========
92 **# bpftool btf dump id 1226** 96 **# bpftool btf dump id 1226**
93 97
94 :: 98 ::
95 99
96 [1] PTR '(anon)' type_id=2 100 [1] PTR '(anon)' type_id=2
97 [2] STRUCT 'dummy_tracepoint_args' size=16 v 101 [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
98 'pad' type_id=3 bits_offset=0 102 'pad' type_id=3 bits_offset=0
99 'sock' type_id=4 bits_offset=64 103 'sock' type_id=4 bits_offset=64
100 [3] INT 'long long unsigned int' size=8 bits 104 [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
101 [4] PTR '(anon)' type_id=5 105 [4] PTR '(anon)' type_id=5
102 [5] FWD 'sock' fwd_kind=union 106 [5] FWD 'sock' fwd_kind=union
103 107
104 This gives an example of default output for al 108 This gives an example of default output for all supported BTF kinds.
105 109
106 **$ cat prog.c** 110 **$ cat prog.c**
107 111
108 :: 112 ::
109 113
110 struct fwd_struct; 114 struct fwd_struct;
111 115
112 enum my_enum { 116 enum my_enum {
113 VAL1 = 3, 117 VAL1 = 3,
114 VAL2 = 7, 118 VAL2 = 7,
115 }; 119 };
116 120
117 typedef struct my_struct my_struct_t; 121 typedef struct my_struct my_struct_t;
118 122
119 struct my_struct { 123 struct my_struct {
120 const unsigned int const_int_field; 124 const unsigned int const_int_field;
121 int bitfield_field: 4; 125 int bitfield_field: 4;
122 char arr_field[16]; 126 char arr_field[16];
123 const struct fwd_struct *restrict fw 127 const struct fwd_struct *restrict fwd_field;
124 enum my_enum enum_field; 128 enum my_enum enum_field;
125 volatile my_struct_t *typedef_ptr_fi 129 volatile my_struct_t *typedef_ptr_field;
126 }; 130 };
127 131
128 union my_union { 132 union my_union {
129 int a; 133 int a;
130 struct my_struct b; 134 struct my_struct b;
131 }; 135 };
132 136
133 struct my_struct struct_global_var __attribu 137 struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
134 .bitfield_field = 3, 138 .bitfield_field = 3,
135 .enum_field = VAL1, 139 .enum_field = VAL1,
136 }; 140 };
137 int global_var __attribute__((section("data_ 141 int global_var __attribute__((section("data_sec"))) = 7;
138 142
139 __attribute__((noinline)) 143 __attribute__((noinline))
140 int my_func(union my_union *arg1, int arg2) 144 int my_func(union my_union *arg1, int arg2)
141 { 145 {
142 static int static_var __attribute__( 146 static int static_var __attribute__((section("data_sec"))) = 123;
143 static_var++; 147 static_var++;
144 return static_var; 148 return static_var;
145 } 149 }
146 150
147 **$ bpftool btf dump file prog.o** 151 **$ bpftool btf dump file prog.o**
148 152
149 :: 153 ::
150 154
151 [1] PTR '(anon)' type_id=2 155 [1] PTR '(anon)' type_id=2
152 [2] UNION 'my_union' size=48 vlen=2 156 [2] UNION 'my_union' size=48 vlen=2
153 'a' type_id=3 bits_offset=0 157 'a' type_id=3 bits_offset=0
154 'b' type_id=4 bits_offset=0 158 'b' type_id=4 bits_offset=0
155 [3] INT 'int' size=4 bits_offset=0 nr_bits=3 159 [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
156 [4] STRUCT 'my_struct' size=48 vlen=6 160 [4] STRUCT 'my_struct' size=48 vlen=6
157 'const_int_field' type_id=5 bits_off 161 'const_int_field' type_id=5 bits_offset=0
158 'bitfield_field' type_id=3 bits_offs 162 'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
159 'arr_field' type_id=8 bits_offset=40 163 'arr_field' type_id=8 bits_offset=40
160 'fwd_field' type_id=10 bits_offset=1 164 'fwd_field' type_id=10 bits_offset=192
161 'enum_field' type_id=14 bits_offset= 165 'enum_field' type_id=14 bits_offset=256
162 'typedef_ptr_field' type_id=15 bits_ 166 'typedef_ptr_field' type_id=15 bits_offset=320
163 [5] CONST '(anon)' type_id=6 167 [5] CONST '(anon)' type_id=6
164 [6] INT 'unsigned int' size=4 bits_offset=0 168 [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
165 [7] INT 'char' size=1 bits_offset=0 nr_bits= 169 [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
166 [8] ARRAY '(anon)' type_id=7 index_type_id=9 170 [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
167 [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_of 171 [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
168 [10] RESTRICT '(anon)' type_id=11 172 [10] RESTRICT '(anon)' type_id=11
169 [11] PTR '(anon)' type_id=12 173 [11] PTR '(anon)' type_id=12
170 [12] CONST '(anon)' type_id=13 174 [12] CONST '(anon)' type_id=13
171 [13] FWD 'fwd_struct' fwd_kind=union 175 [13] FWD 'fwd_struct' fwd_kind=union
172 [14] ENUM 'my_enum' size=4 vlen=2 176 [14] ENUM 'my_enum' size=4 vlen=2
173 'VAL1' val=3 177 'VAL1' val=3
174 'VAL2' val=7 178 'VAL2' val=7
175 [15] PTR '(anon)' type_id=16 179 [15] PTR '(anon)' type_id=16
176 [16] VOLATILE '(anon)' type_id=17 180 [16] VOLATILE '(anon)' type_id=17
177 [17] TYPEDEF 'my_struct_t' type_id=4 181 [17] TYPEDEF 'my_struct_t' type_id=4
178 [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen= 182 [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
179 'arg1' type_id=1 183 'arg1' type_id=1
180 'arg2' type_id=3 184 'arg2' type_id=3
181 [19] FUNC 'my_func' type_id=18 185 [19] FUNC 'my_func' type_id=18
182 [20] VAR 'struct_global_var' type_id=4, link 186 [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
183 [21] VAR 'global_var' type_id=3, linkage=glo 187 [21] VAR 'global_var' type_id=3, linkage=global-alloc
184 [22] VAR 'my_func.static_var' type_id=3, lin 188 [22] VAR 'my_func.static_var' type_id=3, linkage=static
185 [23] DATASEC 'data_sec' size=0 vlen=3 189 [23] DATASEC 'data_sec' size=0 vlen=3
186 type_id=20 offset=0 size=48 190 type_id=20 offset=0 size=48
187 type_id=21 offset=0 size=4 191 type_id=21 offset=0 size=4
188 type_id=22 offset=52 size=4 192 type_id=22 offset=52 size=4
189 193
190 The following commands print BTF types associa 194 The following commands print BTF types associated with specified map's key,
191 value, both key and value, and all BTF types, 195 value, both key and value, and all BTF types, respectively. By default, both
192 key and value types will be printed. 196 key and value types will be printed.
193 197
194 **# bpftool btf dump map id 123 key** 198 **# bpftool btf dump map id 123 key**
195 199
196 :: 200 ::
197 201
198 [39] TYPEDEF 'u32' type_id=37 202 [39] TYPEDEF 'u32' type_id=37
199 203
200 **# bpftool btf dump map id 123 value** 204 **# bpftool btf dump map id 123 value**
201 205
202 :: 206 ::
203 207
204 [86] PTR '(anon)' type_id=87 208 [86] PTR '(anon)' type_id=87
205 209
206 **# bpftool btf dump map id 123 kv** 210 **# bpftool btf dump map id 123 kv**
207 211
208 :: 212 ::
209 213
210 [39] TYPEDEF 'u32' type_id=37 214 [39] TYPEDEF 'u32' type_id=37
211 [86] PTR '(anon)' type_id=87 215 [86] PTR '(anon)' type_id=87
212 216
213 **# bpftool btf dump map id 123 all** 217 **# bpftool btf dump map id 123 all**
214 218
215 :: 219 ::
216 220
217 [1] PTR '(anon)' type_id=0 221 [1] PTR '(anon)' type_id=0
218 . 222 .
219 . 223 .
220 . 224 .
221 [2866] ARRAY '(anon)' type_id=52 index_type_ 225 [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
222 226
223 All the standard ways to specify map or progra 227 All the standard ways to specify map or program are supported:
224 228
225 **# bpftool btf dump map id 123** 229 **# bpftool btf dump map id 123**
226 230
227 **# bpftool btf dump map pinned /sys/fs/bpf/ma 231 **# bpftool btf dump map pinned /sys/fs/bpf/map_name**
228 232
229 **# bpftool btf dump prog id 456** 233 **# bpftool btf dump prog id 456**
230 234
231 **# bpftool btf dump prog tag b88e0a09b1d9759d 235 **# bpftool btf dump prog tag b88e0a09b1d9759d**
232 236
233 **# bpftool btf dump prog pinned /sys/fs/bpf/p 237 **# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
234 238
235 | 239 |
236 | **# bpftool btf dump file /sys/kernel/btf/i2 240 | **# bpftool btf dump file /sys/kernel/btf/i2c_smbus**
237 | (or) 241 | (or)
238 | **# I2C_SMBUS_ID=$(bpftool btf show -p | jq 242 | **# I2C_SMBUS_ID=$(bpftool btf show -p | jq '.[] | select(.name=="i2c_smbus").id')**
239 | **# bpftool btf dump id ${I2C_SMBUS_ID} -B / 243 | **# bpftool btf dump id ${I2C_SMBUS_ID} -B /sys/kernel/btf/vmlinux**
240 244
241 :: 245 ::
242 246
243 [104848] STRUCT 'i2c_smbus_alert' size=40 vl 247 [104848] STRUCT 'i2c_smbus_alert' size=40 vlen=2
244 'alert' type_id=393 bits_offset=0 248 'alert' type_id=393 bits_offset=0
245 'ara' type_id=56050 bits_offset=256 249 'ara' type_id=56050 bits_offset=256
246 [104849] STRUCT 'alert_data' size=12 vlen=3 250 [104849] STRUCT 'alert_data' size=12 vlen=3
247 'addr' type_id=16 bits_offset=0 251 'addr' type_id=16 bits_offset=0
248 'type' type_id=56053 bits_offset=32 252 'type' type_id=56053 bits_offset=32
249 'data' type_id=7 bits_offset=64 253 'data' type_id=7 bits_offset=64
250 [104850] PTR '(anon)' type_id=104848 254 [104850] PTR '(anon)' type_id=104848
251 [104851] PTR '(anon)' type_id=104849 255 [104851] PTR '(anon)' type_id=104849
252 [104852] FUNC 'i2c_register_spd' type_id=847 256 [104852] FUNC 'i2c_register_spd' type_id=84745 linkage=static
253 [104853] FUNC 'smbalert_driver_init' type_id 257 [104853] FUNC 'smbalert_driver_init' type_id=1213 linkage=static
254 [104854] FUNC_PROTO '(anon)' ret_type_id=18 258 [104854] FUNC_PROTO '(anon)' ret_type_id=18 vlen=1
255 'ara' type_id=56050 259 'ara' type_id=56050
256 [104855] FUNC 'i2c_handle_smbus_alert' type_ 260 [104855] FUNC 'i2c_handle_smbus_alert' type_id=104854 linkage=static
257 [104856] FUNC 'smbalert_remove' type_id=1048 261 [104856] FUNC 'smbalert_remove' type_id=104854 linkage=static
258 [104857] FUNC_PROTO '(anon)' ret_type_id=18 262 [104857] FUNC_PROTO '(anon)' ret_type_id=18 vlen=2
259 'ara' type_id=56050 263 'ara' type_id=56050
260 'id' type_id=56056 264 'id' type_id=56056
261 [104858] FUNC 'smbalert_probe' type_id=10485 265 [104858] FUNC 'smbalert_probe' type_id=104857 linkage=static
262 [104859] FUNC 'smbalert_work' type_id=9695 l 266 [104859] FUNC 'smbalert_work' type_id=9695 linkage=static
263 [104860] FUNC 'smbus_alert' type_id=71367 li 267 [104860] FUNC 'smbus_alert' type_id=71367 linkage=static
264 [104861] FUNC 'smbus_do_alert' type_id=84827 268 [104861] FUNC 'smbus_do_alert' type_id=84827 linkage=static
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.