1===================== 2BPF Type Format (BTF) 3===================== 4 51. Introduction 6=============== 7 8BTF (BPF Type Format) is the metadata format which encodes the debug info 9related to BPF program/map. The name BTF was used initially to describe data 10types. The BTF was later extended to include function info for defined 11subroutines, and line info for source/line information. 12 13The debug info is used for map pretty print, function signature, etc. The 14function signature enables better bpf program/function kernel symbol. The line 15info helps generate source annotated translated byte code, jited code and 16verifier log. 17 18The BTF specification contains two parts, 19 * BTF kernel API 20 * BTF ELF file format 21 22The kernel API is the contract between user space and kernel. The kernel 23verifies the BTF info before using it. The ELF file format is a user space 24contract between ELF file and libbpf loader. 25 26The type and string sections are part of the BTF kernel API, describing the 27debug info (mostly types related) referenced by the bpf program. These two 28sections are discussed in details in :ref:`BTF_Type_String`. 29 30.. _BTF_Type_String: 31 322. BTF Type and String Encoding 33=============================== 34 35The file ``include/uapi/linux/btf.h`` provides high-level definition of how 36types/strings are encoded. 37 38The beginning of data blob must be:: 39 40 struct btf_header { 41 __u16 magic; 42 __u8 version; 43 __u8 flags; 44 __u32 hdr_len; 45 46 /* All offsets are in bytes relative to the end of this header */ 47 __u32 type_off; /* offset of type section */ 48 __u32 type_len; /* length of type section */ 49 __u32 str_off; /* offset of string section */ 50 __u32 str_len; /* length of string section */ 51 }; 52 53The magic is ``0xeB9F``, which has different encoding for big and little 54endian systems, and can be used to test whether BTF is generated for big- or 55little-endian target. The ``btf_header`` is designed to be extensible with 56``hdr_len`` equal to ``sizeof(struct btf_header)`` when a data blob is 57generated. 58 592.1 String Encoding 60------------------- 61 62The first string in the string section must be a null string. The rest of 63string table is a concatenation of other null-terminated strings. 64 652.2 Type Encoding 66----------------- 67 68The type id ``0`` is reserved for ``void`` type. The type section is parsed 69sequentially and type id is assigned to each recognized type starting from id 70``1``. Currently, the following types are supported:: 71 72 #define BTF_KIND_INT 1 /* Integer */ 73 #define BTF_KIND_PTR 2 /* Pointer */ 74 #define BTF_KIND_ARRAY 3 /* Array */ 75 #define BTF_KIND_STRUCT 4 /* Struct */ 76 #define BTF_KIND_UNION 5 /* Union */ 77 #define BTF_KIND_ENUM 6 /* Enumeration up to 32-bit values */ 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 #define BTF_KIND_ENUM64 19 /* Enumeration up to 64-bit values */ 91 92Note that the type section encodes debug info, not just pure types. 93``BTF_KIND_FUNC`` is not a type, and it represents a defined subprogram. 94 95Each type contains the following common data:: 96 97 struct btf_type { 98 __u32 name_off; 99 /* "info" bits arrangement 100 * bits 0-15: vlen (e.g. # of struct's members) 101 * bits 16-23: unused 102 * bits 24-28: kind (e.g. int, ptr, array...etc) 103 * bits 29-30: unused 104 * bit 31: kind_flag, currently used by 105 * struct, union, enum, fwd, enum64, 106 * decl_tag and type_tag 107 */ 108 __u32 info; 109 /* "size" is used by INT, ENUM, STRUCT, UNION and ENUM64. 110 * "size" tells the size of the type it is describing. 111 * 112 * "type" is used by PTR, TYPEDEF, VOLATILE, CONST, RESTRICT, 113 * FUNC, FUNC_PROTO, DECL_TAG and TYPE_TAG. 114 * "type" is a type_id referring to another type. 115 */ 116 union { 117 __u32 size; 118 __u32 type; 119 }; 120 }; 121 122For certain kinds, the common data are followed by kind-specific data. The 123``name_off`` in ``struct btf_type`` specifies the offset in the string table. 124The following sections detail encoding of each kind. 125 1262.2.1 BTF_KIND_INT 127~~~~~~~~~~~~~~~~~~ 128 129``struct btf_type`` encoding requirement: 130 * ``name_off``: any valid offset 131 * ``info.kind_flag``: 0 132 * ``info.kind``: BTF_KIND_INT 133 * ``info.vlen``: 0 134 * ``size``: the size of the int type in bytes. 135 136``btf_type`` is followed by a ``u32`` with the following bits arrangement:: 137 138 #define BTF_INT_ENCODING(VAL) (((VAL) & 0x0f000000) >> 24) 139 #define BTF_INT_OFFSET(VAL) (((VAL) & 0x00ff0000) >> 16) 140 #define BTF_INT_BITS(VAL) ((VAL) & 0x000000ff) 141 142The ``BTF_INT_ENCODING`` has the following attributes:: 143 144 #define BTF_INT_SIGNED (1 << 0) 145 #define BTF_INT_CHAR (1 << 1) 146 #define BTF_INT_BOOL (1 << 2) 147 148The ``BTF_INT_ENCODING()`` provides extra information: signedness, char, or 149bool, for the int type. The char and bool encoding are mostly useful for 150pretty print. At most one encoding can be specified for the int type. 151 152The ``BTF_INT_BITS()`` specifies the number of actual bits held by this int 153type. For example, a 4-bit bitfield encodes ``BTF_INT_BITS()`` equals to 4. 154The ``btf_type.size * 8`` must be equal to or greater than ``BTF_INT_BITS()`` 155for the type. The maximum value of ``BTF_INT_BITS()`` is 128. 156 157The ``BTF_INT_OFFSET()`` specifies the starting bit offset to calculate values 158for this int. For example, a bitfield struct member has: 159 160 * btf member bit offset 100 from the start of the structure, 161 * btf member pointing to an int type, 162 * the int type has ``BTF_INT_OFFSET() = 2`` and ``BTF_INT_BITS() = 4`` 163 164Then in the struct memory layout, this member will occupy ``4`` bits starting 165from bits ``100 + 2 = 102``. 166 167Alternatively, the bitfield struct member can be the following to access the 168same bits as the above: 169 170 * btf member bit offset 102, 171 * btf member pointing to an int type, 172 * the int type has ``BTF_INT_OFFSET() = 0`` and ``BTF_INT_BITS() = 4`` 173 174The original intention of ``BTF_INT_OFFSET()`` is to provide flexibility of 175bitfield encoding. Currently, both llvm and pahole generate 176``BTF_INT_OFFSET() = 0`` for all int types. 177 1782.2.2 BTF_KIND_PTR 179~~~~~~~~~~~~~~~~~~ 180 181``struct btf_type`` encoding requirement: 182 * ``name_off``: 0 183 * ``info.kind_flag``: 0 184 * ``info.kind``: BTF_KIND_PTR 185 * ``info.vlen``: 0 186 * ``type``: the pointee type of the pointer 187 188No additional type data follow ``btf_type``. 189 1902.2.3 BTF_KIND_ARRAY 191~~~~~~~~~~~~~~~~~~~~ 192 193``struct btf_type`` encoding requirement: 194 * ``name_off``: 0 195 * ``info.kind_flag``: 0 196 * ``info.kind``: BTF_KIND_ARRAY 197 * ``info.vlen``: 0 198 * ``size/type``: 0, not used 199 200``btf_type`` is followed by one ``struct btf_array``:: 201 202 struct btf_array { 203 __u32 type; 204 __u32 index_type; 205 __u32 nelems; 206 }; 207 208The ``struct btf_array`` encoding: 209 * ``type``: the element type 210 * ``index_type``: the index type 211 * ``nelems``: the number of elements for this array (``0`` is also allowed). 212 213The ``index_type`` can be any regular int type (``u8``, ``u16``, ``u32``, 214``u64``, ``unsigned __int128``). The original design of including 215``index_type`` follows DWARF, which has an ``index_type`` for its array type. 216Currently in BTF, beyond type verification, the ``index_type`` is not used. 217 218The ``struct btf_array`` allows chaining through element type to represent 219multidimensional arrays. For example, for ``int a[5][6]``, the following type 220information illustrates the chaining: 221 222 * [1]: int 223 * [2]: array, ``btf_array.type = [1]``, ``btf_array.nelems = 6`` 224 * [3]: array, ``btf_array.type = [2]``, ``btf_array.nelems = 5`` 225 226Currently, both pahole and llvm collapse multidimensional array into 227one-dimensional array, e.g., for ``a[5][6]``, the ``btf_array.nelems`` is 228equal to ``30``. This is because the original use case is map pretty print 229where the whole array is dumped out so one-dimensional array is enough. As 230more BTF usage is explored, pahole and llvm can be changed to generate proper 231chained representation for multidimensional arrays. 232 2332.2.4 BTF_KIND_STRUCT 234~~~~~~~~~~~~~~~~~~~~~ 2352.2.5 BTF_KIND_UNION 236~~~~~~~~~~~~~~~~~~~~ 237 238``struct btf_type`` encoding requirement: 239 * ``name_off``: 0 or offset to a valid C identifier 240 * ``info.kind_flag``: 0 or 1 241 * ``info.kind``: BTF_KIND_STRUCT or BTF_KIND_UNION 242 * ``info.vlen``: the number of struct/union members 243 * ``info.size``: the size of the struct/union in bytes 244 245``btf_type`` is followed by ``info.vlen`` number of ``struct btf_member``.:: 246 247 struct btf_member { 248 __u32 name_off; 249 __u32 type; 250 __u32 offset; 251 }; 252 253``struct btf_member`` encoding: 254 * ``name_off``: offset to a valid C identifier 255 * ``type``: the member type 256 * ``offset``: <see below> 257 258If the type info ``kind_flag`` is not set, the offset contains only bit offset 259of the member. Note that the base type of the bitfield can only be int or enum 260type. If the bitfield size is 32, the base type can be either int or enum 261type. If the bitfield size is not 32, the base type must be int, and int type 262``BTF_INT_BITS()`` encodes the bitfield size. 263 264If the ``kind_flag`` is set, the ``btf_member.offset`` contains both member 265bitfield size and bit offset. The bitfield size and bit offset are calculated 266as below.:: 267 268 #define BTF_MEMBER_BITFIELD_SIZE(val) ((val) >> 24) 269 #define BTF_MEMBER_BIT_OFFSET(val) ((val) & 0xffffff) 270 271In this case, if the base type is an int type, it must be a regular int type: 272 273 * ``BTF_INT_OFFSET()`` must be 0. 274 * ``BTF_INT_BITS()`` must be equal to ``{1,2,4,8,16} * 8``. 275 276Commit 9d5f9f701b18 introduced ``kind_flag`` and explains why both modes 277exist. 278 2792.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 for unsigned, 1 for signed 285 * ``info.kind``: BTF_KIND_ENUM 286 * ``info.vlen``: number of enum values 287 * ``size``: 1/2/4/8 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 296The ``btf_enum`` encoding: 297 * ``name_off``: offset to a valid C identifier 298 * ``val``: any value 299 300If the original enum value is signed and the size is less than 4, 301that value will be sign extended into 4 bytes. If the size is 8, 302the value will be truncated into 4 bytes. 303 3042.2.7 BTF_KIND_FWD 305~~~~~~~~~~~~~~~~~~ 306 307``struct btf_type`` encoding requirement: 308 * ``name_off``: offset to a valid C identifier 309 * ``info.kind_flag``: 0 for struct, 1 for union 310 * ``info.kind``: BTF_KIND_FWD 311 * ``info.vlen``: 0 312 * ``type``: 0 313 314No additional type data follow ``btf_type``. 315 3162.2.8 BTF_KIND_TYPEDEF 317~~~~~~~~~~~~~~~~~~~~~~ 318 319``struct btf_type`` encoding requirement: 320 * ``name_off``: offset to a valid C identifier 321 * ``info.kind_flag``: 0 322 * ``info.kind``: BTF_KIND_TYPEDEF 323 * ``info.vlen``: 0 324 * ``type``: the type which can be referred by name at ``name_off`` 325 326No additional type data follow ``btf_type``. 327 3282.2.9 BTF_KIND_VOLATILE 329~~~~~~~~~~~~~~~~~~~~~~~ 330 331``struct btf_type`` encoding requirement: 332 * ``name_off``: 0 333 * ``info.kind_flag``: 0 334 * ``info.kind``: BTF_KIND_VOLATILE 335 * ``info.vlen``: 0 336 * ``type``: the type with ``volatile`` qualifier 337 338No additional type data follow ``btf_type``. 339 3402.2.10 BTF_KIND_CONST 341~~~~~~~~~~~~~~~~~~~~~ 342 343``struct btf_type`` encoding requirement: 344 * ``name_off``: 0 345 * ``info.kind_flag``: 0 346 * ``info.kind``: BTF_KIND_CONST 347 * ``info.vlen``: 0 348 * ``type``: the type with ``const`` qualifier 349 350No additional type data follow ``btf_type``. 351 3522.2.11 BTF_KIND_RESTRICT 353~~~~~~~~~~~~~~~~~~~~~~~~ 354 355``struct btf_type`` encoding requirement: 356 * ``name_off``: 0 357 * ``info.kind_flag``: 0 358 * ``info.kind``: BTF_KIND_RESTRICT 359 * ``info.vlen``: 0 360 * ``type``: the type with ``restrict`` qualifier 361 362No additional type data follow ``btf_type``. 363 3642.2.12 BTF_KIND_FUNC 365~~~~~~~~~~~~~~~~~~~~ 366 367``struct btf_type`` encoding requirement: 368 * ``name_off``: offset to a valid C identifier 369 * ``info.kind_flag``: 0 370 * ``info.kind``: BTF_KIND_FUNC 371 * ``info.vlen``: linkage information (BTF_FUNC_STATIC, BTF_FUNC_GLOBAL 372 or BTF_FUNC_EXTERN - see :ref:`BTF_Function_Linkage_Constants`) 373 * ``type``: a BTF_KIND_FUNC_PROTO type 374 375No additional type data follow ``btf_type``. 376 377A BTF_KIND_FUNC defines not a type, but a subprogram (function) whose 378signature is defined by ``type``. The subprogram is thus an instance of that 379type. The BTF_KIND_FUNC may in turn be referenced by a func_info in the 380:ref:`BTF_Ext_Section` (ELF) or in the arguments to :ref:`BPF_Prog_Load` 381(ABI). 382 383Currently, only linkage values of BTF_FUNC_STATIC and BTF_FUNC_GLOBAL are 384supported in the kernel. 385 3862.2.13 BTF_KIND_FUNC_PROTO 387~~~~~~~~~~~~~~~~~~~~~~~~~~ 388 389``struct btf_type`` encoding requirement: 390 * ``name_off``: 0 391 * ``info.kind_flag``: 0 392 * ``info.kind``: BTF_KIND_FUNC_PROTO 393 * ``info.vlen``: # of parameters 394 * ``type``: the return type 395 396``btf_type`` is followed by ``info.vlen`` number of ``struct btf_param``.:: 397 398 struct btf_param { 399 __u32 name_off; 400 __u32 type; 401 }; 402 403If a BTF_KIND_FUNC_PROTO type is referred by a BTF_KIND_FUNC type, then 404``btf_param.name_off`` must point to a valid C identifier except for the 405possible last argument representing the variable argument. The btf_param.type 406refers to parameter type. 407 408If the function has variable arguments, the last parameter is encoded with 409``name_off = 0`` and ``type = 0``. 410 4112.2.14 BTF_KIND_VAR 412~~~~~~~~~~~~~~~~~~~ 413 414``struct btf_type`` encoding requirement: 415 * ``name_off``: offset to a valid C identifier 416 * ``info.kind_flag``: 0 417 * ``info.kind``: BTF_KIND_VAR 418 * ``info.vlen``: 0 419 * ``type``: the type of the variable 420 421``btf_type`` is followed by a single ``struct btf_variable`` with the 422following data:: 423 424 struct btf_var { 425 __u32 linkage; 426 }; 427 428``btf_var.linkage`` may take the values: BTF_VAR_STATIC, BTF_VAR_GLOBAL_ALLOCATED or BTF_VAR_GLOBAL_EXTERN - 429see :ref:`BTF_Var_Linkage_Constants`. 430 431Not all type of global variables are supported by LLVM at this point. 432The following is currently available: 433 434 * static variables with or without section attributes 435 * global variables with section attributes 436 437The latter is for future extraction of map key/value type id's from a 438map definition. 439 4402.2.15 BTF_KIND_DATASEC 441~~~~~~~~~~~~~~~~~~~~~~~ 442 443``struct btf_type`` encoding requirement: 444 * ``name_off``: offset to a valid name associated with a variable or 445 one of .data/.bss/.rodata 446 * ``info.kind_flag``: 0 447 * ``info.kind``: BTF_KIND_DATASEC 448 * ``info.vlen``: # of variables 449 * ``size``: total section size in bytes (0 at compilation time, patched 450 to actual size by BPF loaders such as libbpf) 451 452``btf_type`` is followed by ``info.vlen`` number of ``struct btf_var_secinfo``.:: 453 454 struct btf_var_secinfo { 455 __u32 type; 456 __u32 offset; 457 __u32 size; 458 }; 459 460``struct btf_var_secinfo`` encoding: 461 * ``type``: the type of the BTF_KIND_VAR variable 462 * ``offset``: the in-section offset of the variable 463 * ``size``: the size of the variable in bytes 464 4652.2.16 BTF_KIND_FLOAT 466~~~~~~~~~~~~~~~~~~~~~ 467 468``struct btf_type`` encoding requirement: 469 * ``name_off``: any valid offset 470 * ``info.kind_flag``: 0 471 * ``info.kind``: BTF_KIND_FLOAT 472 * ``info.vlen``: 0 473 * ``size``: the size of the float type in bytes: 2, 4, 8, 12 or 16. 474 475No additional type data follow ``btf_type``. 476 4772.2.17 BTF_KIND_DECL_TAG 478~~~~~~~~~~~~~~~~~~~~~~~~ 479 480``struct btf_type`` encoding requirement: 481 * ``name_off``: offset to a non-empty string 482 * ``info.kind_flag``: 0 or 1 483 * ``info.kind``: BTF_KIND_DECL_TAG 484 * ``info.vlen``: 0 485 * ``type``: ``struct``, ``union``, ``func``, ``var`` or ``typedef`` 486 487``btf_type`` is followed by ``struct btf_decl_tag``.:: 488 489 struct btf_decl_tag { 490 __u32 component_idx; 491 }; 492 493The ``type`` should be ``struct``, ``union``, ``func``, ``var`` or ``typedef``. 494For ``var`` or ``typedef`` type, ``btf_decl_tag.component_idx`` must be ``-1``. 495For the other three types, if the btf_decl_tag attribute is 496applied to the ``struct``, ``union`` or ``func`` itself, 497``btf_decl_tag.component_idx`` must be ``-1``. Otherwise, 498the attribute is applied to a ``struct``/``union`` member or 499a ``func`` argument, and ``btf_decl_tag.component_idx`` should be a 500valid index (starting from 0) pointing to a member or an argument. 501 502If ``info.kind_flag`` is 0, then this is a normal decl tag, and the 503``name_off`` encodes btf_decl_tag attribute string. 504 505If ``info.kind_flag`` is 1, then the decl tag represents an arbitrary 506__attribute__. In this case, ``name_off`` encodes a string 507representing the attribute-list of the attribute specifier. For 508example, for an ``__attribute__((aligned(4)))`` the string's contents 509is ``aligned(4)``. 510 5112.2.18 BTF_KIND_TYPE_TAG 512~~~~~~~~~~~~~~~~~~~~~~~~ 513 514``struct btf_type`` encoding requirement: 515 * ``name_off``: offset to a non-empty string 516 * ``info.kind_flag``: 0 or 1 517 * ``info.kind``: BTF_KIND_TYPE_TAG 518 * ``info.vlen``: 0 519 * ``type``: the type with ``btf_type_tag`` attribute 520 521Currently, ``BTF_KIND_TYPE_TAG`` is only emitted for pointer types. 522It has the following btf type chain: 523:: 524 525 ptr -> [type_tag]* 526 -> [const | volatile | restrict | typedef]* 527 -> base_type 528 529Basically, a pointer type points to zero or more 530type_tag, then zero or more const/volatile/restrict/typedef 531and finally the base type. The base type is one of 532int, ptr, array, struct, union, enum, func_proto and float types. 533 534Similarly to decl tags, if the ``info.kind_flag`` is 0, then this is a 535normal type tag, and the ``name_off`` encodes btf_type_tag attribute 536string. 537 538If ``info.kind_flag`` is 1, then the type tag represents an arbitrary 539__attribute__, and the ``name_off`` encodes a string representing the 540attribute-list of the attribute specifier. 541 5422.2.19 BTF_KIND_ENUM64 543~~~~~~~~~~~~~~~~~~~~~~ 544 545``struct btf_type`` encoding requirement: 546 * ``name_off``: 0 or offset to a valid C identifier 547 * ``info.kind_flag``: 0 for unsigned, 1 for signed 548 * ``info.kind``: BTF_KIND_ENUM64 549 * ``info.vlen``: number of enum values 550 * ``size``: 1/2/4/8 551 552``btf_type`` is followed by ``info.vlen`` number of ``struct btf_enum64``.:: 553 554 struct btf_enum64 { 555 __u32 name_off; 556 __u32 val_lo32; 557 __u32 val_hi32; 558 }; 559 560The ``btf_enum64`` encoding: 561 * ``name_off``: offset to a valid C identifier 562 * ``val_lo32``: lower 32-bit value for a 64-bit value 563 * ``val_hi32``: high 32-bit value for a 64-bit value 564 565If the original enum value is signed and the size is less than 8, 566that value will be sign extended into 8 bytes. 567 5682.3 Constant Values 569------------------- 570 571.. _BTF_Function_Linkage_Constants: 572 5732.3.1 Function Linkage Constant Values 574~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 575.. table:: Function Linkage Values and Meanings 576 577 =================== ===== =========== 578 kind value description 579 =================== ===== =========== 580 ``BTF_FUNC_STATIC`` 0x0 definition of subprogram not visible outside containing compilation unit 581 ``BTF_FUNC_GLOBAL`` 0x1 definition of subprogram visible outside containing compilation unit 582 ``BTF_FUNC_EXTERN`` 0x2 declaration of a subprogram whose definition is outside the containing compilation unit 583 =================== ===== =========== 584 585 586.. _BTF_Var_Linkage_Constants: 587 5882.3.2 Variable Linkage Constant Values 589~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 590.. table:: Variable Linkage Values and Meanings 591 592 ============================ ===== =========== 593 kind value description 594 ============================ ===== =========== 595 ``BTF_VAR_STATIC`` 0x0 definition of global variable not visible outside containing compilation unit 596 ``BTF_VAR_GLOBAL_ALLOCATED`` 0x1 definition of global variable visible outside containing compilation unit 597 ``BTF_VAR_GLOBAL_EXTERN`` 0x2 declaration of global variable whose definition is outside the containing compilation unit 598 ============================ ===== =========== 599 6003. BTF Kernel API 601================= 602 603The following bpf syscall command involves BTF: 604 * BPF_BTF_LOAD: load a blob of BTF data into kernel 605 * BPF_MAP_CREATE: map creation with btf key and value type info. 606 * BPF_PROG_LOAD: prog load with btf function and line info. 607 * BPF_BTF_GET_FD_BY_ID: get a btf fd 608 * BPF_OBJ_GET_INFO_BY_FD: btf, func_info, line_info 609 and other btf related info are returned. 610 611The workflow typically looks like: 612:: 613 614 Application: 615 BPF_BTF_LOAD 616 | 617 v 618 BPF_MAP_CREATE and BPF_PROG_LOAD 619 | 620 V 621 ...... 622 623 Introspection tool: 624 ...... 625 BPF_{PROG,MAP}_GET_NEXT_ID (get prog/map id's) 626 | 627 V 628 BPF_{PROG,MAP}_GET_FD_BY_ID (get a prog/map fd) 629 | 630 V 631 BPF_OBJ_GET_INFO_BY_FD (get bpf_prog_info/bpf_map_info with btf_id) 632 | | 633 V | 634 BPF_BTF_GET_FD_BY_ID (get btf_fd) | 635 | | 636 V | 637 BPF_OBJ_GET_INFO_BY_FD (get btf) | 638 | | 639 V V 640 pretty print types, dump func signatures and line info, etc. 641 642 6433.1 BPF_BTF_LOAD 644---------------- 645 646Load a blob of BTF data into kernel. A blob of data, described in 647:ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd`` 648is returned to a userspace. 649 6503.2 BPF_MAP_CREATE 651------------------ 652 653A map can be created with ``btf_fd`` and specified key/value type id.:: 654 655 __u32 btf_fd; /* fd pointing to a BTF type data */ 656 __u32 btf_key_type_id; /* BTF type_id of the key */ 657 __u32 btf_value_type_id; /* BTF type_id of the value */ 658 659In libbpf, the map can be defined with extra annotation like below: 660:: 661 662 struct { 663 __uint(type, BPF_MAP_TYPE_ARRAY); 664 __type(key, int); 665 __type(value, struct ipv_counts); 666 __uint(max_entries, 4); 667 } btf_map SEC(".maps"); 668 669During ELF parsing, libbpf is able to extract key/value type_id's and assign 670them to BPF_MAP_CREATE attributes automatically. 671 672.. _BPF_Prog_Load: 673 6743.3 BPF_PROG_LOAD 675----------------- 676 677During prog_load, func_info and line_info can be passed to kernel with proper 678values for the following attributes: 679:: 680 681 __u32 insn_cnt; 682 __aligned_u64 insns; 683 ...... 684 __u32 prog_btf_fd; /* fd pointing to BTF type data */ 685 __u32 func_info_rec_size; /* userspace bpf_func_info size */ 686 __aligned_u64 func_info; /* func info */ 687 __u32 func_info_cnt; /* number of bpf_func_info records */ 688 __u32 line_info_rec_size; /* userspace bpf_line_info size */ 689 __aligned_u64 line_info; /* line info */ 690 __u32 line_info_cnt; /* number of bpf_line_info records */ 691 692The func_info and line_info are an array of below, respectively.:: 693 694 struct bpf_func_info { 695 __u32 insn_off; /* [0, insn_cnt - 1] */ 696 __u32 type_id; /* pointing to a BTF_KIND_FUNC type */ 697 }; 698 struct bpf_line_info { 699 __u32 insn_off; /* [0, insn_cnt - 1] */ 700 __u32 file_name_off; /* offset to string table for the filename */ 701 __u32 line_off; /* offset to string table for the source line */ 702 __u32 line_col; /* line number and column number */ 703 }; 704 705func_info_rec_size is the size of each func_info record, and 706line_info_rec_size is the size of each line_info record. Passing the record 707size to kernel make it possible to extend the record itself in the future. 708 709Below are requirements for func_info: 710 * func_info[0].insn_off must be 0. 711 * the func_info insn_off is in strictly increasing order and matches 712 bpf func boundaries. 713 714Below are requirements for line_info: 715 * the first insn in each func must have a line_info record pointing to it. 716 * the line_info insn_off is in strictly increasing order. 717 718For line_info, the line number and column number are defined as below: 719:: 720 721 #define BPF_LINE_INFO_LINE_NUM(line_col) ((line_col) >> 10) 722 #define BPF_LINE_INFO_LINE_COL(line_col) ((line_col) & 0x3ff) 723 7243.4 BPF_{PROG,MAP}_GET_NEXT_ID 725------------------------------ 726 727In kernel, every loaded program, map or btf has a unique id. The id won't 728change during the lifetime of a program, map, or btf. 729 730The bpf syscall command BPF_{PROG,MAP}_GET_NEXT_ID returns all id's, one for 731each command, to user space, for bpf program or maps, respectively, so an 732inspection tool can inspect all programs and maps. 733 7343.5 BPF_{PROG,MAP}_GET_FD_BY_ID 735------------------------------- 736 737An introspection tool cannot use id to get details about program or maps. 738A file descriptor needs to be obtained first for reference-counting purpose. 739 7403.6 BPF_OBJ_GET_INFO_BY_FD 741-------------------------- 742 743Once a program/map fd is acquired, an introspection tool can get the detailed 744information from kernel about this fd, some of which are BTF-related. For 745example, ``bpf_map_info`` returns ``btf_id`` and key/value type ids. 746``bpf_prog_info`` returns ``btf_id``, func_info, and line info for translated 747bpf byte codes, and jited_line_info. 748 7493.7 BPF_BTF_GET_FD_BY_ID 750------------------------ 751 752With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf 753syscall command BPF_BTF_GET_FD_BY_ID can retrieve a btf fd. Then, with 754command BPF_OBJ_GET_INFO_BY_FD, the btf blob, originally loaded into the 755kernel with BPF_BTF_LOAD, can be retrieved. 756 757With the btf blob, ``bpf_map_info``, and ``bpf_prog_info``, an introspection 758tool has full btf knowledge and is able to pretty print map key/values, dump 759func signatures and line info, along with byte/jit codes. 760 7614. ELF File Format Interface 762============================ 763 7644.1 .BTF section 765---------------- 766 767The .BTF section contains type and string data. The format of this section is 768same as the one describe in :ref:`BTF_Type_String`. 769 770.. _BTF_Ext_Section: 771 7724.2 .BTF.ext section 773-------------------- 774 775The .BTF.ext section encodes func_info, line_info and CO-RE relocations 776which needs loader manipulation before loading into the kernel. 777 778The specification for .BTF.ext section is defined at ``tools/lib/bpf/btf.h`` 779and ``tools/lib/bpf/btf.c``. 780 781The current header of .BTF.ext section:: 782 783 struct btf_ext_header { 784 __u16 magic; 785 __u8 version; 786 __u8 flags; 787 __u32 hdr_len; 788 789 /* All offsets are in bytes relative to the end of this header */ 790 __u32 func_info_off; 791 __u32 func_info_len; 792 __u32 line_info_off; 793 __u32 line_info_len; 794 795 /* optional part of .BTF.ext header */ 796 __u32 core_relo_off; 797 __u32 core_relo_len; 798 }; 799 800It is very similar to .BTF section. Instead of type/string section, it 801contains func_info, line_info and core_relo sub-sections. 802See :ref:`BPF_Prog_Load` for details about func_info and line_info 803record format. 804 805The func_info is organized as below.:: 806 807 func_info_rec_size /* __u32 value */ 808 btf_ext_info_sec for section #1 /* func_info for section #1 */ 809 btf_ext_info_sec for section #2 /* func_info for section #2 */ 810 ... 811 812``func_info_rec_size`` specifies the size of ``bpf_func_info`` structure when 813.BTF.ext is generated. ``btf_ext_info_sec``, defined below, is a collection of 814func_info for each specific ELF section.:: 815 816 struct btf_ext_info_sec { 817 __u32 sec_name_off; /* offset to section name */ 818 __u32 num_info; 819 /* Followed by num_info * record_size number of bytes */ 820 __u8 data[0]; 821 }; 822 823Here, num_info must be greater than 0. 824 825The line_info is organized as below.:: 826 827 line_info_rec_size /* __u32 value */ 828 btf_ext_info_sec for section #1 /* line_info for section #1 */ 829 btf_ext_info_sec for section #2 /* line_info for section #2 */ 830 ... 831 832``line_info_rec_size`` specifies the size of ``bpf_line_info`` structure when 833.BTF.ext is generated. 834 835The interpretation of ``bpf_func_info->insn_off`` and 836``bpf_line_info->insn_off`` is different between kernel API and ELF API. For 837kernel API, the ``insn_off`` is the instruction offset in the unit of ``struct 838bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the 839beginning of section (``btf_ext_info_sec->sec_name_off``). 840 841The core_relo is organized as below.:: 842 843 core_relo_rec_size /* __u32 value */ 844 btf_ext_info_sec for section #1 /* core_relo for section #1 */ 845 btf_ext_info_sec for section #2 /* core_relo for section #2 */ 846 847``core_relo_rec_size`` specifies the size of ``bpf_core_relo`` 848structure when .BTF.ext is generated. All ``bpf_core_relo`` structures 849within a single ``btf_ext_info_sec`` describe relocations applied to 850section named by ``btf_ext_info_sec->sec_name_off``. 851 852See :ref:`Documentation/bpf/llvm_reloc.rst <btf-co-re-relocations>` 853for more information on CO-RE relocations. 854 8554.3 .BTF_ids section 856-------------------- 857 858The .BTF_ids section encodes BTF ID values that are used within the kernel. 859 860This section is created during the kernel compilation with the help of 861macros defined in ``include/linux/btf_ids.h`` header file. Kernel code can 862use them to create lists and sets (sorted lists) of BTF ID values. 863 864The ``BTF_ID_LIST`` and ``BTF_ID`` macros define unsorted list of BTF ID values, 865with following syntax:: 866 867 BTF_ID_LIST(list) 868 BTF_ID(type1, name1) 869 BTF_ID(type2, name2) 870 871resulting in following layout in .BTF_ids section:: 872 873 __BTF_ID__type1__name1__1: 874 .zero 4 875 __BTF_ID__type2__name2__2: 876 .zero 4 877 878The ``u32 list[];`` variable is defined to access the list. 879 880The ``BTF_ID_UNUSED`` macro defines 4 zero bytes. It's used when we 881want to define unused entry in BTF_ID_LIST, like:: 882 883 BTF_ID_LIST(bpf_skb_output_btf_ids) 884 BTF_ID(struct, sk_buff) 885 BTF_ID_UNUSED 886 BTF_ID(struct, task_struct) 887 888The ``BTF_SET_START/END`` macros pair defines sorted list of BTF ID values 889and their count, with following syntax:: 890 891 BTF_SET_START(set) 892 BTF_ID(type1, name1) 893 BTF_ID(type2, name2) 894 BTF_SET_END(set) 895 896resulting in following layout in .BTF_ids section:: 897 898 __BTF_ID__set__set: 899 .zero 4 900 __BTF_ID__type1__name1__3: 901 .zero 4 902 __BTF_ID__type2__name2__4: 903 .zero 4 904 905The ``struct btf_id_set set;`` variable is defined to access the list. 906 907The ``typeX`` name can be one of following:: 908 909 struct, union, typedef, func 910 911and is used as a filter when resolving the BTF ID value. 912 913All the BTF ID lists and sets are compiled in the .BTF_ids section and 914resolved during the linking phase of kernel build by ``resolve_btfids`` tool. 915 9164.4 .BTF.base section 917--------------------- 918Split BTF - where the .BTF section only contains types not in the associated 919base .BTF section - is an extremely efficient way to encode type information 920for kernel modules, since they generally consist of a few module-specific 921types along with a large set of shared kernel types. The former are encoded 922in split BTF, while the latter are encoded in base BTF, resulting in more 923compact representations. A type in split BTF that refers to a type in 924base BTF refers to it using its base BTF ID, and split BTF IDs start 925at last_base_BTF_ID + 1. 926 927The downside of this approach however is that this makes the split BTF 928somewhat brittle - when the base BTF changes, base BTF ID references are 929no longer valid and the split BTF itself becomes useless. The role of the 930.BTF.base section is to make split BTF more resilient for cases where 931the base BTF may change, as is the case for kernel modules not built every 932time the kernel is for example. .BTF.base contains named base types; INTs, 933FLOATs, STRUCTs, UNIONs, ENUM[64]s and FWDs. INTs and FLOATs are fully 934described in .BTF.base sections, while composite types like structs 935and unions are not fully defined - the .BTF.base type simply serves as 936a description of the type the split BTF referred to, so structs/unions 937have 0 members in the .BTF.base section. ENUM[64]s are similarly recorded 938with 0 members. Any other types are added to the split BTF. This 939distillation process then leaves us with a .BTF.base section with 940such minimal descriptions of base types and .BTF split section which refers 941to those base types. Later, we can relocate the split BTF using both the 942information stored in the .BTF.base section and the new .BTF base; the type 943information in the .BTF.base section allows us to update the split BTF 944references to point at the corresponding new base BTF IDs. 945 946BTF relocation happens on kernel module load when a kernel module has a 947.BTF.base section, and libbpf also provides a btf__relocate() API to 948accomplish this. 949 950As an example consider the following base BTF:: 951 952 [1] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED 953 [2] STRUCT 'foo' size=8 vlen=2 954 'f1' type_id=1 bits_offset=0 955 'f2' type_id=1 bits_offset=32 956 957...and associated split BTF:: 958 959 [3] PTR '(anon)' type_id=2 960 961i.e. split BTF describes a pointer to struct foo { int f1; int f2 }; 962 963.BTF.base will consist of:: 964 965 [1] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED 966 [2] STRUCT 'foo' size=8 vlen=0 967 968If we relocate the split BTF later using the following new base BTF:: 969 970 [1] INT 'long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none) 971 [2] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED 972 [3] STRUCT 'foo' size=8 vlen=2 973 'f1' type_id=2 bits_offset=0 974 'f2' type_id=2 bits_offset=32 975 976...we can use our .BTF.base description to know that the split BTF reference 977is to struct foo, and relocation results in new split BTF:: 978 979 [4] PTR '(anon)' type_id=3 980 981Note that we had to update BTF ID and start BTF ID for the split BTF. 982 983So we see how .BTF.base plays the role of facilitating later relocation, 984leading to more resilient split BTF. 985 986.BTF.base sections will be generated automatically for out-of-tree kernel module 987builds - i.e. where KBUILD_EXTMOD is set (as it would be for "make M=path/2/mod" 988cases). .BTF.base generation requires pahole support for the "distilled_base" 989BTF feature; this is available in pahole v1.28 and later. 990 9915. Using BTF 992============ 993 9945.1 bpftool map pretty print 995---------------------------- 996 997With BTF, the map key/value can be printed based on fields rather than simply 998raw bytes. This is especially valuable for large structure or if your data 999structure has bitfields. For example, for the following map,:: 1000 1001 enum A { A1, A2, A3, A4, A5 }; 1002 typedef enum A ___A; 1003 struct tmp_t { 1004 char a1:4; 1005 int a2:4; 1006 int :4; 1007 __u32 a3:4; 1008 int b; 1009 ___A b1:4; 1010 enum A b2:4; 1011 }; 1012 struct { 1013 __uint(type, BPF_MAP_TYPE_ARRAY); 1014 __type(key, int); 1015 __type(value, struct tmp_t); 1016 __uint(max_entries, 1); 1017 } tmpmap SEC(".maps"); 1018 1019bpftool is able to pretty print like below: 1020:: 1021 1022 [{ 1023 "key": 0, 1024 "value": { 1025 "a1": 0x2, 1026 "a2": 0x4, 1027 "a3": 0x6, 1028 "b": 7, 1029 "b1": 0x8, 1030 "b2": 0xa 1031 } 1032 } 1033 ] 1034 10355.2 bpftool prog dump 1036--------------------- 1037 1038The following is an example showing how func_info and line_info can help prog 1039dump with better kernel symbol names, function prototypes and line 1040information.:: 1041 1042 $ bpftool prog dump jited pinned /sys/fs/bpf/test_btf_haskv 1043 [...] 1044 int test_long_fname_2(struct dummy_tracepoint_args * arg): 1045 bpf_prog_44a040bf25481309_test_long_fname_2: 1046 ; static int test_long_fname_2(struct dummy_tracepoint_args *arg) 1047 0: push %rbp 1048 1: mov %rsp,%rbp 1049 4: sub $0x30,%rsp 1050 b: sub $0x28,%rbp 1051 f: mov %rbx,0x0(%rbp) 1052 13: mov %r13,0x8(%rbp) 1053 17: mov %r14,0x10(%rbp) 1054 1b: mov %r15,0x18(%rbp) 1055 1f: xor %eax,%eax 1056 21: mov %rax,0x20(%rbp) 1057 25: xor %esi,%esi 1058 ; int key = 0; 1059 27: mov %esi,-0x4(%rbp) 1060 ; if (!arg->sock) 1061 2a: mov 0x8(%rdi),%rdi 1062 ; if (!arg->sock) 1063 2e: cmp $0x0,%rdi 1064 32: je 0x0000000000000070 1065 34: mov %rbp,%rsi 1066 ; counts = bpf_map_lookup_elem(&btf_map, &key); 1067 [...] 1068 10695.3 Verifier Log 1070---------------- 1071 1072The following is an example of how line_info can help debugging verification 1073failure.:: 1074 1075 /* The code at tools/testing/selftests/bpf/test_xdp_noinline.c 1076 * is modified as below. 1077 */ 1078 data = (void *)(long)xdp->data; 1079 data_end = (void *)(long)xdp->data_end; 1080 /* 1081 if (data + 4 > data_end) 1082 return XDP_DROP; 1083 */ 1084 *(u32 *)data = dst->dst; 1085 1086 $ bpftool prog load ./test_xdp_noinline.o /sys/fs/bpf/test_xdp_noinline type xdp 1087 ; data = (void *)(long)xdp->data; 1088 224: (79) r2 = *(u64 *)(r10 -112) 1089 225: (61) r2 = *(u32 *)(r2 +0) 1090 ; *(u32 *)data = dst->dst; 1091 226: (63) *(u32 *)(r2 +0) = r1 1092 invalid access to packet, off=0 size=4, R2(id=0,off=0,r=0) 1093 R2 offset is outside of the packet 1094 10956. BTF Generation 1096================= 1097 1098You need latest pahole 1099 1100 https://git.kernel.org/pub/scm/devel/pahole/pahole.git/ 1101 1102or llvm (8.0 or later). The pahole acts as a dwarf2btf converter. It doesn't 1103support .BTF.ext and btf BTF_KIND_FUNC type yet. For example,:: 1104 1105 -bash-4.4$ cat t.c 1106 struct t { 1107 int a:2; 1108 int b:3; 1109 int c:2; 1110 } g; 1111 -bash-4.4$ gcc -c -O2 -g t.c 1112 -bash-4.4$ pahole -JV t.o 1113 File t.o: 1114 [1] STRUCT t kind_flag=1 size=4 vlen=3 1115 a type_id=2 bitfield_size=2 bits_offset=0 1116 b type_id=2 bitfield_size=3 bits_offset=2 1117 c type_id=2 bitfield_size=2 bits_offset=5 1118 [2] INT int size=4 bit_offset=0 nr_bits=32 encoding=SIGNED 1119 1120The llvm is able to generate .BTF and .BTF.ext directly with -g for bpf target 1121only. The assembly code (-S) is able to show the BTF encoding in assembly 1122format.:: 1123 1124 -bash-4.4$ cat t2.c 1125 typedef int __int32; 1126 struct t2 { 1127 int a2; 1128 int (*f2)(char q1, __int32 q2, ...); 1129 int (*f3)(); 1130 } g2; 1131 int main() { return 0; } 1132 int test() { return 0; } 1133 -bash-4.4$ clang -c -g -O2 --target=bpf t2.c 1134 -bash-4.4$ readelf -S t2.o 1135 ...... 1136 [ 8] .BTF PROGBITS 0000000000000000 00000247 1137 000000000000016e 0000000000000000 0 0 1 1138 [ 9] .BTF.ext PROGBITS 0000000000000000 000003b5 1139 0000000000000060 0000000000000000 0 0 1 1140 [10] .rel.BTF.ext REL 0000000000000000 000007e0 1141 0000000000000040 0000000000000010 16 9 8 1142 ...... 1143 -bash-4.4$ clang -S -g -O2 --target=bpf t2.c 1144 -bash-4.4$ cat t2.s 1145 ...... 1146 .section .BTF,"",@progbits 1147 .short 60319 # 0xeb9f 1148 .byte 1 1149 .byte 0 1150 .long 24 1151 .long 0 1152 .long 220 1153 .long 220 1154 .long 122 1155 .long 0 # BTF_KIND_FUNC_PROTO(id = 1) 1156 .long 218103808 # 0xd000000 1157 .long 2 1158 .long 83 # BTF_KIND_INT(id = 2) 1159 .long 16777216 # 0x1000000 1160 .long 4 1161 .long 16777248 # 0x1000020 1162 ...... 1163 .byte 0 # string offset=0 1164 .ascii ".text" # string offset=1 1165 .byte 0 1166 .ascii "/home/yhs/tmp-pahole/t2.c" # string offset=7 1167 .byte 0 1168 .ascii "int main() { return 0; }" # string offset=33 1169 .byte 0 1170 .ascii "int test() { return 0; }" # string offset=58 1171 .byte 0 1172 .ascii "int" # string offset=83 1173 ...... 1174 .section .BTF.ext,"",@progbits 1175 .short 60319 # 0xeb9f 1176 .byte 1 1177 .byte 0 1178 .long 24 1179 .long 0 1180 .long 28 1181 .long 28 1182 .long 44 1183 .long 8 # FuncInfo 1184 .long 1 # FuncInfo section string offset=1 1185 .long 2 1186 .long .Lfunc_begin0 1187 .long 3 1188 .long .Lfunc_begin1 1189 .long 5 1190 .long 16 # LineInfo 1191 .long 1 # LineInfo section string offset=1 1192 .long 2 1193 .long .Ltmp0 1194 .long 7 1195 .long 33 1196 .long 7182 # Line 7 Col 14 1197 .long .Ltmp3 1198 .long 7 1199 .long 58 1200 .long 8206 # Line 8 Col 14 1201 12027. Testing 1203========== 1204 1205The kernel BPF selftest `tools/testing/selftests/bpf/prog_tests/btf.c`_ 1206provides an extensive set of BTF-related tests. 1207 1208.. Links 1209.. _tools/testing/selftests/bpf/prog_tests/btf.c: 1210 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/prog_tests/btf.c 1211