0001 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002
0003 ================
0004 bpftool-btf
0005 ================
0006 -------------------------------------------------------------------------------
0007 tool for inspection of BTF data
0008 -------------------------------------------------------------------------------
0009
0010 :Manual section: 8
0011
0012 .. include:: substitutions.rst
0013
0014 SYNOPSIS
0015 ========
0016
0017 **bpftool** [*OPTIONS*] **btf** *COMMAND*
0018
0019 *OPTIONS* := { |COMMON_OPTIONS| | { **-B** | **--base-btf** } }
0020
0021 *COMMANDS* := { **dump** | **help** }
0022
0023 BTF COMMANDS
0024 =============
0025
0026 | **bpftool** **btf** { **show** | **list** } [**id** *BTF_ID*]
0027 | **bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*]
0028 | **bpftool** **btf help**
0029 |
0030 | *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
0031 | *FORMAT* := { **raw** | **c** }
0032 | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
0033 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
0034
0035 DESCRIPTION
0036 ===========
0037 **bpftool btf { show | list }** [**id** *BTF_ID*]
0038 Show information about loaded BTF objects. If a BTF ID is
0039 specified, show information only about given BTF object,
0040 otherwise list all BTF objects currently loaded on the
0041 system.
0042
0043 Since Linux 5.8 bpftool is able to discover information about
0044 processes that hold open file descriptors (FDs) against BTF
0045 objects. On such kernels bpftool will automatically emit this
0046 information as well.
0047
0048 **bpftool btf dump** *BTF_SRC*
0049 Dump BTF entries from a given *BTF_SRC*.
0050
0051 When **id** is specified, BTF object with that ID will be
0052 loaded and all its BTF types emitted.
0053
0054 When **map** is provided, it's expected that map has
0055 associated BTF object with BTF types describing key and
0056 value. It's possible to select whether to dump only BTF
0057 type(s) associated with key (**key**), value (**value**),
0058 both key and value (**kv**), or all BTF types present in
0059 associated BTF object (**all**). If not specified, **kv**
0060 is assumed.
0061
0062 When **prog** is provided, it's expected that program has
0063 associated BTF object with BTF types.
0064
0065 When specifying *FILE*, an ELF file is expected, containing
0066 .BTF section with well-defined BTF binary format data,
0067 typically produced by clang or pahole.
0068
0069 **format** option can be used to override default (raw)
0070 output format. Raw (**raw**) or C-syntax (**c**) output
0071 formats are supported.
0072
0073 **bpftool btf help**
0074 Print short help message.
0075
0076 OPTIONS
0077 =======
0078 .. include:: common_options.rst
0079
0080 -B, --base-btf *FILE*
0081 Pass a base BTF object. Base BTF objects are typically used
0082 with BTF objects for kernel modules. To avoid duplicating
0083 all kernel symbols required by modules, BTF objects for
0084 modules are "split", they are built incrementally on top of
0085 the kernel (vmlinux) BTF object. So the base BTF reference
0086 should usually point to the kernel BTF.
0087
0088 When the main BTF object to process (for example, the
0089 module BTF to dump) is passed as a *FILE*, bpftool attempts
0090 to autodetect the path for the base object, and passing
0091 this option is optional. When the main BTF object is passed
0092 through other handles, this option becomes necessary.
0093
0094 EXAMPLES
0095 ========
0096 **# bpftool btf dump id 1226**
0097
0098 ::
0099
0100 [1] PTR '(anon)' type_id=2
0101 [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
0102 'pad' type_id=3 bits_offset=0
0103 'sock' type_id=4 bits_offset=64
0104 [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
0105 [4] PTR '(anon)' type_id=5
0106 [5] FWD 'sock' fwd_kind=union
0107
0108 This gives an example of default output for all supported BTF kinds.
0109
0110 **$ cat prog.c**
0111
0112 ::
0113
0114 struct fwd_struct;
0115
0116 enum my_enum {
0117 VAL1 = 3,
0118 VAL2 = 7,
0119 };
0120
0121 typedef struct my_struct my_struct_t;
0122
0123 struct my_struct {
0124 const unsigned int const_int_field;
0125 int bitfield_field: 4;
0126 char arr_field[16];
0127 const struct fwd_struct *restrict fwd_field;
0128 enum my_enum enum_field;
0129 volatile my_struct_t *typedef_ptr_field;
0130 };
0131
0132 union my_union {
0133 int a;
0134 struct my_struct b;
0135 };
0136
0137 struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
0138 .bitfield_field = 3,
0139 .enum_field = VAL1,
0140 };
0141 int global_var __attribute__((section("data_sec"))) = 7;
0142
0143 __attribute__((noinline))
0144 int my_func(union my_union *arg1, int arg2)
0145 {
0146 static int static_var __attribute__((section("data_sec"))) = 123;
0147 static_var++;
0148 return static_var;
0149 }
0150
0151 **$ bpftool btf dump file prog.o**
0152
0153 ::
0154
0155 [1] PTR '(anon)' type_id=2
0156 [2] UNION 'my_union' size=48 vlen=2
0157 'a' type_id=3 bits_offset=0
0158 'b' type_id=4 bits_offset=0
0159 [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
0160 [4] STRUCT 'my_struct' size=48 vlen=6
0161 'const_int_field' type_id=5 bits_offset=0
0162 'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
0163 'arr_field' type_id=8 bits_offset=40
0164 'fwd_field' type_id=10 bits_offset=192
0165 'enum_field' type_id=14 bits_offset=256
0166 'typedef_ptr_field' type_id=15 bits_offset=320
0167 [5] CONST '(anon)' type_id=6
0168 [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
0169 [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
0170 [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
0171 [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
0172 [10] RESTRICT '(anon)' type_id=11
0173 [11] PTR '(anon)' type_id=12
0174 [12] CONST '(anon)' type_id=13
0175 [13] FWD 'fwd_struct' fwd_kind=union
0176 [14] ENUM 'my_enum' size=4 vlen=2
0177 'VAL1' val=3
0178 'VAL2' val=7
0179 [15] PTR '(anon)' type_id=16
0180 [16] VOLATILE '(anon)' type_id=17
0181 [17] TYPEDEF 'my_struct_t' type_id=4
0182 [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
0183 'arg1' type_id=1
0184 'arg2' type_id=3
0185 [19] FUNC 'my_func' type_id=18
0186 [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
0187 [21] VAR 'global_var' type_id=3, linkage=global-alloc
0188 [22] VAR 'my_func.static_var' type_id=3, linkage=static
0189 [23] DATASEC 'data_sec' size=0 vlen=3
0190 type_id=20 offset=0 size=48
0191 type_id=21 offset=0 size=4
0192 type_id=22 offset=52 size=4
0193
0194 The following commands print BTF types associated with specified map's key,
0195 value, both key and value, and all BTF types, respectively. By default, both
0196 key and value types will be printed.
0197
0198 **# bpftool btf dump map id 123 key**
0199
0200 ::
0201
0202 [39] TYPEDEF 'u32' type_id=37
0203
0204 **# bpftool btf dump map id 123 value**
0205
0206 ::
0207
0208 [86] PTR '(anon)' type_id=87
0209
0210 **# bpftool btf dump map id 123 kv**
0211
0212 ::
0213
0214 [39] TYPEDEF 'u32' type_id=37
0215 [86] PTR '(anon)' type_id=87
0216
0217 **# bpftool btf dump map id 123 all**
0218
0219 ::
0220
0221 [1] PTR '(anon)' type_id=0
0222 .
0223 .
0224 .
0225 [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
0226
0227 All the standard ways to specify map or program are supported:
0228
0229 **# bpftool btf dump map id 123**
0230
0231 **# bpftool btf dump map pinned /sys/fs/bpf/map_name**
0232
0233 **# bpftool btf dump prog id 456**
0234
0235 **# bpftool btf dump prog tag b88e0a09b1d9759d**
0236
0237 **# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
0238
0239 |
0240 | **# bpftool btf dump file /sys/kernel/btf/i2c_smbus**
0241 | (or)
0242 | **# I2C_SMBUS_ID=$(bpftool btf show -p | jq '.[] | select(.name=="i2c_smbus").id')**
0243 | **# bpftool btf dump id ${I2C_SMBUS_ID} -B /sys/kernel/btf/vmlinux**
0244
0245 ::
0246
0247 [104848] STRUCT 'i2c_smbus_alert' size=40 vlen=2
0248 'alert' type_id=393 bits_offset=0
0249 'ara' type_id=56050 bits_offset=256
0250 [104849] STRUCT 'alert_data' size=12 vlen=3
0251 'addr' type_id=16 bits_offset=0
0252 'type' type_id=56053 bits_offset=32
0253 'data' type_id=7 bits_offset=64
0254 [104850] PTR '(anon)' type_id=104848
0255 [104851] PTR '(anon)' type_id=104849
0256 [104852] FUNC 'i2c_register_spd' type_id=84745 linkage=static
0257 [104853] FUNC 'smbalert_driver_init' type_id=1213 linkage=static
0258 [104854] FUNC_PROTO '(anon)' ret_type_id=18 vlen=1
0259 'ara' type_id=56050
0260 [104855] FUNC 'i2c_handle_smbus_alert' type_id=104854 linkage=static
0261 [104856] FUNC 'smbalert_remove' type_id=104854 linkage=static
0262 [104857] FUNC_PROTO '(anon)' ret_type_id=18 vlen=2
0263 'ara' type_id=56050
0264 'id' type_id=56056
0265 [104858] FUNC 'smbalert_probe' type_id=104857 linkage=static
0266 [104859] FUNC 'smbalert_work' type_id=9695 linkage=static
0267 [104860] FUNC 'smbus_alert' type_id=71367 linkage=static
0268 [104861] FUNC 'smbus_do_alert' type_id=84827 linkage=static
