tools/bpf/bpftool/Documentation/bpftool-btf.rst

   1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2
   3 ================
   4 bpftool-btf
   5 ================
   6 -------------------------------------------------------------------------------
   7 tool for inspection of BTF data
   8 -------------------------------------------------------------------------------
   9
  10 :Manual section: 8
  11
  12 .. include:: substitutions.rst
  13
  14 SYNOPSIS
  15 ========
  16
  17         **bpftool** [*OPTIONS*] **btf** *COMMAND*
  18
  19         *OPTIONS* := { |COMMON_OPTIONS| | { **-B** | **--base-btf** } }
  20
  21         *COMMANDS* := { **dump** | **help** }
  22
  23 BTF 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
  35 DESCRIPTION
  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
  76 OPTIONS
  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
  94 EXAMPLES
  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
 108 This 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
 194 The following commands print BTF types associated with specified map's key,
 195 value, both key and value, and all BTF types, respectively. By default, both
 196 key 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
 227 All 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