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