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