Documentation/bpf/btf.rst

2 BPF Type Format (BTF)
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
18 The BTF specification contains two parts,
19   * BTF kernel API
20   * BTF ELF file format
23 verifies the BTF info before using it. The ELF file format is a user space
26 The type and string sections are part of the BTF kernel API, describing the
32 2. BTF Type and String Encoding
54 endian systems, and can be used to test whether BTF is generated for big- or
211 Currently in BTF, beyond type verification, the ``index_type`` is not used.
225 more BTF usage is explored, pahole and llvm can be changed to generate proper
455 3. BTF Kernel API
458 The following bpf syscall command involves BTF:
459    * BPF_BTF_LOAD: load a blob of BTF data into kernel
501 Load a blob of BTF data into kernel. A blob of data, described in
510     __u32   btf_fd;         /* fd pointing to a BTF type data */
511     __u32   btf_key_type_id;        /* BTF type_id of the key */
512     __u32   btf_value_type_id;      /* BTF type_id of the value */
542     __u32           prog_btf_fd;    /* fd pointing to BTF type data */
602 information from kernel about this fd, some of which are BTF-related. For
622 4.1 .BTF section
625 The .BTF section contains type and string data. The format of this section is
630 4.2 .BTF.ext section
633 The .BTF.ext section encodes func_info and line_info which needs loader
636 The specification for .BTF.ext section is defined at ``tools/lib/bpf/btf.h``
639 The current header of .BTF.ext section::
654 It is very similar to .BTF section. Instead of type/string section, it
666 .BTF.ext is generated. ``btf_ext_info_sec``, defined below, is a collection of
686 .BTF.ext is generated.
697 The .BTF_ids section encodes BTF ID values that are used within the kernel.
701 use them to create lists and sets (sorted lists) of BTF ID values.
703 The ``BTF_ID_LIST`` and ``BTF_ID`` macros define unsorted list of BTF ID values,
727 The ``BTF_SET_START/END`` macros pair defines sorted list of BTF ID values
750 and is used as a filter when resolving the BTF ID value.
752 All the BTF ID lists and sets are compiled in the .BTF_ids section and
755 5. Using BTF
761 With BTF, the map key/value can be printed based on fields rather than simply
860 6. BTF Generation
868 support .BTF.ext and btf BTF_KIND_FUNC type yet. For example,::
885 The llvm is able to generate .BTF and .BTF.ext directly with -g for bpf target
886 only. The assembly code (-S) is able to show the BTF encoding in assembly
901       [ 8] .BTF              PROGBITS         0000000000000000  00000247
903       [ 9] .BTF.ext          PROGBITS         0000000000000000  000003b5
905       [10] .rel.BTF.ext      REL              0000000000000000  000007e0
911             .section        .BTF,"",@progbits
939             .section        .BTF.ext,"",@progbits
970 Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests.