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