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

   1 ================
   2 bpftool-btf
   3 ================
   4 -------------------------------------------------------------------------------
   5 tool for inspection of BTF data
   6 -------------------------------------------------------------------------------
   7
   8 :Manual section: 8
   9
  10 SYNOPSIS
  11 ========
  12
  13         **bpftool** [*OPTIONS*] **btf** *COMMAND*
  14
  15         *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | {**-d** | **--debug** } |
  16                 { **-B** | **--base-btf** } }
  17
  18         *COMMANDS* := { **dump** | **help** }
  19
  20 BTF COMMANDS
  21 =============
  22
  23 |       **bpftool** **btf** { **show** | **list** } [**id** *BTF_ID*]
  24 |       **bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*]
  25 |       **bpftool** **btf help**
  26 |
  27 |       *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
  28 |       *FORMAT* := { **raw** | **c** }
  29 |       *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
  30 |       *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
  31
  32 DESCRIPTION
  33 ===========
  34         **bpftool btf { show | list }** [**id** *BTF_ID*]
  35                   Show information about loaded BTF objects. If a BTF ID is
  36                   specified, show information only about given BTF object,
  37                   otherwise list all BTF objects currently loaded on the
  38                   system.
  39
  40                   Since Linux 5.8 bpftool is able to discover information about
  41                   processes that hold open file descriptors (FDs) against BTF
  42                   objects. On such kernels bpftool will automatically emit this
  43                   information as well.
  44
  45         **bpftool btf dump** *BTF_SRC*
  46                   Dump BTF entries from a given *BTF_SRC*.
  47
  48                   When **id** is specified, BTF object with that ID will be
  49                   loaded and all its BTF types emitted.
  50
  51                   When **map** is provided, it's expected that map has
  52                   associated BTF object with BTF types describing key and
  53                   value. It's possible to select whether to dump only BTF
  54                   type(s) associated with key (**key**), value (**value**),
  55                   both key and value (**kv**), or all BTF types present in
  56                   associated BTF object (**all**). If not specified, **kv**
  57                   is assumed.
  58
  59                   When **prog** is provided, it's expected that program has
  60                   associated BTF object with BTF types.
  61
  62                   When specifying *FILE*, an ELF file is expected, containing
  63                   .BTF section with well-defined BTF binary format data,
  64                   typically produced by clang or pahole.
  65
  66                   **format** option can be used to override default (raw)
  67                   output format. Raw (**raw**) or C-syntax (**c**) output
  68                   formats are supported.
  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
  79                   with BTF objects for kernel modules. To avoid duplicating
  80                   all kernel symbols required by modules, BTF objects for
  81                   modules are "split", they are built incrementally on top of
  82                   the kernel (vmlinux) BTF object. So the base BTF reference
  83                   should usually point to the kernel BTF.
  84
  85                   When the main BTF object to process (for example, the
  86                   module BTF to dump) is passed as a *FILE*, bpftool attempts
  87                   to autodetect the path for the base object, and passing
  88                   this option is optional. When the main BTF object is passed
  89                   through other handles, this option becomes necessary.
  90
  91 EXAMPLES
  92 ========
  93 **# bpftool btf dump id 1226**
  94
  95 ::
  96
  97   [1] PTR '(anon)' type_id=2
  98   [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
  99           'pad' type_id=3 bits_offset=0
 100           'sock' type_id=4 bits_offset=64
 101   [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
 102   [4] PTR '(anon)' type_id=5
 103   [5] FWD 'sock' fwd_kind=union
 104
 105 This gives an example of default output for all supported BTF kinds.
 106
 107 **$ cat prog.c**
 108
 109 ::
 110
 111   struct fwd_struct;
 112
 113   enum my_enum {
 114           VAL1 = 3,
 115           VAL2 = 7,
 116   };
 117
 118   typedef struct my_struct my_struct_t;
 119
 120   struct my_struct {
 121           const unsigned int const_int_field;
 122           int bitfield_field: 4;
 123           char arr_field[16];
 124           const struct fwd_struct *restrict fwd_field;
 125           enum my_enum enum_field;
 126           volatile my_struct_t *typedef_ptr_field;
 127   };
 128
 129   union my_union {
 130           int a;
 131           struct my_struct b;
 132   };
 133
 134   struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
 135           .bitfield_field = 3,
 136           .enum_field = VAL1,
 137   };
 138   int global_var __attribute__((section("data_sec"))) = 7;
 139
 140   __attribute__((noinline))
 141   int my_func(union my_union *arg1, int arg2)
 142   {
 143           static int static_var __attribute__((section("data_sec"))) = 123;
 144           static_var++;
 145           return static_var;
 146   }
 147
 148 **$ bpftool btf dump file prog.o**
 149
 150 ::
 151
 152   [1] PTR '(anon)' type_id=2
 153   [2] UNION 'my_union' size=48 vlen=2
 154           'a' type_id=3 bits_offset=0
 155           'b' type_id=4 bits_offset=0
 156   [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
 157   [4] STRUCT 'my_struct' size=48 vlen=6
 158           'const_int_field' type_id=5 bits_offset=0
 159           'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
 160           'arr_field' type_id=8 bits_offset=40
 161           'fwd_field' type_id=10 bits_offset=192
 162           'enum_field' type_id=14 bits_offset=256
 163           'typedef_ptr_field' type_id=15 bits_offset=320
 164   [5] CONST '(anon)' type_id=6
 165   [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
 166   [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
 167   [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
 168   [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
 169   [10] RESTRICT '(anon)' type_id=11
 170   [11] PTR '(anon)' type_id=12
 171   [12] CONST '(anon)' type_id=13
 172   [13] FWD 'fwd_struct' fwd_kind=union
 173   [14] ENUM 'my_enum' size=4 vlen=2
 174           'VAL1' val=3
 175           'VAL2' val=7
 176   [15] PTR '(anon)' type_id=16
 177   [16] VOLATILE '(anon)' type_id=17
 178   [17] TYPEDEF 'my_struct_t' type_id=4
 179   [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
 180           'arg1' type_id=1
 181           'arg2' type_id=3
 182   [19] FUNC 'my_func' type_id=18
 183   [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
 184   [21] VAR 'global_var' type_id=3, linkage=global-alloc
 185   [22] VAR 'my_func.static_var' type_id=3, linkage=static
 186   [23] DATASEC 'data_sec' size=0 vlen=3
 187           type_id=20 offset=0 size=48
 188           type_id=21 offset=0 size=4
 189           type_id=22 offset=52 size=4
 190
 191 The following commands print BTF types associated with specified map's key,
 192 value, both key and value, and all BTF types, respectively. By default, both
 193 key and value types will be printed.
 194
 195 **# bpftool btf dump map id 123 key**
 196
 197 ::
 198
 199   [39] TYPEDEF 'u32' type_id=37
 200
 201 **# bpftool btf dump map id 123 value**
 202
 203 ::
 204
 205   [86] PTR '(anon)' type_id=87
 206
 207 **# bpftool btf dump map id 123 kv**
 208
 209 ::
 210
 211   [39] TYPEDEF 'u32' type_id=37
 212   [86] PTR '(anon)' type_id=87
 213
 214 **# bpftool btf dump map id 123 all**
 215
 216 ::
 217
 218   [1] PTR '(anon)' type_id=0
 219   .
 220   .
 221   .
 222   [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
 223
 224 All the standard ways to specify map or program are supported:
 225
 226 **# bpftool btf dump map id 123**
 227
 228 **# bpftool btf dump map pinned /sys/fs/bpf/map_name**
 229
 230 **# bpftool btf dump prog id 456**
 231
 232 **# bpftool btf dump prog tag b88e0a09b1d9759d**
 233
 234 **# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
 235
 236 |
 237 | **# bpftool btf dump file /sys/kernel/btf/i2c_smbus**
 238 | (or)
 239 | **# I2C_SMBUS_ID=$(bpftool btf show -p | jq '.[] | select(.name=="i2c_smbus").id')**
 240 | **# bpftool btf dump id ${I2C_SMBUS_ID} -B /sys/kernel/btf/vmlinux**
 241
 242 ::
 243
 244   [104848] STRUCT 'i2c_smbus_alert' size=40 vlen=2
 245           'alert' type_id=393 bits_offset=0
 246           'ara' type_id=56050 bits_offset=256
 247   [104849] STRUCT 'alert_data' size=12 vlen=3
 248           'addr' type_id=16 bits_offset=0
 249           'type' type_id=56053 bits_offset=32
 250           'data' type_id=7 bits_offset=64
 251   [104850] PTR '(anon)' type_id=104848
 252   [104851] PTR '(anon)' type_id=104849
 253   [104852] FUNC 'i2c_register_spd' type_id=84745 linkage=static
 254   [104853] FUNC 'smbalert_driver_init' type_id=1213 linkage=static
 255   [104854] FUNC_PROTO '(anon)' ret_type_id=18 vlen=1
 256           'ara' type_id=56050
 257   [104855] FUNC 'i2c_handle_smbus_alert' type_id=104854 linkage=static
 258   [104856] FUNC 'smbalert_remove' type_id=104854 linkage=static
 259   [104857] FUNC_PROTO '(anon)' ret_type_id=18 vlen=2
 260           'ara' type_id=56050
 261           'id' type_id=56056
 262   [104858] FUNC 'smbalert_probe' type_id=104857 linkage=static
 263   [104859] FUNC 'smbalert_work' type_id=9695 linkage=static
 264   [104860] FUNC 'smbus_alert' type_id=71367 linkage=static
 265   [104861] FUNC 'smbus_do_alert' type_id=84827 linkage=static