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