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