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 }] | { -d | --debug }
12          | { -l | --legacy } | { -B | --base-btf } }
13
14          COMMANDS := { dump | help }
15

BTF COMMANDS

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

DESCRIPTION

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

OPTIONS

66          -h, --help
67                 Print short help message (similar to bpftool help).
68
69          -V, --version
70                 Print bpftool's version number (similar to bpftool  version),
71                 the  number  of  the libbpf version in use, and optional fea‐
72                 tures that were included when bpftool was compiled.  Optional
73                 features include linking against libbfd to provide the disas‐
74                 sembler for JIT-ted programs (bpftool prog  dump  jited)  and
75                 usage  of BPF skeletons (some features like bpftool prog pro‐
76                 file or showing pids associated to BPF objects  may  rely  on
77                 it).
78
79          -j, --json
80                 Generate  JSON output. For commands that cannot produce JSON,
81                 this option has no effect.
82
83          -p, --pretty
84                 Generate human-readable JSON output. Implies -j.
85
86          -d, --debug
87                 Print all logs available, even debug-level information.  This
88                 includes  logs from libbpf as well as from the verifier, when
89                 attempting to load programs.
90
91          -l, --legacy
92                 Use legacy libbpf mode which has more relaxed BPF program re‐
93                 quirements.  By default, bpftool has more strict requirements
94                 about section names, changes pinning logic and  doesn't  sup‐
95                 port some of the older non-BTF map declarations.
96
97                 See
98                 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
99                 for details.
100
101          -B, --base-btf FILE
102                 Pass  a  base BTF object. Base BTF objects are typically used
103                 with BTF objects for kernel modules. To avoid duplicating all
104                 kernel  symbols  required by modules, BTF objects for modules
105                 are "split", they are built incrementally on top of the  ker‐
106                 nel  (vmlinux)  BTF  object. So the base BTF reference should
107                 usually point to the kernel BTF.
108
109                 When the main BTF object to process (for example, the  module
110                 BTF to dump) is passed as a FILE, bpftool attempts to autode‐
111                 tect the path for the base object, and passing this option is
112                 optional.  When  the  main BTF object is passed through other
113                 handles, this option becomes necessary.
114

EXAMPLES

116       # bpftool btf dump id 1226
117
118          [1] PTR '(anon)' type_id=2
119          [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
120                  'pad' type_id=3 bits_offset=0
121                  'sock' type_id=4 bits_offset=64
122          [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
123          [4] PTR '(anon)' type_id=5
124          [5] FWD 'sock' fwd_kind=union
125
126       This gives an example of default output for all supported BTF kinds.
127
128       $ cat prog.c
129
130          struct fwd_struct;
131
132          enum my_enum {
133                  VAL1 = 3,
134                  VAL2 = 7,
135          };
136
137          typedef struct my_struct my_struct_t;
138
139          struct my_struct {
140                  const unsigned int const_int_field;
141                  int bitfield_field: 4;
142                  char arr_field[16];
143                  const struct fwd_struct *restrict fwd_field;
144                  enum my_enum enum_field;
145                  volatile my_struct_t *typedef_ptr_field;
146          };
147
148          union my_union {
149                  int a;
150                  struct my_struct b;
151          };
152
153          struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
154                  .bitfield_field = 3,
155                  .enum_field = VAL1,
156          };
157          int global_var __attribute__((section("data_sec"))) = 7;
158
159          __attribute__((noinline))
160          int my_func(union my_union *arg1, int arg2)
161          {
162                  static int static_var __attribute__((section("data_sec"))) = 123;
163                  static_var++;
164                  return static_var;
165          }
166
167       $ bpftool btf dump file prog.o
168
169          [1] PTR '(anon)' type_id=2
170          [2] UNION 'my_union' size=48 vlen=2
171                  'a' type_id=3 bits_offset=0
172                  'b' type_id=4 bits_offset=0
173          [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
174          [4] STRUCT 'my_struct' size=48 vlen=6
175                  'const_int_field' type_id=5 bits_offset=0
176                  'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
177                  'arr_field' type_id=8 bits_offset=40
178                  'fwd_field' type_id=10 bits_offset=192
179                  'enum_field' type_id=14 bits_offset=256
180                  'typedef_ptr_field' type_id=15 bits_offset=320
181          [5] CONST '(anon)' type_id=6
182          [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
183          [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
184          [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
185          [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
186          [10] RESTRICT '(anon)' type_id=11
187          [11] PTR '(anon)' type_id=12
188          [12] CONST '(anon)' type_id=13
189          [13] FWD 'fwd_struct' fwd_kind=union
190          [14] ENUM 'my_enum' size=4 vlen=2
191                  'VAL1' val=3
192                  'VAL2' val=7
193          [15] PTR '(anon)' type_id=16
194          [16] VOLATILE '(anon)' type_id=17
195          [17] TYPEDEF 'my_struct_t' type_id=4
196          [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
197                  'arg1' type_id=1
198                  'arg2' type_id=3
199          [19] FUNC 'my_func' type_id=18
200          [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
201          [21] VAR 'global_var' type_id=3, linkage=global-alloc
202          [22] VAR 'my_func.static_var' type_id=3, linkage=static
203          [23] DATASEC 'data_sec' size=0 vlen=3
204                  type_id=20 offset=0 size=48
205                  type_id=21 offset=0 size=4
206                  type_id=22 offset=52 size=4
207
208       The following commands print BTF types associated with specified  map's
209       key, value, both key and value, and all BTF types, respectively. By de‐
210       fault, both key and value types will be printed.
211
212       # bpftool btf dump map id 123 key
213
214          [39] TYPEDEF 'u32' type_id=37
215
216       # bpftool btf dump map id 123 value
217
218          [86] PTR '(anon)' type_id=87
219
220       # bpftool btf dump map id 123 kv
221
222          [39] TYPEDEF 'u32' type_id=37
223          [86] PTR '(anon)' type_id=87
224
225       # bpftool btf dump map id 123 all
226
227          [1] PTR '(anon)' type_id=0
228          .
229          .
230          .
231          [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
232
233       All the standard ways to specify map or program are supported:
234
235       # bpftool btf dump map id 123
236
237       # bpftool btf dump map pinned /sys/fs/bpf/map_name
238
239       # bpftool btf dump prog id 456
240
241       # bpftool btf dump prog tag b88e0a09b1d9759d
242
243       # bpftool btf dump prog pinned /sys/fs/bpf/prog_name
244
245       # bpftool btf dump file /sys/kernel/btf/i2c_smbus
246       (or)
247       # I2C_SMBUS_ID=$(bpftool btf show -p | jq '.[] | select(.name=="i2c_smbus").id')
248       # bpftool btf dump id ${I2C_SMBUS_ID} -B /sys/kernel/btf/vmlinux
249
250
251          [104848] STRUCT 'i2c_smbus_alert' size=40 vlen=2
252                  'alert' type_id=393 bits_offset=0
253                  'ara' type_id=56050 bits_offset=256
254          [104849] STRUCT 'alert_data' size=12 vlen=3
255                  'addr' type_id=16 bits_offset=0
256                  'type' type_id=56053 bits_offset=32
257                  'data' type_id=7 bits_offset=64
258          [104850] PTR '(anon)' type_id=104848
259          [104851] PTR '(anon)' type_id=104849
260          [104852] FUNC 'i2c_register_spd' type_id=84745 linkage=static
261          [104853] FUNC 'smbalert_driver_init' type_id=1213 linkage=static
262          [104854] FUNC_PROTO '(anon)' ret_type_id=18 vlen=1
263                  'ara' type_id=56050
264          [104855] FUNC 'i2c_handle_smbus_alert' type_id=104854 linkage=static
265          [104856] FUNC 'smbalert_remove' type_id=104854 linkage=static
266          [104857] FUNC_PROTO '(anon)' ret_type_id=18 vlen=2
267                  'ara' type_id=56050
268                  'id' type_id=56056
269          [104858] FUNC 'smbalert_probe' type_id=104857 linkage=static
270          [104859] FUNC 'smbalert_work' type_id=9695 linkage=static
271          [104860] FUNC 'smbus_alert' type_id=71367 linkage=static
272          [104861] FUNC 'smbus_do_alert' type_id=84827 linkage=static
273

SEE ALSO

275          bpf(2), bpf-helpers(7), bpftool(8), bpftool-cgroup(8),  bpftool-fea‐
276          ture(8),     bpftool-gen(8),    bpftool-iter(8),    bpftool-link(8),
277          bpftool-map(8),  bpftool-net(8),  bpftool-perf(8),  bpftool-prog(8),
278          bpftool-struct_ops(8)
279
280
281
282
283                                                                BPFTOOL-BTF(8)
Impressum