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   [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   struct fwd_struct;
 110
 111   enum my_enum {
 112           VAL1 = 3,
 113           VAL2 = 7,
 114   };
 115
 116   typedef struct my_struct my_struct_t;
 117
 118   struct my_struct {
 119           const unsigned int const_int_field;
 120           int bitfield_field: 4;
 121           char arr_field[16];
 122           const struct fwd_struct *restrict fwd_field;
 123           enum my_enum enum_field;
 124           volatile my_struct_t *typedef_ptr_field;
 125   };
 126
 127   union my_union {
 128           int a;
 129           struct my_struct b;
 130   };
 131
 132   struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
 133           .bitfield_field = 3,
 134           .enum_field = VAL1,
 135   };
 136   int global_var __attribute__((section("data_sec"))) = 7;
 137
 138   __attribute__((noinline))
 139   int my_func(union my_union *arg1, int arg2)
 140   {
 141           static int static_var __attribute__((section("data_sec"))) = 123;
 142           static_var++;
 143           return static_var;
 144   }
 145
 146 **$ bpftool btf dump file prog.o**
 147 ::
 148
 149   [1] PTR '(anon)' type_id=2
 150   [2] UNION 'my_union' size=48 vlen=2
 151           'a' type_id=3 bits_offset=0
 152           'b' type_id=4 bits_offset=0
 153   [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
 154   [4] STRUCT 'my_struct' size=48 vlen=6
 155           'const_int_field' type_id=5 bits_offset=0
 156           'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
 157           'arr_field' type_id=8 bits_offset=40
 158           'fwd_field' type_id=10 bits_offset=192
 159           'enum_field' type_id=14 bits_offset=256
 160           'typedef_ptr_field' type_id=15 bits_offset=320
 161   [5] CONST '(anon)' type_id=6
 162   [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
 163   [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
 164   [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
 165   [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
 166   [10] RESTRICT '(anon)' type_id=11
 167   [11] PTR '(anon)' type_id=12
 168   [12] CONST '(anon)' type_id=13
 169   [13] FWD 'fwd_struct' fwd_kind=union
 170   [14] ENUM 'my_enum' size=4 vlen=2
 171           'VAL1' val=3
 172           'VAL2' val=7
 173   [15] PTR '(anon)' type_id=16
 174   [16] VOLATILE '(anon)' type_id=17
 175   [17] TYPEDEF 'my_struct_t' type_id=4
 176   [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
 177           'arg1' type_id=1
 178           'arg2' type_id=3
 179   [19] FUNC 'my_func' type_id=18
 180   [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
 181   [21] VAR 'global_var' type_id=3, linkage=global-alloc
 182   [22] VAR 'my_func.static_var' type_id=3, linkage=static
 183   [23] DATASEC 'data_sec' size=0 vlen=3
 184           type_id=20 offset=0 size=48
 185           type_id=21 offset=0 size=4
 186           type_id=22 offset=52 size=4
 187
 188 The following commands print BTF types associated with specified map's key,
 189 value, both key and value, and all BTF types, respectively. By default, both
 190 key and value types will be printed.
 191
 192 **# bpftool btf dump map id 123 key**
 193
 194 ::
 195
 196   [39] TYPEDEF 'u32' type_id=37
 197
 198 **# bpftool btf dump map id 123 value**
 199
 200 ::
 201
 202   [86] PTR '(anon)' type_id=87
 203
 204 **# bpftool btf dump map id 123 kv**
 205
 206 ::
 207
 208   [39] TYPEDEF 'u32' type_id=37
 209   [86] PTR '(anon)' type_id=87
 210
 211 **# bpftool btf dump map id 123 all**
 212
 213 ::
 214
 215   [1] PTR '(anon)' type_id=0
 216   .
 217   .
 218   .
 219   [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
 220
 221 All the standard ways to specify map or program are supported:
 222
 223 **# bpftool btf dump map id 123**
 224
 225 **# bpftool btf dump map pinned /sys/fs/bpf/map_name**
 226
 227 **# bpftool btf dump prog id 456**
 228
 229 **# bpftool btf dump prog tag b88e0a09b1d9759d**
 230
 231 **# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
 232
 233 SEE ALSO
 234 ========
 235         **bpf**\ (2),
 236         **bpf-helpers**\ (7),
 237         **bpftool**\ (8),
 238         **bpftool-btf**\ (8),
 239         **bpftool-cgroup**\ (8),
 240         **bpftool-feature**\ (8),
 241         **bpftool-gen**\ (8),
 242         **bpftool-iter**\ (8),
 243         **bpftool-link**\ (8),
 244         **bpftool-map**\ (8),
 245         **bpftool-net**\ (8),
 246         **bpftool-perf**\ (8),
 247         **bpftool-prog**\ (8),
 248         **bpftool-struct_ops**\ (8)