Commit | Line | Data |
---|---|---|
ffcf7ce9 YS |
1 | ===================== |
2 | BPF Type Format (BTF) | |
3 | ===================== | |
4 | ||
5 | 1. Introduction | |
3ff36bff | 6 | =============== |
ffcf7ce9 | 7 | |
9ab5305d AN |
8 | BTF (BPF Type Format) is the metadata format which encodes the debug info |
9 | related to BPF program/map. The name BTF was used initially to describe data | |
10 | types. The BTF was later extended to include function info for defined | |
11 | subroutines, and line info for source/line information. | |
12 | ||
13 | The debug info is used for map pretty print, function signature, etc. The | |
14 | function signature enables better bpf program/function kernel symbol. The line | |
15 | info helps generate source annotated translated byte code, jited code and | |
16 | verifier log. | |
ffcf7ce9 YS |
17 | |
18 | The BTF specification contains two parts, | |
19 | * BTF kernel API | |
20 | * BTF ELF file format | |
21 | ||
9ab5305d AN |
22 | The kernel API is the contract between user space and kernel. The kernel |
23 | verifies the BTF info before using it. The ELF file format is a user space | |
24 | contract between ELF file and libbpf loader. | |
ffcf7ce9 | 25 | |
9ab5305d AN |
26 | The type and string sections are part of the BTF kernel API, describing the |
27 | debug info (mostly types related) referenced by the bpf program. These two | |
28 | sections are discussed in details in :ref:`BTF_Type_String`. | |
ffcf7ce9 YS |
29 | |
30 | .. _BTF_Type_String: | |
31 | ||
32 | 2. BTF Type and String Encoding | |
3ff36bff | 33 | =============================== |
ffcf7ce9 | 34 | |
9ab5305d AN |
35 | The file ``include/uapi/linux/btf.h`` provides high-level definition of how |
36 | types/strings are encoded. | |
ffcf7ce9 YS |
37 | |
38 | The beginning of data blob must be:: | |
39 | ||
40 | struct btf_header { | |
41 | __u16 magic; | |
42 | __u8 version; | |
43 | __u8 flags; | |
44 | __u32 hdr_len; | |
45 | ||
46 | /* All offsets are in bytes relative to the end of this header */ | |
47 | __u32 type_off; /* offset of type section */ | |
48 | __u32 type_len; /* length of type section */ | |
49 | __u32 str_off; /* offset of string section */ | |
50 | __u32 str_len; /* length of string section */ | |
51 | }; | |
52 | ||
53 | The magic is ``0xeB9F``, which has different encoding for big and little | |
9ab5305d AN |
54 | endian systems, and can be used to test whether BTF is generated for big- or |
55 | little-endian target. The ``btf_header`` is designed to be extensible with | |
56 | ``hdr_len`` equal to ``sizeof(struct btf_header)`` when a data blob is | |
57 | generated. | |
ffcf7ce9 YS |
58 | |
59 | 2.1 String Encoding | |
3ff36bff | 60 | ------------------- |
ffcf7ce9 | 61 | |
9ab5305d AN |
62 | The first string in the string section must be a null string. The rest of |
63 | string table is a concatenation of other null-terminated strings. | |
ffcf7ce9 YS |
64 | |
65 | 2.2 Type Encoding | |
3ff36bff | 66 | ----------------- |
ffcf7ce9 | 67 | |
9ab5305d AN |
68 | The type id ``0`` is reserved for ``void`` type. The type section is parsed |
69 | sequentially and type id is assigned to each recognized type starting from id | |
70 | ``1``. Currently, the following types are supported:: | |
ffcf7ce9 YS |
71 | |
72 | #define BTF_KIND_INT 1 /* Integer */ | |
73 | #define BTF_KIND_PTR 2 /* Pointer */ | |
74 | #define BTF_KIND_ARRAY 3 /* Array */ | |
75 | #define BTF_KIND_STRUCT 4 /* Struct */ | |
76 | #define BTF_KIND_UNION 5 /* Union */ | |
61dbd598 | 77 | #define BTF_KIND_ENUM 6 /* Enumeration up to 32-bit values */ |
ffcf7ce9 YS |
78 | #define BTF_KIND_FWD 7 /* Forward */ |
79 | #define BTF_KIND_TYPEDEF 8 /* Typedef */ | |
80 | #define BTF_KIND_VOLATILE 9 /* Volatile */ | |
81 | #define BTF_KIND_CONST 10 /* Const */ | |
82 | #define BTF_KIND_RESTRICT 11 /* Restrict */ | |
83 | #define BTF_KIND_FUNC 12 /* Function */ | |
84 | #define BTF_KIND_FUNC_PROTO 13 /* Function Proto */ | |
f063c889 DB |
85 | #define BTF_KIND_VAR 14 /* Variable */ |
86 | #define BTF_KIND_DATASEC 15 /* Section */ | |
6be6a0ba | 87 | #define BTF_KIND_FLOAT 16 /* Floating point */ |
223f903e | 88 | #define BTF_KIND_DECL_TAG 17 /* Decl Tag */ |
d52f5c63 | 89 | #define BTF_KIND_TYPE_TAG 18 /* Type Tag */ |
61dbd598 | 90 | #define BTF_KIND_ENUM64 19 /* Enumeration up to 64-bit values */ |
ffcf7ce9 YS |
91 | |
92 | Note that the type section encodes debug info, not just pure types. | |
93 | ``BTF_KIND_FUNC`` is not a type, and it represents a defined subprogram. | |
94 | ||
95 | Each type contains the following common data:: | |
96 | ||
97 | struct btf_type { | |
98 | __u32 name_off; | |
99 | /* "info" bits arrangement | |
100 | * bits 0-15: vlen (e.g. # of struct's members) | |
101 | * bits 16-23: unused | |
6be6a0ba IL |
102 | * bits 24-28: kind (e.g. int, ptr, array...etc) |
103 | * bits 29-30: unused | |
ffcf7ce9 | 104 | * bit 31: kind_flag, currently used by |
61dbd598 | 105 | * struct, union, fwd, enum and enum64. |
ffcf7ce9 YS |
106 | */ |
107 | __u32 info; | |
61dbd598 | 108 | /* "size" is used by INT, ENUM, STRUCT, UNION and ENUM64. |
ffcf7ce9 YS |
109 | * "size" tells the size of the type it is describing. |
110 | * | |
111 | * "type" is used by PTR, TYPEDEF, VOLATILE, CONST, RESTRICT, | |
d52f5c63 | 112 | * FUNC, FUNC_PROTO, DECL_TAG and TYPE_TAG. |
ffcf7ce9 YS |
113 | * "type" is a type_id referring to another type. |
114 | */ | |
115 | union { | |
116 | __u32 size; | |
117 | __u32 type; | |
118 | }; | |
119 | }; | |
120 | ||
9ab5305d AN |
121 | For certain kinds, the common data are followed by kind-specific data. The |
122 | ``name_off`` in ``struct btf_type`` specifies the offset in the string table. | |
123 | The following sections detail encoding of each kind. | |
ffcf7ce9 YS |
124 | |
125 | 2.2.1 BTF_KIND_INT | |
126 | ~~~~~~~~~~~~~~~~~~ | |
127 | ||
128 | ``struct btf_type`` encoding requirement: | |
129 | * ``name_off``: any valid offset | |
130 | * ``info.kind_flag``: 0 | |
131 | * ``info.kind``: BTF_KIND_INT | |
132 | * ``info.vlen``: 0 | |
133 | * ``size``: the size of the int type in bytes. | |
134 | ||
5efc529f | 135 | ``btf_type`` is followed by a ``u32`` with the following bits arrangement:: |
ffcf7ce9 YS |
136 | |
137 | #define BTF_INT_ENCODING(VAL) (((VAL) & 0x0f000000) >> 24) | |
948dc8c9 | 138 | #define BTF_INT_OFFSET(VAL) (((VAL) & 0x00ff0000) >> 16) |
ffcf7ce9 YS |
139 | #define BTF_INT_BITS(VAL) ((VAL) & 0x000000ff) |
140 | ||
141 | The ``BTF_INT_ENCODING`` has the following attributes:: | |
142 | ||
143 | #define BTF_INT_SIGNED (1 << 0) | |
144 | #define BTF_INT_CHAR (1 << 1) | |
145 | #define BTF_INT_BOOL (1 << 2) | |
146 | ||
9ab5305d AN |
147 | The ``BTF_INT_ENCODING()`` provides extra information: signedness, char, or |
148 | bool, for the int type. The char and bool encoding are mostly useful for | |
149 | pretty print. At most one encoding can be specified for the int type. | |
150 | ||
151 | The ``BTF_INT_BITS()`` specifies the number of actual bits held by this int | |
152 | type. For example, a 4-bit bitfield encodes ``BTF_INT_BITS()`` equals to 4. | |
153 | The ``btf_type.size * 8`` must be equal to or greater than ``BTF_INT_BITS()`` | |
154 | for the type. The maximum value of ``BTF_INT_BITS()`` is 128. | |
155 | ||
156 | The ``BTF_INT_OFFSET()`` specifies the starting bit offset to calculate values | |
f52c97d9 | 157 | for this int. For example, a bitfield struct member has: |
d857a3ff | 158 | |
f52c97d9 JDB |
159 | * btf member bit offset 100 from the start of the structure, |
160 | * btf member pointing to an int type, | |
161 | * the int type has ``BTF_INT_OFFSET() = 2`` and ``BTF_INT_BITS() = 4`` | |
ffcf7ce9 | 162 | |
9ab5305d AN |
163 | Then in the struct memory layout, this member will occupy ``4`` bits starting |
164 | from bits ``100 + 2 = 102``. | |
ffcf7ce9 | 165 | |
9ab5305d AN |
166 | Alternatively, the bitfield struct member can be the following to access the |
167 | same bits as the above: | |
d857a3ff | 168 | |
ffcf7ce9 YS |
169 | * btf member bit offset 102, |
170 | * btf member pointing to an int type, | |
171 | * the int type has ``BTF_INT_OFFSET() = 0`` and ``BTF_INT_BITS() = 4`` | |
172 | ||
9ab5305d AN |
173 | The original intention of ``BTF_INT_OFFSET()`` is to provide flexibility of |
174 | bitfield encoding. Currently, both llvm and pahole generate | |
175 | ``BTF_INT_OFFSET() = 0`` for all int types. | |
ffcf7ce9 YS |
176 | |
177 | 2.2.2 BTF_KIND_PTR | |
178 | ~~~~~~~~~~~~~~~~~~ | |
179 | ||
180 | ``struct btf_type`` encoding requirement: | |
181 | * ``name_off``: 0 | |
182 | * ``info.kind_flag``: 0 | |
183 | * ``info.kind``: BTF_KIND_PTR | |
184 | * ``info.vlen``: 0 | |
185 | * ``type``: the pointee type of the pointer | |
186 | ||
187 | No additional type data follow ``btf_type``. | |
188 | ||
189 | 2.2.3 BTF_KIND_ARRAY | |
190 | ~~~~~~~~~~~~~~~~~~~~ | |
191 | ||
192 | ``struct btf_type`` encoding requirement: | |
193 | * ``name_off``: 0 | |
194 | * ``info.kind_flag``: 0 | |
195 | * ``info.kind``: BTF_KIND_ARRAY | |
196 | * ``info.vlen``: 0 | |
197 | * ``size/type``: 0, not used | |
198 | ||
5efc529f | 199 | ``btf_type`` is followed by one ``struct btf_array``:: |
ffcf7ce9 YS |
200 | |
201 | struct btf_array { | |
202 | __u32 type; | |
203 | __u32 index_type; | |
204 | __u32 nelems; | |
205 | }; | |
206 | ||
207 | The ``struct btf_array`` encoding: | |
208 | * ``type``: the element type | |
209 | * ``index_type``: the index type | |
210 | * ``nelems``: the number of elements for this array (``0`` is also allowed). | |
211 | ||
9ab5305d AN |
212 | The ``index_type`` can be any regular int type (``u8``, ``u16``, ``u32``, |
213 | ``u64``, ``unsigned __int128``). The original design of including | |
214 | ``index_type`` follows DWARF, which has an ``index_type`` for its array type. | |
ffcf7ce9 YS |
215 | Currently in BTF, beyond type verification, the ``index_type`` is not used. |
216 | ||
217 | The ``struct btf_array`` allows chaining through element type to represent | |
9ab5305d AN |
218 | multidimensional arrays. For example, for ``int a[5][6]``, the following type |
219 | information illustrates the chaining: | |
ffcf7ce9 YS |
220 | |
221 | * [1]: int | |
222 | * [2]: array, ``btf_array.type = [1]``, ``btf_array.nelems = 6`` | |
223 | * [3]: array, ``btf_array.type = [2]``, ``btf_array.nelems = 5`` | |
224 | ||
9ab5305d AN |
225 | Currently, both pahole and llvm collapse multidimensional array into |
226 | one-dimensional array, e.g., for ``a[5][6]``, the ``btf_array.nelems`` is | |
227 | equal to ``30``. This is because the original use case is map pretty print | |
228 | where the whole array is dumped out so one-dimensional array is enough. As | |
229 | more BTF usage is explored, pahole and llvm can be changed to generate proper | |
230 | chained representation for multidimensional arrays. | |
ffcf7ce9 YS |
231 | |
232 | 2.2.4 BTF_KIND_STRUCT | |
233 | ~~~~~~~~~~~~~~~~~~~~~ | |
234 | 2.2.5 BTF_KIND_UNION | |
235 | ~~~~~~~~~~~~~~~~~~~~ | |
236 | ||
237 | ``struct btf_type`` encoding requirement: | |
238 | * ``name_off``: 0 or offset to a valid C identifier | |
239 | * ``info.kind_flag``: 0 or 1 | |
240 | * ``info.kind``: BTF_KIND_STRUCT or BTF_KIND_UNION | |
241 | * ``info.vlen``: the number of struct/union members | |
242 | * ``info.size``: the size of the struct/union in bytes | |
243 | ||
244 | ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_member``.:: | |
245 | ||
246 | struct btf_member { | |
247 | __u32 name_off; | |
248 | __u32 type; | |
249 | __u32 offset; | |
250 | }; | |
251 | ||
252 | ``struct btf_member`` encoding: | |
253 | * ``name_off``: offset to a valid C identifier | |
254 | * ``type``: the member type | |
255 | * ``offset``: <see below> | |
256 | ||
9ab5305d AN |
257 | If the type info ``kind_flag`` is not set, the offset contains only bit offset |
258 | of the member. Note that the base type of the bitfield can only be int or enum | |
259 | type. If the bitfield size is 32, the base type can be either int or enum | |
260 | type. If the bitfield size is not 32, the base type must be int, and int type | |
261 | ``BTF_INT_BITS()`` encodes the bitfield size. | |
ffcf7ce9 | 262 | |
9ab5305d AN |
263 | If the ``kind_flag`` is set, the ``btf_member.offset`` contains both member |
264 | bitfield size and bit offset. The bitfield size and bit offset are calculated | |
265 | as below.:: | |
ffcf7ce9 YS |
266 | |
267 | #define BTF_MEMBER_BITFIELD_SIZE(val) ((val) >> 24) | |
268 | #define BTF_MEMBER_BIT_OFFSET(val) ((val) & 0xffffff) | |
269 | ||
9ab5305d | 270 | In this case, if the base type is an int type, it must be a regular int type: |
ffcf7ce9 YS |
271 | |
272 | * ``BTF_INT_OFFSET()`` must be 0. | |
273 | * ``BTF_INT_BITS()`` must be equal to ``{1,2,4,8,16} * 8``. | |
274 | ||
86b17aaf VN |
275 | Commit 9d5f9f701b18 introduced ``kind_flag`` and explains why both modes |
276 | exist. | |
ffcf7ce9 YS |
277 | |
278 | 2.2.6 BTF_KIND_ENUM | |
279 | ~~~~~~~~~~~~~~~~~~~ | |
280 | ||
281 | ``struct btf_type`` encoding requirement: | |
282 | * ``name_off``: 0 or offset to a valid C identifier | |
61dbd598 | 283 | * ``info.kind_flag``: 0 for unsigned, 1 for signed |
ffcf7ce9 YS |
284 | * ``info.kind``: BTF_KIND_ENUM |
285 | * ``info.vlen``: number of enum values | |
61dbd598 | 286 | * ``size``: 1/2/4/8 |
ffcf7ce9 YS |
287 | |
288 | ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_enum``.:: | |
289 | ||
290 | struct btf_enum { | |
291 | __u32 name_off; | |
292 | __s32 val; | |
293 | }; | |
294 | ||
295 | The ``btf_enum`` encoding: | |
296 | * ``name_off``: offset to a valid C identifier | |
297 | * ``val``: any value | |
298 | ||
61dbd598 YS |
299 | If the original enum value is signed and the size is less than 4, |
300 | that value will be sign extended into 4 bytes. If the size is 8, | |
301 | the value will be truncated into 4 bytes. | |
302 | ||
ffcf7ce9 YS |
303 | 2.2.7 BTF_KIND_FWD |
304 | ~~~~~~~~~~~~~~~~~~ | |
305 | ||
306 | ``struct btf_type`` encoding requirement: | |
307 | * ``name_off``: offset to a valid C identifier | |
308 | * ``info.kind_flag``: 0 for struct, 1 for union | |
309 | * ``info.kind``: BTF_KIND_FWD | |
310 | * ``info.vlen``: 0 | |
311 | * ``type``: 0 | |
312 | ||
313 | No additional type data follow ``btf_type``. | |
314 | ||
315 | 2.2.8 BTF_KIND_TYPEDEF | |
316 | ~~~~~~~~~~~~~~~~~~~~~~ | |
317 | ||
318 | ``struct btf_type`` encoding requirement: | |
319 | * ``name_off``: offset to a valid C identifier | |
320 | * ``info.kind_flag``: 0 | |
321 | * ``info.kind``: BTF_KIND_TYPEDEF | |
322 | * ``info.vlen``: 0 | |
323 | * ``type``: the type which can be referred by name at ``name_off`` | |
324 | ||
325 | No additional type data follow ``btf_type``. | |
326 | ||
327 | 2.2.9 BTF_KIND_VOLATILE | |
328 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
329 | ||
330 | ``struct btf_type`` encoding requirement: | |
331 | * ``name_off``: 0 | |
332 | * ``info.kind_flag``: 0 | |
333 | * ``info.kind``: BTF_KIND_VOLATILE | |
334 | * ``info.vlen``: 0 | |
335 | * ``type``: the type with ``volatile`` qualifier | |
336 | ||
337 | No additional type data follow ``btf_type``. | |
338 | ||
339 | 2.2.10 BTF_KIND_CONST | |
340 | ~~~~~~~~~~~~~~~~~~~~~ | |
341 | ||
342 | ``struct btf_type`` encoding requirement: | |
343 | * ``name_off``: 0 | |
344 | * ``info.kind_flag``: 0 | |
345 | * ``info.kind``: BTF_KIND_CONST | |
346 | * ``info.vlen``: 0 | |
347 | * ``type``: the type with ``const`` qualifier | |
348 | ||
349 | No additional type data follow ``btf_type``. | |
350 | ||
351 | 2.2.11 BTF_KIND_RESTRICT | |
352 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
353 | ||
354 | ``struct btf_type`` encoding requirement: | |
355 | * ``name_off``: 0 | |
356 | * ``info.kind_flag``: 0 | |
357 | * ``info.kind``: BTF_KIND_RESTRICT | |
358 | * ``info.vlen``: 0 | |
359 | * ``type``: the type with ``restrict`` qualifier | |
360 | ||
361 | No additional type data follow ``btf_type``. | |
362 | ||
363 | 2.2.12 BTF_KIND_FUNC | |
364 | ~~~~~~~~~~~~~~~~~~~~ | |
365 | ||
366 | ``struct btf_type`` encoding requirement: | |
367 | * ``name_off``: offset to a valid C identifier | |
368 | * ``info.kind_flag``: 0 | |
369 | * ``info.kind``: BTF_KIND_FUNC | |
e5e23424 | 370 | * ``info.vlen``: linkage information (BTF_FUNC_STATIC, BTF_FUNC_GLOBAL |
c229c17a | 371 | or BTF_FUNC_EXTERN - see :ref:`BTF_Function_Linkage_Constants`) |
ffcf7ce9 YS |
372 | * ``type``: a BTF_KIND_FUNC_PROTO type |
373 | ||
374 | No additional type data follow ``btf_type``. | |
375 | ||
5efc529f | 376 | A BTF_KIND_FUNC defines not a type, but a subprogram (function) whose |
9ab5305d AN |
377 | signature is defined by ``type``. The subprogram is thus an instance of that |
378 | type. The BTF_KIND_FUNC may in turn be referenced by a func_info in the | |
379 | :ref:`BTF_Ext_Section` (ELF) or in the arguments to :ref:`BPF_Prog_Load` | |
380 | (ABI). | |
ffcf7ce9 | 381 | |
e5e23424 IB |
382 | Currently, only linkage values of BTF_FUNC_STATIC and BTF_FUNC_GLOBAL are |
383 | supported in the kernel. | |
384 | ||
ffcf7ce9 YS |
385 | 2.2.13 BTF_KIND_FUNC_PROTO |
386 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
387 | ||
388 | ``struct btf_type`` encoding requirement: | |
389 | * ``name_off``: 0 | |
390 | * ``info.kind_flag``: 0 | |
391 | * ``info.kind``: BTF_KIND_FUNC_PROTO | |
392 | * ``info.vlen``: # of parameters | |
393 | * ``type``: the return type | |
394 | ||
395 | ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_param``.:: | |
396 | ||
397 | struct btf_param { | |
398 | __u32 name_off; | |
399 | __u32 type; | |
400 | }; | |
401 | ||
9ab5305d AN |
402 | If a BTF_KIND_FUNC_PROTO type is referred by a BTF_KIND_FUNC type, then |
403 | ``btf_param.name_off`` must point to a valid C identifier except for the | |
404 | possible last argument representing the variable argument. The btf_param.type | |
405 | refers to parameter type. | |
ffcf7ce9 | 406 | |
9ab5305d AN |
407 | If the function has variable arguments, the last parameter is encoded with |
408 | ``name_off = 0`` and ``type = 0``. | |
ffcf7ce9 | 409 | |
f063c889 DB |
410 | 2.2.14 BTF_KIND_VAR |
411 | ~~~~~~~~~~~~~~~~~~~ | |
412 | ||
413 | ``struct btf_type`` encoding requirement: | |
414 | * ``name_off``: offset to a valid C identifier | |
415 | * ``info.kind_flag``: 0 | |
416 | * ``info.kind``: BTF_KIND_VAR | |
417 | * ``info.vlen``: 0 | |
418 | * ``type``: the type of the variable | |
419 | ||
420 | ``btf_type`` is followed by a single ``struct btf_variable`` with the | |
421 | following data:: | |
422 | ||
423 | struct btf_var { | |
424 | __u32 linkage; | |
425 | }; | |
426 | ||
c229c17a WH |
427 | ``btf_var.linkage`` may take the values: BTF_VAR_STATIC, BTF_VAR_GLOBAL_ALLOCATED or BTF_VAR_GLOBAL_EXTERN - |
428 | see :ref:`BTF_Var_Linkage_Constants`. | |
f063c889 DB |
429 | |
430 | Not all type of global variables are supported by LLVM at this point. | |
431 | The following is currently available: | |
432 | ||
433 | * static variables with or without section attributes | |
434 | * global variables with section attributes | |
435 | ||
436 | The latter is for future extraction of map key/value type id's from a | |
437 | map definition. | |
438 | ||
439 | 2.2.15 BTF_KIND_DATASEC | |
440 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
441 | ||
442 | ``struct btf_type`` encoding requirement: | |
443 | * ``name_off``: offset to a valid name associated with a variable or | |
444 | one of .data/.bss/.rodata | |
445 | * ``info.kind_flag``: 0 | |
446 | * ``info.kind``: BTF_KIND_DATASEC | |
447 | * ``info.vlen``: # of variables | |
448 | * ``size``: total section size in bytes (0 at compilation time, patched | |
449 | to actual size by BPF loaders such as libbpf) | |
450 | ||
451 | ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_var_secinfo``.:: | |
452 | ||
453 | struct btf_var_secinfo { | |
454 | __u32 type; | |
455 | __u32 offset; | |
456 | __u32 size; | |
457 | }; | |
458 | ||
459 | ``struct btf_var_secinfo`` encoding: | |
460 | * ``type``: the type of the BTF_KIND_VAR variable | |
461 | * ``offset``: the in-section offset of the variable | |
462 | * ``size``: the size of the variable in bytes | |
463 | ||
6be6a0ba IL |
464 | 2.2.16 BTF_KIND_FLOAT |
465 | ~~~~~~~~~~~~~~~~~~~~~ | |
466 | ||
467 | ``struct btf_type`` encoding requirement: | |
468 | * ``name_off``: any valid offset | |
469 | * ``info.kind_flag``: 0 | |
470 | * ``info.kind``: BTF_KIND_FLOAT | |
471 | * ``info.vlen``: 0 | |
472 | * ``size``: the size of the float type in bytes: 2, 4, 8, 12 or 16. | |
473 | ||
474 | No additional type data follow ``btf_type``. | |
475 | ||
223f903e YS |
476 | 2.2.17 BTF_KIND_DECL_TAG |
477 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
48f5a6c4 YS |
478 | |
479 | ``struct btf_type`` encoding requirement: | |
480 | * ``name_off``: offset to a non-empty string | |
481 | * ``info.kind_flag``: 0 | |
223f903e | 482 | * ``info.kind``: BTF_KIND_DECL_TAG |
48f5a6c4 | 483 | * ``info.vlen``: 0 |
5a867134 | 484 | * ``type``: ``struct``, ``union``, ``func``, ``var`` or ``typedef`` |
48f5a6c4 | 485 | |
223f903e | 486 | ``btf_type`` is followed by ``struct btf_decl_tag``.:: |
48f5a6c4 | 487 | |
223f903e | 488 | struct btf_decl_tag { |
48f5a6c4 YS |
489 | __u32 component_idx; |
490 | }; | |
491 | ||
223f903e | 492 | The ``name_off`` encodes btf_decl_tag attribute string. |
5a867134 YS |
493 | The ``type`` should be ``struct``, ``union``, ``func``, ``var`` or ``typedef``. |
494 | For ``var`` or ``typedef`` type, ``btf_decl_tag.component_idx`` must be ``-1``. | |
223f903e | 495 | For the other three types, if the btf_decl_tag attribute is |
48f5a6c4 | 496 | applied to the ``struct``, ``union`` or ``func`` itself, |
223f903e | 497 | ``btf_decl_tag.component_idx`` must be ``-1``. Otherwise, |
48f5a6c4 | 498 | the attribute is applied to a ``struct``/``union`` member or |
223f903e | 499 | a ``func`` argument, and ``btf_decl_tag.component_idx`` should be a |
48f5a6c4 YS |
500 | valid index (starting from 0) pointing to a member or an argument. |
501 | ||
61dbd598 | 502 | 2.2.18 BTF_KIND_TYPE_TAG |
d52f5c63 YS |
503 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
504 | ||
505 | ``struct btf_type`` encoding requirement: | |
506 | * ``name_off``: offset to a non-empty string | |
507 | * ``info.kind_flag``: 0 | |
508 | * ``info.kind``: BTF_KIND_TYPE_TAG | |
509 | * ``info.vlen``: 0 | |
510 | * ``type``: the type with ``btf_type_tag`` attribute | |
511 | ||
b7290384 YS |
512 | Currently, ``BTF_KIND_TYPE_TAG`` is only emitted for pointer types. |
513 | It has the following btf type chain: | |
514 | :: | |
515 | ||
516 | ptr -> [type_tag]* | |
517 | -> [const | volatile | restrict | typedef]* | |
518 | -> base_type | |
519 | ||
520 | Basically, a pointer type points to zero or more | |
521 | type_tag, then zero or more const/volatile/restrict/typedef | |
522 | and finally the base type. The base type is one of | |
523 | int, ptr, array, struct, union, enum, func_proto and float types. | |
524 | ||
61dbd598 YS |
525 | 2.2.19 BTF_KIND_ENUM64 |
526 | ~~~~~~~~~~~~~~~~~~~~~~ | |
527 | ||
528 | ``struct btf_type`` encoding requirement: | |
529 | * ``name_off``: 0 or offset to a valid C identifier | |
530 | * ``info.kind_flag``: 0 for unsigned, 1 for signed | |
531 | * ``info.kind``: BTF_KIND_ENUM64 | |
532 | * ``info.vlen``: number of enum values | |
533 | * ``size``: 1/2/4/8 | |
534 | ||
535 | ``btf_type`` is followed by ``info.vlen`` number of ``struct btf_enum64``.:: | |
536 | ||
537 | struct btf_enum64 { | |
538 | __u32 name_off; | |
539 | __u32 val_lo32; | |
540 | __u32 val_hi32; | |
541 | }; | |
542 | ||
543 | The ``btf_enum64`` encoding: | |
544 | * ``name_off``: offset to a valid C identifier | |
545 | * ``val_lo32``: lower 32-bit value for a 64-bit value | |
546 | * ``val_hi32``: high 32-bit value for a 64-bit value | |
547 | ||
548 | If the original enum value is signed and the size is less than 8, | |
549 | that value will be sign extended into 8 bytes. | |
550 | ||
c229c17a WH |
551 | 2.3 Constant Values |
552 | ------------------- | |
553 | ||
554 | .. _BTF_Function_Linkage_Constants: | |
555 | ||
556 | 2.3.1 Function Linkage Constant Values | |
557 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
558 | .. table:: Function Linkage Values and Meanings | |
559 | ||
560 | =================== ===== =========== | |
561 | kind value description | |
562 | =================== ===== =========== | |
563 | ``BTF_FUNC_STATIC`` 0x0 definition of subprogram not visible outside containing compilation unit | |
564 | ``BTF_FUNC_GLOBAL`` 0x1 definition of subprogram visible outside containing compilation unit | |
565 | ``BTF_FUNC_EXTERN`` 0x2 declaration of a subprogram whose definition is outside the containing compilation unit | |
566 | =================== ===== =========== | |
567 | ||
568 | ||
569 | .. _BTF_Var_Linkage_Constants: | |
570 | ||
571 | 2.3.2 Variable Linkage Constant Values | |
572 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
573 | .. table:: Variable Linkage Values and Meanings | |
574 | ||
575 | ============================ ===== =========== | |
576 | kind value description | |
577 | ============================ ===== =========== | |
578 | ``BTF_VAR_STATIC`` 0x0 definition of global variable not visible outside containing compilation unit | |
579 | ``BTF_VAR_GLOBAL_ALLOCATED`` 0x1 definition of global variable visible outside containing compilation unit | |
580 | ``BTF_VAR_GLOBAL_EXTERN`` 0x2 declaration of global variable whose definition is outside the containing compilation unit | |
581 | ============================ ===== =========== | |
582 | ||
ffcf7ce9 | 583 | 3. BTF Kernel API |
3ff36bff | 584 | ================= |
ffcf7ce9 YS |
585 | |
586 | The following bpf syscall command involves BTF: | |
587 | * BPF_BTF_LOAD: load a blob of BTF data into kernel | |
588 | * BPF_MAP_CREATE: map creation with btf key and value type info. | |
589 | * BPF_PROG_LOAD: prog load with btf function and line info. | |
590 | * BPF_BTF_GET_FD_BY_ID: get a btf fd | |
591 | * BPF_OBJ_GET_INFO_BY_FD: btf, func_info, line_info | |
592 | and other btf related info are returned. | |
593 | ||
594 | The workflow typically looks like: | |
595 | :: | |
596 | ||
597 | Application: | |
598 | BPF_BTF_LOAD | |
599 | | | |
600 | v | |
601 | BPF_MAP_CREATE and BPF_PROG_LOAD | |
602 | | | |
603 | V | |
604 | ...... | |
605 | ||
606 | Introspection tool: | |
607 | ...... | |
608 | BPF_{PROG,MAP}_GET_NEXT_ID (get prog/map id's) | |
609 | | | |
610 | V | |
611 | BPF_{PROG,MAP}_GET_FD_BY_ID (get a prog/map fd) | |
612 | | | |
613 | V | |
614 | BPF_OBJ_GET_INFO_BY_FD (get bpf_prog_info/bpf_map_info with btf_id) | |
615 | | | | |
616 | V | | |
617 | BPF_BTF_GET_FD_BY_ID (get btf_fd) | | |
618 | | | | |
619 | V | | |
620 | BPF_OBJ_GET_INFO_BY_FD (get btf) | | |
621 | | | | |
622 | V V | |
623 | pretty print types, dump func signatures and line info, etc. | |
624 | ||
625 | ||
626 | 3.1 BPF_BTF_LOAD | |
3ff36bff | 627 | ---------------- |
ffcf7ce9 | 628 | |
9ab5305d AN |
629 | Load a blob of BTF data into kernel. A blob of data, described in |
630 | :ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd`` | |
631 | is returned to a userspace. | |
ffcf7ce9 YS |
632 | |
633 | 3.2 BPF_MAP_CREATE | |
3ff36bff | 634 | ------------------ |
ffcf7ce9 YS |
635 | |
636 | A map can be created with ``btf_fd`` and specified key/value type id.:: | |
637 | ||
638 | __u32 btf_fd; /* fd pointing to a BTF type data */ | |
639 | __u32 btf_key_type_id; /* BTF type_id of the key */ | |
640 | __u32 btf_value_type_id; /* BTF type_id of the value */ | |
641 | ||
642 | In libbpf, the map can be defined with extra annotation like below: | |
643 | :: | |
644 | ||
96c85308 AN |
645 | struct { |
646 | __uint(type, BPF_MAP_TYPE_ARRAY); | |
647 | __type(key, int); | |
648 | __type(value, struct ipv_counts); | |
649 | __uint(max_entries, 4); | |
650 | } btf_map SEC(".maps"); | |
ffcf7ce9 | 651 | |
96c85308 AN |
652 | During ELF parsing, libbpf is able to extract key/value type_id's and assign |
653 | them to BPF_MAP_CREATE attributes automatically. | |
ffcf7ce9 YS |
654 | |
655 | .. _BPF_Prog_Load: | |
656 | ||
657 | 3.3 BPF_PROG_LOAD | |
3ff36bff | 658 | ----------------- |
ffcf7ce9 | 659 | |
9ab5305d AN |
660 | During prog_load, func_info and line_info can be passed to kernel with proper |
661 | values for the following attributes: | |
ffcf7ce9 YS |
662 | :: |
663 | ||
664 | __u32 insn_cnt; | |
665 | __aligned_u64 insns; | |
666 | ...... | |
667 | __u32 prog_btf_fd; /* fd pointing to BTF type data */ | |
668 | __u32 func_info_rec_size; /* userspace bpf_func_info size */ | |
669 | __aligned_u64 func_info; /* func info */ | |
670 | __u32 func_info_cnt; /* number of bpf_func_info records */ | |
671 | __u32 line_info_rec_size; /* userspace bpf_line_info size */ | |
672 | __aligned_u64 line_info; /* line info */ | |
673 | __u32 line_info_cnt; /* number of bpf_line_info records */ | |
674 | ||
675 | The func_info and line_info are an array of below, respectively.:: | |
676 | ||
677 | struct bpf_func_info { | |
678 | __u32 insn_off; /* [0, insn_cnt - 1] */ | |
679 | __u32 type_id; /* pointing to a BTF_KIND_FUNC type */ | |
680 | }; | |
681 | struct bpf_line_info { | |
682 | __u32 insn_off; /* [0, insn_cnt - 1] */ | |
683 | __u32 file_name_off; /* offset to string table for the filename */ | |
684 | __u32 line_off; /* offset to string table for the source line */ | |
685 | __u32 line_col; /* line number and column number */ | |
686 | }; | |
687 | ||
9ab5305d AN |
688 | func_info_rec_size is the size of each func_info record, and |
689 | line_info_rec_size is the size of each line_info record. Passing the record | |
690 | size to kernel make it possible to extend the record itself in the future. | |
ffcf7ce9 YS |
691 | |
692 | Below are requirements for func_info: | |
693 | * func_info[0].insn_off must be 0. | |
694 | * the func_info insn_off is in strictly increasing order and matches | |
695 | bpf func boundaries. | |
696 | ||
697 | Below are requirements for line_info: | |
5efc529f | 698 | * the first insn in each func must have a line_info record pointing to it. |
ffcf7ce9 YS |
699 | * the line_info insn_off is in strictly increasing order. |
700 | ||
701 | For line_info, the line number and column number are defined as below: | |
702 | :: | |
703 | ||
704 | #define BPF_LINE_INFO_LINE_NUM(line_col) ((line_col) >> 10) | |
705 | #define BPF_LINE_INFO_LINE_COL(line_col) ((line_col) & 0x3ff) | |
706 | ||
707 | 3.4 BPF_{PROG,MAP}_GET_NEXT_ID | |
3ff36bff | 708 | ------------------------------ |
ffcf7ce9 | 709 | |
9ab5305d AN |
710 | In kernel, every loaded program, map or btf has a unique id. The id won't |
711 | change during the lifetime of a program, map, or btf. | |
ffcf7ce9 | 712 | |
9ab5305d AN |
713 | The bpf syscall command BPF_{PROG,MAP}_GET_NEXT_ID returns all id's, one for |
714 | each command, to user space, for bpf program or maps, respectively, so an | |
715 | inspection tool can inspect all programs and maps. | |
ffcf7ce9 YS |
716 | |
717 | 3.5 BPF_{PROG,MAP}_GET_FD_BY_ID | |
3ff36bff | 718 | ------------------------------- |
ffcf7ce9 | 719 | |
5efc529f AN |
720 | An introspection tool cannot use id to get details about program or maps. |
721 | A file descriptor needs to be obtained first for reference-counting purpose. | |
ffcf7ce9 YS |
722 | |
723 | 3.6 BPF_OBJ_GET_INFO_BY_FD | |
3ff36bff | 724 | -------------------------- |
ffcf7ce9 | 725 | |
9ab5305d AN |
726 | Once a program/map fd is acquired, an introspection tool can get the detailed |
727 | information from kernel about this fd, some of which are BTF-related. For | |
728 | example, ``bpf_map_info`` returns ``btf_id`` and key/value type ids. | |
729 | ``bpf_prog_info`` returns ``btf_id``, func_info, and line info for translated | |
730 | bpf byte codes, and jited_line_info. | |
ffcf7ce9 YS |
731 | |
732 | 3.7 BPF_BTF_GET_FD_BY_ID | |
3ff36bff | 733 | ------------------------ |
ffcf7ce9 | 734 | |
9ab5305d AN |
735 | With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf |
736 | syscall command BPF_BTF_GET_FD_BY_ID can retrieve a btf fd. Then, with | |
737 | command BPF_OBJ_GET_INFO_BY_FD, the btf blob, originally loaded into the | |
738 | kernel with BPF_BTF_LOAD, can be retrieved. | |
ffcf7ce9 | 739 | |
5efc529f | 740 | With the btf blob, ``bpf_map_info``, and ``bpf_prog_info``, an introspection |
9ab5305d AN |
741 | tool has full btf knowledge and is able to pretty print map key/values, dump |
742 | func signatures and line info, along with byte/jit codes. | |
ffcf7ce9 YS |
743 | |
744 | 4. ELF File Format Interface | |
3ff36bff | 745 | ============================ |
ffcf7ce9 YS |
746 | |
747 | 4.1 .BTF section | |
3ff36bff | 748 | ---------------- |
ffcf7ce9 | 749 | |
9ab5305d AN |
750 | The .BTF section contains type and string data. The format of this section is |
751 | same as the one describe in :ref:`BTF_Type_String`. | |
ffcf7ce9 YS |
752 | |
753 | .. _BTF_Ext_Section: | |
754 | ||
755 | 4.2 .BTF.ext section | |
3ff36bff | 756 | -------------------- |
ffcf7ce9 | 757 | |
be4033d3 EZ |
758 | The .BTF.ext section encodes func_info, line_info and CO-RE relocations |
759 | which needs loader manipulation before loading into the kernel. | |
ffcf7ce9 | 760 | |
9ab5305d AN |
761 | The specification for .BTF.ext section is defined at ``tools/lib/bpf/btf.h`` |
762 | and ``tools/lib/bpf/btf.c``. | |
ffcf7ce9 YS |
763 | |
764 | The current header of .BTF.ext section:: | |
765 | ||
766 | struct btf_ext_header { | |
767 | __u16 magic; | |
768 | __u8 version; | |
769 | __u8 flags; | |
770 | __u32 hdr_len; | |
771 | ||
772 | /* All offsets are in bytes relative to the end of this header */ | |
773 | __u32 func_info_off; | |
774 | __u32 func_info_len; | |
775 | __u32 line_info_off; | |
776 | __u32 line_info_len; | |
be4033d3 EZ |
777 | |
778 | /* optional part of .BTF.ext header */ | |
779 | __u32 core_relo_off; | |
780 | __u32 core_relo_len; | |
ffcf7ce9 YS |
781 | }; |
782 | ||
9ab5305d | 783 | It is very similar to .BTF section. Instead of type/string section, it |
be4033d3 EZ |
784 | contains func_info, line_info and core_relo sub-sections. |
785 | See :ref:`BPF_Prog_Load` for details about func_info and line_info | |
786 | record format. | |
ffcf7ce9 YS |
787 | |
788 | The func_info is organized as below.:: | |
789 | ||
be4033d3 | 790 | func_info_rec_size /* __u32 value */ |
ffcf7ce9 YS |
791 | btf_ext_info_sec for section #1 /* func_info for section #1 */ |
792 | btf_ext_info_sec for section #2 /* func_info for section #2 */ | |
793 | ... | |
794 | ||
9ab5305d AN |
795 | ``func_info_rec_size`` specifies the size of ``bpf_func_info`` structure when |
796 | .BTF.ext is generated. ``btf_ext_info_sec``, defined below, is a collection of | |
797 | func_info for each specific ELF section.:: | |
ffcf7ce9 YS |
798 | |
799 | struct btf_ext_info_sec { | |
800 | __u32 sec_name_off; /* offset to section name */ | |
801 | __u32 num_info; | |
802 | /* Followed by num_info * record_size number of bytes */ | |
803 | __u8 data[0]; | |
804 | }; | |
805 | ||
806 | Here, num_info must be greater than 0. | |
807 | ||
808 | The line_info is organized as below.:: | |
809 | ||
be4033d3 | 810 | line_info_rec_size /* __u32 value */ |
ffcf7ce9 YS |
811 | btf_ext_info_sec for section #1 /* line_info for section #1 */ |
812 | btf_ext_info_sec for section #2 /* line_info for section #2 */ | |
813 | ... | |
814 | ||
9ab5305d AN |
815 | ``line_info_rec_size`` specifies the size of ``bpf_line_info`` structure when |
816 | .BTF.ext is generated. | |
ffcf7ce9 YS |
817 | |
818 | The interpretation of ``bpf_func_info->insn_off`` and | |
9ab5305d AN |
819 | ``bpf_line_info->insn_off`` is different between kernel API and ELF API. For |
820 | kernel API, the ``insn_off`` is the instruction offset in the unit of ``struct | |
821 | bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the | |
822 | beginning of section (``btf_ext_info_sec->sec_name_off``). | |
ffcf7ce9 | 823 | |
be4033d3 EZ |
824 | The core_relo is organized as below.:: |
825 | ||
826 | core_relo_rec_size /* __u32 value */ | |
827 | btf_ext_info_sec for section #1 /* core_relo for section #1 */ | |
828 | btf_ext_info_sec for section #2 /* core_relo for section #2 */ | |
829 | ||
830 | ``core_relo_rec_size`` specifies the size of ``bpf_core_relo`` | |
831 | structure when .BTF.ext is generated. All ``bpf_core_relo`` structures | |
832 | within a single ``btf_ext_info_sec`` describe relocations applied to | |
833 | section named by ``btf_ext_info_sec->sec_name_off``. | |
834 | ||
3888fa13 | 835 | See :ref:`Documentation/bpf/llvm_reloc.rst <btf-co-re-relocations>` |
be4033d3 EZ |
836 | for more information on CO-RE relocations. |
837 | ||
232ce4be | 838 | 4.2 .BTF_ids section |
3ff36bff | 839 | -------------------- |
232ce4be JO |
840 | |
841 | The .BTF_ids section encodes BTF ID values that are used within the kernel. | |
842 | ||
843 | This section is created during the kernel compilation with the help of | |
844 | macros defined in ``include/linux/btf_ids.h`` header file. Kernel code can | |
845 | use them to create lists and sets (sorted lists) of BTF ID values. | |
846 | ||
847 | The ``BTF_ID_LIST`` and ``BTF_ID`` macros define unsorted list of BTF ID values, | |
848 | with following syntax:: | |
849 | ||
850 | BTF_ID_LIST(list) | |
851 | BTF_ID(type1, name1) | |
852 | BTF_ID(type2, name2) | |
853 | ||
854 | resulting in following layout in .BTF_ids section:: | |
855 | ||
856 | __BTF_ID__type1__name1__1: | |
857 | .zero 4 | |
858 | __BTF_ID__type2__name2__2: | |
859 | .zero 4 | |
860 | ||
861 | The ``u32 list[];`` variable is defined to access the list. | |
862 | ||
863 | The ``BTF_ID_UNUSED`` macro defines 4 zero bytes. It's used when we | |
864 | want to define unused entry in BTF_ID_LIST, like:: | |
865 | ||
866 | BTF_ID_LIST(bpf_skb_output_btf_ids) | |
867 | BTF_ID(struct, sk_buff) | |
868 | BTF_ID_UNUSED | |
869 | BTF_ID(struct, task_struct) | |
870 | ||
68a26bc7 JO |
871 | The ``BTF_SET_START/END`` macros pair defines sorted list of BTF ID values |
872 | and their count, with following syntax:: | |
873 | ||
874 | BTF_SET_START(set) | |
875 | BTF_ID(type1, name1) | |
876 | BTF_ID(type2, name2) | |
877 | BTF_SET_END(set) | |
878 | ||
879 | resulting in following layout in .BTF_ids section:: | |
880 | ||
881 | __BTF_ID__set__set: | |
882 | .zero 4 | |
883 | __BTF_ID__type1__name1__3: | |
884 | .zero 4 | |
885 | __BTF_ID__type2__name2__4: | |
886 | .zero 4 | |
887 | ||
888 | The ``struct btf_id_set set;`` variable is defined to access the list. | |
889 | ||
890 | The ``typeX`` name can be one of following:: | |
891 | ||
892 | struct, union, typedef, func | |
893 | ||
894 | and is used as a filter when resolving the BTF ID value. | |
895 | ||
232ce4be JO |
896 | All the BTF ID lists and sets are compiled in the .BTF_ids section and |
897 | resolved during the linking phase of kernel build by ``resolve_btfids`` tool. | |
898 | ||
ffcf7ce9 | 899 | 5. Using BTF |
3ff36bff | 900 | ============ |
ffcf7ce9 YS |
901 | |
902 | 5.1 bpftool map pretty print | |
3ff36bff | 903 | ---------------------------- |
ffcf7ce9 | 904 | |
9ab5305d AN |
905 | With BTF, the map key/value can be printed based on fields rather than simply |
906 | raw bytes. This is especially valuable for large structure or if your data | |
907 | structure has bitfields. For example, for the following map,:: | |
ffcf7ce9 YS |
908 | |
909 | enum A { A1, A2, A3, A4, A5 }; | |
910 | typedef enum A ___A; | |
911 | struct tmp_t { | |
912 | char a1:4; | |
913 | int a2:4; | |
914 | int :4; | |
915 | __u32 a3:4; | |
916 | int b; | |
917 | ___A b1:4; | |
918 | enum A b2:4; | |
919 | }; | |
96c85308 AN |
920 | struct { |
921 | __uint(type, BPF_MAP_TYPE_ARRAY); | |
922 | __type(key, int); | |
923 | __type(value, struct tmp_t); | |
924 | __uint(max_entries, 1); | |
925 | } tmpmap SEC(".maps"); | |
ffcf7ce9 YS |
926 | |
927 | bpftool is able to pretty print like below: | |
928 | :: | |
929 | ||
930 | [{ | |
931 | "key": 0, | |
932 | "value": { | |
933 | "a1": 0x2, | |
934 | "a2": 0x4, | |
935 | "a3": 0x6, | |
936 | "b": 7, | |
937 | "b1": 0x8, | |
938 | "b2": 0xa | |
939 | } | |
940 | } | |
941 | ] | |
942 | ||
943 | 5.2 bpftool prog dump | |
3ff36bff | 944 | --------------------- |
ffcf7ce9 | 945 | |
9ab5305d AN |
946 | The following is an example showing how func_info and line_info can help prog |
947 | dump with better kernel symbol names, function prototypes and line | |
948 | information.:: | |
ffcf7ce9 YS |
949 | |
950 | $ bpftool prog dump jited pinned /sys/fs/bpf/test_btf_haskv | |
951 | [...] | |
952 | int test_long_fname_2(struct dummy_tracepoint_args * arg): | |
953 | bpf_prog_44a040bf25481309_test_long_fname_2: | |
954 | ; static int test_long_fname_2(struct dummy_tracepoint_args *arg) | |
955 | 0: push %rbp | |
956 | 1: mov %rsp,%rbp | |
957 | 4: sub $0x30,%rsp | |
958 | b: sub $0x28,%rbp | |
959 | f: mov %rbx,0x0(%rbp) | |
960 | 13: mov %r13,0x8(%rbp) | |
961 | 17: mov %r14,0x10(%rbp) | |
962 | 1b: mov %r15,0x18(%rbp) | |
963 | 1f: xor %eax,%eax | |
964 | 21: mov %rax,0x20(%rbp) | |
965 | 25: xor %esi,%esi | |
966 | ; int key = 0; | |
967 | 27: mov %esi,-0x4(%rbp) | |
968 | ; if (!arg->sock) | |
969 | 2a: mov 0x8(%rdi),%rdi | |
970 | ; if (!arg->sock) | |
971 | 2e: cmp $0x0,%rdi | |
972 | 32: je 0x0000000000000070 | |
973 | 34: mov %rbp,%rsi | |
974 | ; counts = bpf_map_lookup_elem(&btf_map, &key); | |
975 | [...] | |
976 | ||
5efc529f | 977 | 5.3 Verifier Log |
3ff36bff | 978 | ---------------- |
ffcf7ce9 | 979 | |
9ab5305d AN |
980 | The following is an example of how line_info can help debugging verification |
981 | failure.:: | |
ffcf7ce9 YS |
982 | |
983 | /* The code at tools/testing/selftests/bpf/test_xdp_noinline.c | |
984 | * is modified as below. | |
985 | */ | |
986 | data = (void *)(long)xdp->data; | |
987 | data_end = (void *)(long)xdp->data_end; | |
988 | /* | |
989 | if (data + 4 > data_end) | |
990 | return XDP_DROP; | |
991 | */ | |
992 | *(u32 *)data = dst->dst; | |
993 | ||
994 | $ bpftool prog load ./test_xdp_noinline.o /sys/fs/bpf/test_xdp_noinline type xdp | |
995 | ; data = (void *)(long)xdp->data; | |
996 | 224: (79) r2 = *(u64 *)(r10 -112) | |
997 | 225: (61) r2 = *(u32 *)(r2 +0) | |
998 | ; *(u32 *)data = dst->dst; | |
999 | 226: (63) *(u32 *)(r2 +0) = r1 | |
1000 | invalid access to packet, off=0 size=4, R2(id=0,off=0,r=0) | |
1001 | R2 offset is outside of the packet | |
1002 | ||
1003 | 6. BTF Generation | |
3ff36bff | 1004 | ================= |
ffcf7ce9 YS |
1005 | |
1006 | You need latest pahole | |
1007 | ||
1008 | https://git.kernel.org/pub/scm/devel/pahole/pahole.git/ | |
1009 | ||
9ab5305d AN |
1010 | or llvm (8.0 or later). The pahole acts as a dwarf2btf converter. It doesn't |
1011 | support .BTF.ext and btf BTF_KIND_FUNC type yet. For example,:: | |
ffcf7ce9 YS |
1012 | |
1013 | -bash-4.4$ cat t.c | |
1014 | struct t { | |
1015 | int a:2; | |
1016 | int b:3; | |
1017 | int c:2; | |
1018 | } g; | |
1019 | -bash-4.4$ gcc -c -O2 -g t.c | |
1020 | -bash-4.4$ pahole -JV t.o | |
1021 | File t.o: | |
1022 | [1] STRUCT t kind_flag=1 size=4 vlen=3 | |
1023 | a type_id=2 bitfield_size=2 bits_offset=0 | |
1024 | b type_id=2 bitfield_size=3 bits_offset=2 | |
1025 | c type_id=2 bitfield_size=2 bits_offset=5 | |
1026 | [2] INT int size=4 bit_offset=0 nr_bits=32 encoding=SIGNED | |
1027 | ||
9ab5305d AN |
1028 | The llvm is able to generate .BTF and .BTF.ext directly with -g for bpf target |
1029 | only. The assembly code (-S) is able to show the BTF encoding in assembly | |
1030 | format.:: | |
ffcf7ce9 YS |
1031 | |
1032 | -bash-4.4$ cat t2.c | |
1033 | typedef int __int32; | |
1034 | struct t2 { | |
1035 | int a2; | |
1036 | int (*f2)(char q1, __int32 q2, ...); | |
1037 | int (*f3)(); | |
1038 | } g2; | |
1039 | int main() { return 0; } | |
1040 | int test() { return 0; } | |
bbaf1ff0 | 1041 | -bash-4.4$ clang -c -g -O2 --target=bpf t2.c |
ffcf7ce9 YS |
1042 | -bash-4.4$ readelf -S t2.o |
1043 | ...... | |
1044 | [ 8] .BTF PROGBITS 0000000000000000 00000247 | |
1045 | 000000000000016e 0000000000000000 0 0 1 | |
1046 | [ 9] .BTF.ext PROGBITS 0000000000000000 000003b5 | |
1047 | 0000000000000060 0000000000000000 0 0 1 | |
1048 | [10] .rel.BTF.ext REL 0000000000000000 000007e0 | |
1049 | 0000000000000040 0000000000000010 16 9 8 | |
1050 | ...... | |
bbaf1ff0 | 1051 | -bash-4.4$ clang -S -g -O2 --target=bpf t2.c |
ffcf7ce9 YS |
1052 | -bash-4.4$ cat t2.s |
1053 | ...... | |
1054 | .section .BTF,"",@progbits | |
1055 | .short 60319 # 0xeb9f | |
1056 | .byte 1 | |
1057 | .byte 0 | |
1058 | .long 24 | |
1059 | .long 0 | |
1060 | .long 220 | |
1061 | .long 220 | |
1062 | .long 122 | |
1063 | .long 0 # BTF_KIND_FUNC_PROTO(id = 1) | |
1064 | .long 218103808 # 0xd000000 | |
1065 | .long 2 | |
1066 | .long 83 # BTF_KIND_INT(id = 2) | |
1067 | .long 16777216 # 0x1000000 | |
1068 | .long 4 | |
1069 | .long 16777248 # 0x1000020 | |
1070 | ...... | |
1071 | .byte 0 # string offset=0 | |
1072 | .ascii ".text" # string offset=1 | |
1073 | .byte 0 | |
1074 | .ascii "/home/yhs/tmp-pahole/t2.c" # string offset=7 | |
1075 | .byte 0 | |
1076 | .ascii "int main() { return 0; }" # string offset=33 | |
1077 | .byte 0 | |
1078 | .ascii "int test() { return 0; }" # string offset=58 | |
1079 | .byte 0 | |
1080 | .ascii "int" # string offset=83 | |
1081 | ...... | |
1082 | .section .BTF.ext,"",@progbits | |
1083 | .short 60319 # 0xeb9f | |
1084 | .byte 1 | |
1085 | .byte 0 | |
1086 | .long 24 | |
1087 | .long 0 | |
1088 | .long 28 | |
1089 | .long 28 | |
1090 | .long 44 | |
1091 | .long 8 # FuncInfo | |
1092 | .long 1 # FuncInfo section string offset=1 | |
1093 | .long 2 | |
1094 | .long .Lfunc_begin0 | |
1095 | .long 3 | |
1096 | .long .Lfunc_begin1 | |
1097 | .long 5 | |
1098 | .long 16 # LineInfo | |
1099 | .long 1 # LineInfo section string offset=1 | |
1100 | .long 2 | |
1101 | .long .Ltmp0 | |
1102 | .long 7 | |
1103 | .long 33 | |
1104 | .long 7182 # Line 7 Col 14 | |
1105 | .long .Ltmp3 | |
1106 | .long 7 | |
1107 | .long 58 | |
1108 | .long 8206 # Line 8 Col 14 | |
1109 | ||
1110 | 7. Testing | |
3ff36bff | 1111 | ========== |
ffcf7ce9 | 1112 | |
b74344cb RT |
1113 | The kernel BPF selftest `tools/testing/selftests/bpf/prog_tests/btf.c`_ |
1114 | provides an extensive set of BTF-related tests. | |
1115 | ||
1116 | .. Links | |
1117 | .. _tools/testing/selftests/bpf/prog_tests/btf.c: | |
1118 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/prog_tests/btf.c |