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         -h, --help
  75                   Print short generic help message (similar to **bpftool help**).
  76
  77         -V, --version
  78                   Print version number (similar to **bpftool version**).
  79
  80         -j, --json
  81                   Generate JSON output. For commands that cannot produce JSON, this
  82                   option has no effect.
  83
  84         -p, --pretty
  85                   Generate human-readable JSON output. Implies **-j**.
  86
  87         -d, --debug
  88                   Print all logs available from libbpf, including debug-level
  89                   information.
  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 SEE ALSO
 237 ========
 238         **bpf**\ (2),
 239         **bpf-helpers**\ (7),
 240         **bpftool**\ (8),
 241         **bpftool-btf**\ (8),
 242         **bpftool-cgroup**\ (8),
 243         **bpftool-feature**\ (8),
 244         **bpftool-gen**\ (8),
 245         **bpftool-iter**\ (8),
 246         **bpftool-link**\ (8),
 247         **bpftool-map**\ (8),
 248         **bpftool-net**\ (8),
 249         **bpftool-perf**\ (8),
 250         **bpftool-prog**\ (8),
 251         **bpftool-struct_ops**\ (8)