netdev - Re: [PATCH bpf-next] bpf: btf: add btf documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Date:   Fri, 18 Jan 2019 01:46:40 +0000
From:   Yonghong Song <yhs@...com>
To:     Edward Cree <ecree@...arflare.com>,
        Alexei Starovoitov <ast@...com>,
        "daniel@...earbox.net" <daniel@...earbox.net>,
        "netdev@...r.kernel.org" <netdev@...r.kernel.org>
CC:     Kernel Team <Kernel-team@...com>
Subject: Re: [PATCH bpf-next] bpf: btf: add btf documentation



On 1/17/19 7:13 AM, Edward Cree wrote:
> On 16/01/19 00:58, Yonghong Song wrote:
>> This patch added documentation for BTF (BPF Debug Format).
>> The document is placed under linux:Documentation/bpf directory.
>>
>> Signed-off-by: Yonghong Song <yhs@...com>
> I like this a lot overall, it does a good job of explaining how the
>   various pieces fit together.
> See inline for review comments.
> 
>> ---
>>   Documentation/bpf/btf.rst   | 787 ++++++++++++++++++++++++++++++++++++
>>   Documentation/bpf/index.rst |   7 +
>>   2 files changed, 794 insertions(+)
>>   create mode 100644 Documentation/bpf/btf.rst
>>
>> diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
>> new file mode 100644
>> index 000000000000..3dfa8edd22ac
>> --- /dev/null
>> +++ b/Documentation/bpf/btf.rst
>> @@ -0,0 +1,787 @@
>> +=====================
>> +BPF Type Format (BTF)
>> +=====================
>> +
>> +1. Introduction
>> +***************
>> +
>> +BTF (BPF Type Format) is the meta data format which
>> +encodes the debug info related to BPF program/map.
>> +The name BTF was used initially to describe
>> +data types. The BTF was later extended to include
>> +function info for defined subroutines, and line info
>> +for source/line information.

[...]

>> +2.2.1 BTF_KIND_INT
>> +~~~~~~~~~~~~~~~~~~
>> +
>> +``struct btf_type`` encoding requirement:
>> + * ``name_off``: any valid offset
>> + * ``info.kind_flag``: 0
>> + * ``info.kind``: BTF_KIND_INT
>> + * ``info.vlen``: 0
>> + * ``size``: the size of the int type in bytes.
>> +
>> +``btf_type`` is followed by a ``u32`` with following bits arrangement::
>> +
>> +  #define BTF_INT_ENCODING(VAL)   (((VAL) & 0x0f000000) >> 24)
>> +  #define BTF_INT_OFFSET(VAL)     (((VAL  & 0x00ff0000)) >> 16)
>> +  #define BTF_INT_BITS(VAL)       ((VAL)  & 0x000000ff)
>> +
>> +The ``BTF_INT_ENCODING`` has the following attributes::
>> +
>> +  #define BTF_INT_SIGNED  (1 << 0)
>> +  #define BTF_INT_CHAR    (1 << 1)
>> +  #define BTF_INT_BOOL    (1 << 2)
>> +
>> +The ``BTF_INT_ENCODING()`` provides extra information, signness,
>> +char, or bool, for the int type. The char and bool encoding
>> +are mostly useful for pretty print. At most one encoding can
>> +be specified for the int type.
>> +
>> +The ``BTF_INT_OFFSET()`` specifies the starting bit offset to
>> +calculate values for this int.
> That really doesn't make clear, at least to me, what this field is for.

The original intention is to help specify the bitfield offset.
But in practice, the bitfield offset is specified in the struct member,
so this field is 0 currently by pahole and llvm.

If this BTF_INT_OFFSET() is not 0, say 2, and struct member offset for 
this int type is 100, then the value offset will be 102. But this
probably not necessary as you can just specify member offset 102.

I will add more explanation here.

>> Typically it should be 0 and
>> +currently both llvm and pahole generates ``BTF_INT_OFFSET() = 0``.
>> +
>> +The ``BTF_INT_BITS()`` specifies the number of actual bits held by
>> +this int type. For example, a 4-bit bitfield encodes
>> +``BTF_INT_BITS()`` equals to 4. The ``btf_type.size * 8``
>> +must be equal to or greater than ``BTF_INT_BITS()`` for the type.
>> +The maximum value of ``BTF_INT_BITS()`` is 128.
>> +