xref: /linux/tools/bpf/bpftool/Documentation/bpftool-btf.rst (revision daa121128a2d2ac6006159e2c47676e4fcd21eab)
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