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