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