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