bpftool-btf(8)

1BPFTOOL-BTF(8)                                                  BPFTOOL-BTF(8)
2
3
4

NAME

6       bpftool-btf - tool for inspection of BTF data
7

SYNOPSIS

9          bpftool [OPTIONS] btf COMMAND
10
11          OPTIONS := { { -j | --json } [{ -p | --pretty }] }
12
13          COMMANDS := { dump | help }
14

BTF COMMANDS

16       bpftool btf { show | list } [id BTF_ID]
17       bpftool btf dump BTF_SRC [format FORMAT]
18       bpftool btf help
19
20       BTF_SRC := { id BTF_ID | prog PROG | map MAP [{key | value | kv | all}] | file FILE }
21       FORMAT := { raw | c }
22       MAP := { id MAP_ID | pinned FILE }
23       PROG := { id PROG_ID | pinned FILE | tag PROG_TAG }
24
25

DESCRIPTION

27          bpftool btf { show | list } [id BTF_ID]
28                 Show  information  about  loaded  BTF objects. If a BTF ID is
29                 specified, show information only about given BTF object, oth‐
30                 erwise list all BTF objects currently loaded on the system.
31
32                 Since Linux 5.8 bpftool is able to discover information about
33                 processes that hold open file descriptors (FDs)  against  BTF
34                 objects. On such kernels bpftool will automatically emit this
35                 information as well.
36
37          bpftool btf dump BTF_SRC
38                 Dump BTF entries from a given BTF_SRC.
39
40                 When id is specified, BTF object with that ID will be  loaded
41                 and all its BTF types emitted.
42
43                 When  map  is provided, it's expected that map has associated
44                 BTF object with BTF types describing key and value. It's pos‐
45                 sible  to  select whether to dump only BTF type(s) associated
46                 with key (key), value (value), both key and  value  (kv),  or
47                 all  BTF types present in associated BTF object (all). If not
48                 specified, kv is assumed.
49
50                 When prog is provided, it's expected that program has associ‐
51                 ated BTF object with BTF types.
52
53                 When  specifying  FILE,  an  ELF file is expected, containing
54                 .BTF section with well-defined BTF binary format data,  typi‐
55                 cally produced by clang or pahole.
56
57                 format  option  can  be used to override default (raw) output
58                 format. Raw (raw) or C-syntax (c)  output  formats  are  sup‐
59                 ported.
60
61          bpftool btf help
62                 Print short help message.
63

OPTIONS

65          -h, --help
66                 Print short help message (similar to bpftool help).
67
68          -V, --version
69                 Print  version  number  (similar  to  bpftool  version),  and
70                 optional features that were included when  bpftool  was  com‐
71                 piled.  Optional  features  include linking against libbfd to
72                 provide the disassembler for JIT-ted programs  (bpftool  prog
73                 dump  jited)  and  usage of BPF skeletons (some features like
74                 bpftool prog  profile  or  showing  pids  associated  to  BPF
75                 objects may rely on it).
76
77          -j, --json
78                 Generate  JSON output. For commands that cannot produce JSON,
79                 this option has no effect.
80
81          -p, --pretty
82                 Generate human-readable JSON output. Implies -j.
83
84          -d, --debug
85                 Print all logs available, even debug-level information.  This
86                 includes  logs from libbpf as well as from the verifier, when
87                 attempting to load programs.
88

EXAMPLES

90       # bpftool btf dump id 1226
91
92          [1] PTR '(anon)' type_id=2
93          [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
94                  'pad' type_id=3 bits_offset=0
95                  'sock' type_id=4 bits_offset=64
96          [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
97          [4] PTR '(anon)' type_id=5
98          [5] FWD 'sock' fwd_kind=union
99
100       This gives an example of default output for all supported BTF kinds.
101
102       $ cat prog.c
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          [1] PTR '(anon)' type_id=2
144          [2] UNION 'my_union' size=48 vlen=2
145                  'a' type_id=3 bits_offset=0
146                  'b' type_id=4 bits_offset=0
147          [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
148          [4] STRUCT 'my_struct' size=48 vlen=6
149                  'const_int_field' type_id=5 bits_offset=0
150                  'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
151                  'arr_field' type_id=8 bits_offset=40
152                  'fwd_field' type_id=10 bits_offset=192
153                  'enum_field' type_id=14 bits_offset=256
154                  'typedef_ptr_field' type_id=15 bits_offset=320
155          [5] CONST '(anon)' type_id=6
156          [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
157          [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
158          [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
159          [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
160          [10] RESTRICT '(anon)' type_id=11
161          [11] PTR '(anon)' type_id=12
162          [12] CONST '(anon)' type_id=13
163          [13] FWD 'fwd_struct' fwd_kind=union
164          [14] ENUM 'my_enum' size=4 vlen=2
165                  'VAL1' val=3
166                  'VAL2' val=7
167          [15] PTR '(anon)' type_id=16
168          [16] VOLATILE '(anon)' type_id=17
169          [17] TYPEDEF 'my_struct_t' type_id=4
170          [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
171                  'arg1' type_id=1
172                  'arg2' type_id=3
173          [19] FUNC 'my_func' type_id=18
174          [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
175          [21] VAR 'global_var' type_id=3, linkage=global-alloc
176          [22] VAR 'my_func.static_var' type_id=3, linkage=static
177          [23] DATASEC 'data_sec' size=0 vlen=3
178                  type_id=20 offset=0 size=48
179                  type_id=21 offset=0 size=4
180                  type_id=22 offset=52 size=4
181
182       The following commands print BTF types associated with specified  map's
183       key,  value,  both  key  and value, and all BTF types, respectively. By
184       default, both key and value types will be printed.
185
186       # bpftool btf dump map id 123 key
187
188          [39] TYPEDEF 'u32' type_id=37
189
190       # bpftool btf dump map id 123 value
191
192          [86] PTR '(anon)' type_id=87
193
194       # bpftool btf dump map id 123 kv
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          [1] PTR '(anon)' type_id=0
202          .
203          .
204          .
205          [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
206
207       All the standard ways to specify map or program are supported:
208
209       # bpftool btf dump map id 123
210
211       # bpftool btf dump map pinned /sys/fs/bpf/map_name
212
213       # bpftool btf dump prog id 456
214
215       # bpftool btf dump prog tag b88e0a09b1d9759d
216
217       # bpftool btf dump prog pinned /sys/fs/bpf/prog_name
218

NAME

SYNOPSIS

BTF COMMANDS

DESCRIPTION

OPTIONS

EXAMPLES

SEE ALSO