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