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 }] | {-d | --debug } |
12                 { -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  version  number  (similar to bpftool version), and op‐
71                 tional features that were included when bpftool was compiled.
72                 Optional  features  include linking against libbfd to provide
73                 the disassembler for  JIT-ted  programs  (bpftool  prog  dump
74                 jited) and usage of BPF skeletons (some features like bpftool
75                 prog profile or showing pids associated to  BPF  objects  may
76                 rely on it).
77
78          -j, --json
79                 Generate  JSON output. For commands that cannot produce JSON,
80                 this option has no effect.
81
82          -p, --pretty
83                 Generate human-readable JSON output. Implies -j.
84
85          -d, --debug
86                 Print all logs available, even debug-level information.  This
87                 includes  logs from libbpf as well as from the verifier, when
88                 attempting to load programs.
89
90          -B, --base-btf FILE
91                 Pass a base BTF object. Base BTF objects are  typically  used
92                 with BTF objects for kernel modules. To avoid duplicating all
93                 kernel symbols required by modules, BTF objects  for  modules
94                 are  "split", they are built incrementally on top of the ker‐
95                 nel (vmlinux) BTF object. So the base  BTF  reference  should
96                 usually point to the kernel BTF.
97
98                 When  the main BTF object to process (for example, the module
99                 BTF to dump) is passed as a FILE, bpftool attempts to autode‐
100                 tect the path for the base object, and passing this option is
101                 optional. When the main BTF object is  passed  through  other
102                 handles, this option becomes necessary.
103

EXAMPLES

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

NAME

SYNOPSIS

BTF COMMANDS

DESCRIPTION

OPTIONS

EXAMPLES

SEE ALSO