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