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** }] }
  16
  17         *COMMANDS* := { **dump** | **help** }
  18
  19 BTF COMMANDS
  20 =============
  21
  22 |       **bpftool** **btf** { **show** | **list** } [**id** *BTF_ID*]
  23 |       **bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*]
  24 |       **bpftool** **btf help**
  25 |
  26 |       *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
  27 |       *FORMAT* := { **raw** | **c** }
  28 |       *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
  29 |       *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
  30
  31 DESCRIPTION
  32 ===========
  33         **bpftool btf { show | list }** [**id** *BTF_ID*]
  34                   Show information about loaded BTF objects. If a BTF ID is
  35                   specified, show information only about given BTF object,
  36                   otherwise list all BTF objects currently loaded on the
  37                   system.
  38
  39                   Since Linux 5.8 bpftool is able to discover information about
  40                   processes that hold open file descriptors (FDs) against BTF
  41                   objects. On such kernels bpftool will automatically emit this
  42                   information as well.
  43
  44         **bpftool btf dump** *BTF_SRC*
  45                   Dump BTF entries from a given *BTF_SRC*.
  46
  47                   When **id** is specified, BTF object with that ID will be
  48                   loaded and all its BTF types emitted.
  49
  50                   When **map** is provided, it's expected that map has
  51                   associated BTF object with BTF types describing key and
  52                   value. It's possible to select whether to dump only BTF
  53                   type(s) associated with key (**key**), value (**value**),
  54                   both key and value (**kv**), or all BTF types present in
  55                   associated BTF object (**all**). If not specified, **kv**
  56                   is assumed.
  57
  58                   When **prog** is provided, it's expected that program has
  59                   associated BTF object with BTF types.
  60
  61                   When specifying *FILE*, an ELF file is expected, containing
  62                   .BTF section with well-defined BTF binary format data,
  63                   typically produced by clang or pahole.
  64
  65                   **format** option can be used to override default (raw)
  66                   output format. Raw (**raw**) or C-syntax (**c**) output
  67                   formats are supported.
  68
  69         **bpftool btf help**
  70                   Print short help message.
  71
  72 OPTIONS
  73 =======
  74         .. include:: common_options.rst
  75
  76 EXAMPLES
  77 ========
  78 **# bpftool btf dump id 1226**
  79
  80 ::
  81
  82   [1] PTR '(anon)' type_id=2
  83   [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
  84           'pad' type_id=3 bits_offset=0
  85           'sock' type_id=4 bits_offset=64
  86   [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
  87   [4] PTR '(anon)' type_id=5
  88   [5] FWD 'sock' fwd_kind=union
  89
  90 This gives an example of default output for all supported BTF kinds.
  91
  92 **$ cat prog.c**
  93
  94 ::
  95
  96   struct fwd_struct;
  97
  98   enum my_enum {
  99           VAL1 = 3,
 100           VAL2 = 7,
 101   };
 102
 103   typedef struct my_struct my_struct_t;
 104
 105   struct my_struct {
 106           const unsigned int const_int_field;
 107           int bitfield_field: 4;
 108           char arr_field[16];
 109           const struct fwd_struct *restrict fwd_field;
 110           enum my_enum enum_field;
 111           volatile my_struct_t *typedef_ptr_field;
 112   };
 113
 114   union my_union {
 115           int a;
 116           struct my_struct b;
 117   };
 118
 119   struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
 120           .bitfield_field = 3,
 121           .enum_field = VAL1,
 122   };
 123   int global_var __attribute__((section("data_sec"))) = 7;
 124
 125   __attribute__((noinline))
 126   int my_func(union my_union *arg1, int arg2)
 127   {
 128           static int static_var __attribute__((section("data_sec"))) = 123;
 129           static_var++;
 130           return static_var;
 131   }
 132
 133 **$ bpftool btf dump file prog.o**
 134
 135 ::
 136
 137   [1] PTR '(anon)' type_id=2
 138   [2] UNION 'my_union' size=48 vlen=2
 139           'a' type_id=3 bits_offset=0
 140           'b' type_id=4 bits_offset=0
 141   [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
 142   [4] STRUCT 'my_struct' size=48 vlen=6
 143           'const_int_field' type_id=5 bits_offset=0
 144           'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
 145           'arr_field' type_id=8 bits_offset=40
 146           'fwd_field' type_id=10 bits_offset=192
 147           'enum_field' type_id=14 bits_offset=256
 148           'typedef_ptr_field' type_id=15 bits_offset=320
 149   [5] CONST '(anon)' type_id=6
 150   [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
 151   [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
 152   [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
 153   [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
 154   [10] RESTRICT '(anon)' type_id=11
 155   [11] PTR '(anon)' type_id=12
 156   [12] CONST '(anon)' type_id=13
 157   [13] FWD 'fwd_struct' fwd_kind=union
 158   [14] ENUM 'my_enum' size=4 vlen=2
 159           'VAL1' val=3
 160           'VAL2' val=7
 161   [15] PTR '(anon)' type_id=16
 162   [16] VOLATILE '(anon)' type_id=17
 163   [17] TYPEDEF 'my_struct_t' type_id=4
 164   [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
 165           'arg1' type_id=1
 166           'arg2' type_id=3
 167   [19] FUNC 'my_func' type_id=18
 168   [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
 169   [21] VAR 'global_var' type_id=3, linkage=global-alloc
 170   [22] VAR 'my_func.static_var' type_id=3, linkage=static
 171   [23] DATASEC 'data_sec' size=0 vlen=3
 172           type_id=20 offset=0 size=48
 173           type_id=21 offset=0 size=4
 174           type_id=22 offset=52 size=4
 175
 176 The following commands print BTF types associated with specified map's key,
 177 value, both key and value, and all BTF types, respectively. By default, both
 178 key and value types will be printed.
 179
 180 **# bpftool btf dump map id 123 key**
 181
 182 ::
 183
 184   [39] TYPEDEF 'u32' type_id=37
 185
 186 **# bpftool btf dump map id 123 value**
 187
 188 ::
 189
 190   [86] PTR '(anon)' type_id=87
 191
 192 **# bpftool btf dump map id 123 kv**
 193
 194 ::
 195
 196   [39] TYPEDEF 'u32' type_id=37
 197   [86] PTR '(anon)' type_id=87
 198
 199 **# bpftool btf dump map id 123 all**
 200
 201 ::
 202
 203   [1] PTR '(anon)' type_id=0
 204   .
 205   .
 206   .
 207   [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
 208
 209 All the standard ways to specify map or program are supported:
 210
 211 **# bpftool btf dump map id 123**
 212
 213 **# bpftool btf dump map pinned /sys/fs/bpf/map_name**
 214
 215 **# bpftool btf dump prog id 456**
 216
 217 **# bpftool btf dump prog tag b88e0a09b1d9759d**
 218
 219 **# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**