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