bpftool-btf.rst

  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