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 Currently, ``BTF_KIND_TYPE_TAG`` is only emitted for pointer types.
 507 It has the following btf type chain:
 508 ::
 509
 510   ptr -> [type_tag]*
 511       -> [const | volatile | restrict | typedef]*
 512       -> base_type
 513
 514 Basically, a pointer type points to zero or more
 515 type_tag, then zero or more const/volatile/restrict/typedef
 516 and finally the base type. The base type is one of
 517 int, ptr, array, struct, union, enum, func_proto and float types.
 518
 519 3. BTF Kernel API
 520 =================
 521
 522 The following bpf syscall command involves BTF:
 523    * BPF_BTF_LOAD: load a blob of BTF data into kernel
 524    * BPF_MAP_CREATE: map creation with btf key and value type info.
 525    * BPF_PROG_LOAD: prog load with btf function and line info.
 526    * BPF_BTF_GET_FD_BY_ID: get a btf fd
 527    * BPF_OBJ_GET_INFO_BY_FD: btf, func_info, line_info
 528      and other btf related info are returned.
 529
 530 The workflow typically looks like:
 531 ::
 532
 533   Application:
 534       BPF_BTF_LOAD
 535           |
 536           v
 537       BPF_MAP_CREATE and BPF_PROG_LOAD
 538           |
 539           V
 540       ......
 541
 542   Introspection tool:
 543       ......
 544       BPF_{PROG,MAP}_GET_NEXT_ID (get prog/map id's)
 545           |
 546           V
 547       BPF_{PROG,MAP}_GET_FD_BY_ID (get a prog/map fd)
 548           |
 549           V
 550       BPF_OBJ_GET_INFO_BY_FD (get bpf_prog_info/bpf_map_info with btf_id)
 551           |                                     |
 552           V                                     |
 553       BPF_BTF_GET_FD_BY_ID (get btf_fd)         |
 554           |                                     |
 555           V                                     |
 556       BPF_OBJ_GET_INFO_BY_FD (get btf)          |
 557           |                                     |
 558           V                                     V
 559       pretty print types, dump func signatures and line info, etc.
 560
 561
 562 3.1 BPF_BTF_LOAD
 563 ----------------
 564
 565 Load a blob of BTF data into kernel. A blob of data, described in
 566 :ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd``
 567 is returned to a userspace.
 568
 569 3.2 BPF_MAP_CREATE
 570 ------------------
 571
 572 A map can be created with ``btf_fd`` and specified key/value type id.::
 573
 574     __u32   btf_fd;         /* fd pointing to a BTF type data */
 575     __u32   btf_key_type_id;        /* BTF type_id of the key */
 576     __u32   btf_value_type_id;      /* BTF type_id of the value */
 577
 578 In libbpf, the map can be defined with extra annotation like below:
 579 ::
 580
 581     struct {
 582         __uint(type, BPF_MAP_TYPE_ARRAY);
 583         __type(key, int);
 584         __type(value, struct ipv_counts);
 585         __uint(max_entries, 4);
 586     } btf_map SEC(".maps");
 587
 588 During ELF parsing, libbpf is able to extract key/value type_id's and assign
 589 them to BPF_MAP_CREATE attributes automatically.
 590
 591 .. _BPF_Prog_Load:
 592
 593 3.3 BPF_PROG_LOAD
 594 -----------------
 595
 596 During prog_load, func_info and line_info can be passed to kernel with proper
 597 values for the following attributes:
 598 ::
 599
 600     __u32           insn_cnt;
 601     __aligned_u64   insns;
 602     ......
 603     __u32           prog_btf_fd;    /* fd pointing to BTF type data */
 604     __u32           func_info_rec_size;     /* userspace bpf_func_info size */
 605     __aligned_u64   func_info;      /* func info */
 606     __u32           func_info_cnt;  /* number of bpf_func_info records */
 607     __u32           line_info_rec_size;     /* userspace bpf_line_info size */
 608     __aligned_u64   line_info;      /* line info */
 609     __u32           line_info_cnt;  /* number of bpf_line_info records */
 610
 611 The func_info and line_info are an array of below, respectively.::
 612
 613     struct bpf_func_info {
 614         __u32   insn_off; /* [0, insn_cnt - 1] */
 615         __u32   type_id;  /* pointing to a BTF_KIND_FUNC type */
 616     };
 617     struct bpf_line_info {
 618         __u32   insn_off; /* [0, insn_cnt - 1] */
 619         __u32   file_name_off; /* offset to string table for the filename */
 620         __u32   line_off; /* offset to string table for the source line */
 621         __u32   line_col; /* line number and column number */
 622     };
 623
 624 func_info_rec_size is the size of each func_info record, and
 625 line_info_rec_size is the size of each line_info record. Passing the record
 626 size to kernel make it possible to extend the record itself in the future.
 627
 628 Below are requirements for func_info:
 629   * func_info[0].insn_off must be 0.
 630   * the func_info insn_off is in strictly increasing order and matches
 631     bpf func boundaries.
 632
 633 Below are requirements for line_info:
 634   * the first insn in each func must have a line_info record pointing to it.
 635   * the line_info insn_off is in strictly increasing order.
 636
 637 For line_info, the line number and column number are defined as below:
 638 ::
 639
 640     #define BPF_LINE_INFO_LINE_NUM(line_col)        ((line_col) >> 10)
 641     #define BPF_LINE_INFO_LINE_COL(line_col)        ((line_col) & 0x3ff)
 642
 643 3.4 BPF_{PROG,MAP}_GET_NEXT_ID
 644 ------------------------------
 645
 646 In kernel, every loaded program, map or btf has a unique id. The id won't
 647 change during the lifetime of a program, map, or btf.
 648
 649 The bpf syscall command BPF_{PROG,MAP}_GET_NEXT_ID returns all id's, one for
 650 each command, to user space, for bpf program or maps, respectively, so an
 651 inspection tool can inspect all programs and maps.
 652
 653 3.5 BPF_{PROG,MAP}_GET_FD_BY_ID
 654 -------------------------------
 655
 656 An introspection tool cannot use id to get details about program or maps.
 657 A file descriptor needs to be obtained first for reference-counting purpose.
 658
 659 3.6 BPF_OBJ_GET_INFO_BY_FD
 660 --------------------------
 661
 662 Once a program/map fd is acquired, an introspection tool can get the detailed
 663 information from kernel about this fd, some of which are BTF-related. For
 664 example, ``bpf_map_info`` returns ``btf_id`` and key/value type ids.
 665 ``bpf_prog_info`` returns ``btf_id``, func_info, and line info for translated
 666 bpf byte codes, and jited_line_info.
 667
 668 3.7 BPF_BTF_GET_FD_BY_ID
 669 ------------------------
 670
 671 With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf
 672 syscall command BPF_BTF_GET_FD_BY_ID can retrieve a btf fd. Then, with
 673 command BPF_OBJ_GET_INFO_BY_FD, the btf blob, originally loaded into the
 674 kernel with BPF_BTF_LOAD, can be retrieved.
 675
 676 With the btf blob, ``bpf_map_info``, and ``bpf_prog_info``, an introspection
 677 tool has full btf knowledge and is able to pretty print map key/values, dump
 678 func signatures and line info, along with byte/jit codes.
 679
 680 4. ELF File Format Interface
 681 ============================
 682
 683 4.1 .BTF section
 684 ----------------
 685
 686 The .BTF section contains type and string data. The format of this section is
 687 same as the one describe in :ref:`BTF_Type_String`.
 688
 689 .. _BTF_Ext_Section:
 690
 691 4.2 .BTF.ext section
 692 --------------------
 693
 694 The .BTF.ext section encodes func_info and line_info which needs loader
 695 manipulation before loading into the kernel.
 696
 697 The specification for .BTF.ext section is defined at ``tools/lib/bpf/btf.h``
 698 and ``tools/lib/bpf/btf.c``.
 699
 700 The current header of .BTF.ext section::
 701
 702     struct btf_ext_header {
 703         __u16   magic;
 704         __u8    version;
 705         __u8    flags;
 706         __u32   hdr_len;
 707
 708         /* All offsets are in bytes relative to the end of this header */
 709         __u32   func_info_off;
 710         __u32   func_info_len;
 711         __u32   line_info_off;
 712         __u32   line_info_len;
 713     };
 714
 715 It is very similar to .BTF section. Instead of type/string section, it
 716 contains func_info and line_info section. See :ref:`BPF_Prog_Load` for details
 717 about func_info and line_info record format.
 718
 719 The func_info is organized as below.::
 720
 721      func_info_rec_size
 722      btf_ext_info_sec for section #1 /* func_info for section #1 */
 723      btf_ext_info_sec for section #2 /* func_info for section #2 */
 724      ...
 725
 726 ``func_info_rec_size`` specifies the size of ``bpf_func_info`` structure when
 727 .BTF.ext is generated. ``btf_ext_info_sec``, defined below, is a collection of
 728 func_info for each specific ELF section.::
 729
 730      struct btf_ext_info_sec {
 731         __u32   sec_name_off; /* offset to section name */
 732         __u32   num_info;
 733         /* Followed by num_info * record_size number of bytes */
 734         __u8    data[0];
 735      };
 736
 737 Here, num_info must be greater than 0.
 738
 739 The line_info is organized as below.::
 740
 741      line_info_rec_size
 742      btf_ext_info_sec for section #1 /* line_info for section #1 */
 743      btf_ext_info_sec for section #2 /* line_info for section #2 */
 744      ...
 745
 746 ``line_info_rec_size`` specifies the size of ``bpf_line_info`` structure when
 747 .BTF.ext is generated.
 748
 749 The interpretation of ``bpf_func_info->insn_off`` and
 750 ``bpf_line_info->insn_off`` is different between kernel API and ELF API. For
 751 kernel API, the ``insn_off`` is the instruction offset in the unit of ``struct
 752 bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the
 753 beginning of section (``btf_ext_info_sec->sec_name_off``).
 754
 755 4.2 .BTF_ids section
 756 --------------------
 757
 758 The .BTF_ids section encodes BTF ID values that are used within the kernel.
 759
 760 This section is created during the kernel compilation with the help of
 761 macros defined in ``include/linux/btf_ids.h`` header file. Kernel code can
 762 use them to create lists and sets (sorted lists) of BTF ID values.
 763
 764 The ``BTF_ID_LIST`` and ``BTF_ID`` macros define unsorted list of BTF ID values,
 765 with following syntax::
 766
 767   BTF_ID_LIST(list)
 768   BTF_ID(type1, name1)
 769   BTF_ID(type2, name2)
 770
 771 resulting in following layout in .BTF_ids section::
 772
 773   __BTF_ID__type1__name1__1:
 774   .zero 4
 775   __BTF_ID__type2__name2__2:
 776   .zero 4
 777
 778 The ``u32 list[];`` variable is defined to access the list.
 779
 780 The ``BTF_ID_UNUSED`` macro defines 4 zero bytes. It's used when we
 781 want to define unused entry in BTF_ID_LIST, like::
 782
 783       BTF_ID_LIST(bpf_skb_output_btf_ids)
 784       BTF_ID(struct, sk_buff)
 785       BTF_ID_UNUSED
 786       BTF_ID(struct, task_struct)
 787
 788 The ``BTF_SET_START/END`` macros pair defines sorted list of BTF ID values
 789 and their count, with following syntax::
 790
 791   BTF_SET_START(set)
 792   BTF_ID(type1, name1)
 793   BTF_ID(type2, name2)
 794   BTF_SET_END(set)
 795
 796 resulting in following layout in .BTF_ids section::
 797
 798   __BTF_ID__set__set:
 799   .zero 4
 800   __BTF_ID__type1__name1__3:
 801   .zero 4
 802   __BTF_ID__type2__name2__4:
 803   .zero 4
 804
 805 The ``struct btf_id_set set;`` variable is defined to access the list.
 806
 807 The ``typeX`` name can be one of following::
 808
 809    struct, union, typedef, func
 810
 811 and is used as a filter when resolving the BTF ID value.
 812
 813 All the BTF ID lists and sets are compiled in the .BTF_ids section and
 814 resolved during the linking phase of kernel build by ``resolve_btfids`` tool.
 815
 816 5. Using BTF
 817 ============
 818
 819 5.1 bpftool map pretty print
 820 ----------------------------
 821
 822 With BTF, the map key/value can be printed based on fields rather than simply
 823 raw bytes. This is especially valuable for large structure or if your data
 824 structure has bitfields. For example, for the following map,::
 825
 826       enum A { A1, A2, A3, A4, A5 };
 827       typedef enum A ___A;
 828       struct tmp_t {
 829            char a1:4;
 830            int  a2:4;
 831            int  :4;
 832            __u32 a3:4;
 833            int b;
 834            ___A b1:4;
 835            enum A b2:4;
 836       };
 837       struct {
 838            __uint(type, BPF_MAP_TYPE_ARRAY);
 839            __type(key, int);
 840            __type(value, struct tmp_t);
 841            __uint(max_entries, 1);
 842       } tmpmap SEC(".maps");
 843
 844 bpftool is able to pretty print like below:
 845 ::
 846
 847       [{
 848             "key": 0,
 849             "value": {
 850                 "a1": 0x2,
 851                 "a2": 0x4,
 852                 "a3": 0x6,
 853                 "b": 7,
 854                 "b1": 0x8,
 855                 "b2": 0xa
 856             }
 857         }
 858       ]
 859
 860 5.2 bpftool prog dump
 861 ---------------------
 862
 863 The following is an example showing how func_info and line_info can help prog
 864 dump with better kernel symbol names, function prototypes and line
 865 information.::
 866
 867     $ bpftool prog dump jited pinned /sys/fs/bpf/test_btf_haskv
 868     [...]
 869     int test_long_fname_2(struct dummy_tracepoint_args * arg):
 870     bpf_prog_44a040bf25481309_test_long_fname_2:
 871     ; static int test_long_fname_2(struct dummy_tracepoint_args *arg)
 872        0:   push   %rbp
 873        1:   mov    %rsp,%rbp
 874        4:   sub    $0x30,%rsp
 875        b:   sub    $0x28,%rbp
 876        f:   mov    %rbx,0x0(%rbp)
 877       13:   mov    %r13,0x8(%rbp)
 878       17:   mov    %r14,0x10(%rbp)
 879       1b:   mov    %r15,0x18(%rbp)
 880       1f:   xor    %eax,%eax
 881       21:   mov    %rax,0x20(%rbp)
 882       25:   xor    %esi,%esi
 883     ; int key = 0;
 884       27:   mov    %esi,-0x4(%rbp)
 885     ; if (!arg->sock)
 886       2a:   mov    0x8(%rdi),%rdi
 887     ; if (!arg->sock)
 888       2e:   cmp    $0x0,%rdi
 889       32:   je     0x0000000000000070
 890       34:   mov    %rbp,%rsi
 891     ; counts = bpf_map_lookup_elem(&btf_map, &key);
 892     [...]
 893
 894 5.3 Verifier Log
 895 ----------------
 896
 897 The following is an example of how line_info can help debugging verification
 898 failure.::
 899
 900        /* The code at tools/testing/selftests/bpf/test_xdp_noinline.c
 901         * is modified as below.
 902         */
 903        data = (void *)(long)xdp->data;
 904        data_end = (void *)(long)xdp->data_end;
 905        /*
 906        if (data + 4 > data_end)
 907                return XDP_DROP;
 908        */
 909        *(u32 *)data = dst->dst;
 910
 911     $ bpftool prog load ./test_xdp_noinline.o /sys/fs/bpf/test_xdp_noinline type xdp
 912         ; data = (void *)(long)xdp->data;
 913         224: (79) r2 = *(u64 *)(r10 -112)
 914         225: (61) r2 = *(u32 *)(r2 +0)
 915         ; *(u32 *)data = dst->dst;
 916         226: (63) *(u32 *)(r2 +0) = r1
 917         invalid access to packet, off=0 size=4, R2(id=0,off=0,r=0)
 918         R2 offset is outside of the packet
 919
 920 6. BTF Generation
 921 =================
 922
 923 You need latest pahole
 924
 925   https://git.kernel.org/pub/scm/devel/pahole/pahole.git/
 926
 927 or llvm (8.0 or later). The pahole acts as a dwarf2btf converter. It doesn't
 928 support .BTF.ext and btf BTF_KIND_FUNC type yet. For example,::
 929
 930       -bash-4.4$ cat t.c
 931       struct t {
 932         int a:2;
 933         int b:3;
 934         int c:2;
 935       } g;
 936       -bash-4.4$ gcc -c -O2 -g t.c
 937       -bash-4.4$ pahole -JV t.o
 938       File t.o:
 939       [1] STRUCT t kind_flag=1 size=4 vlen=3
 940               a type_id=2 bitfield_size=2 bits_offset=0
 941               b type_id=2 bitfield_size=3 bits_offset=2
 942               c type_id=2 bitfield_size=2 bits_offset=5
 943       [2] INT int size=4 bit_offset=0 nr_bits=32 encoding=SIGNED
 944
 945 The llvm is able to generate .BTF and .BTF.ext directly with -g for bpf target
 946 only. The assembly code (-S) is able to show the BTF encoding in assembly
 947 format.::
 948
 949     -bash-4.4$ cat t2.c
 950     typedef int __int32;
 951     struct t2 {
 952       int a2;
 953       int (*f2)(char q1, __int32 q2, ...);
 954       int (*f3)();
 955     } g2;
 956     int main() { return 0; }
 957     int test() { return 0; }
 958     -bash-4.4$ clang -c -g -O2 -target bpf t2.c
 959     -bash-4.4$ readelf -S t2.o
 960       ......
 961       [ 8] .BTF              PROGBITS         0000000000000000  00000247
 962            000000000000016e  0000000000000000           0     0     1
 963       [ 9] .BTF.ext          PROGBITS         0000000000000000  000003b5
 964            0000000000000060  0000000000000000           0     0     1
 965       [10] .rel.BTF.ext      REL              0000000000000000  000007e0
 966            0000000000000040  0000000000000010          16     9     8
 967       ......
 968     -bash-4.4$ clang -S -g -O2 -target bpf t2.c
 969     -bash-4.4$ cat t2.s
 970       ......
 971             .section        .BTF,"",@progbits
 972             .short  60319                   # 0xeb9f
 973             .byte   1
 974             .byte   0
 975             .long   24
 976             .long   0
 977             .long   220
 978             .long   220
 979             .long   122
 980             .long   0                       # BTF_KIND_FUNC_PROTO(id = 1)
 981             .long   218103808               # 0xd000000
 982             .long   2
 983             .long   83                      # BTF_KIND_INT(id = 2)
 984             .long   16777216                # 0x1000000
 985             .long   4
 986             .long   16777248                # 0x1000020
 987       ......
 988             .byte   0                       # string offset=0
 989             .ascii  ".text"                 # string offset=1
 990             .byte   0
 991             .ascii  "/home/yhs/tmp-pahole/t2.c" # string offset=7
 992             .byte   0
 993             .ascii  "int main() { return 0; }" # string offset=33
 994             .byte   0
 995             .ascii  "int test() { return 0; }" # string offset=58
 996             .byte   0
 997             .ascii  "int"                   # string offset=83
 998       ......
 999             .section        .BTF.ext,"",@progbits
1000             .short  60319                   # 0xeb9f
1001             .byte   1
1002             .byte   0
1003             .long   24
1004             .long   0
1005             .long   28
1006             .long   28
1007             .long   44
1008             .long   8                       # FuncInfo
1009             .long   1                       # FuncInfo section string offset=1
1010             .long   2
1011             .long   .Lfunc_begin0
1012             .long   3
1013             .long   .Lfunc_begin1
1014             .long   5
1015             .long   16                      # LineInfo
1016             .long   1                       # LineInfo section string offset=1
1017             .long   2
1018             .long   .Ltmp0
1019             .long   7
1020             .long   33
1021             .long   7182                    # Line 7 Col 14
1022             .long   .Ltmp3
1023             .long   7
1024             .long   58
1025             .long   8206                    # Line 8 Col 14
1026
1027 7. Testing
1028 ==========
1029
1030 Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests.