Commit 61dbd598 authored by Yonghong Song's avatar Yonghong Song Committed by Alexei Starovoitov
Browse files

docs/bpf: Update documentation for BTF_KIND_ENUM64 support 



Add BTF_KIND_ENUM64 documentation in btf.rst.
Also fixed a typo for section number for BTF_KIND_TYPE_TAG
from 2.2.17 to 2.2.18, and fixed a type size issue for
BTF_KIND_ENUM.

Acked-by: default avatarAndrii Nakryiko <andrii@kernel.org>
Signed-off-by: default avatarYonghong Song <yhs@fb.com>
Link: https://lore.kernel.org/r/20220607062724.3728215-1-yhs@fb.com


Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parent f4db3dd5

Documentation/bpf/btf.rst

+37 −6
Original line number Diff line number Diff line
@@ -74,7 +74,7 @@ sequentially and type id is assigned to each recognized type starting from id 
    #define BTF_KIND_ARRAY          3       /* Array        */

    #define BTF_KIND_STRUCT         4       /* Struct       */

    #define BTF_KIND_UNION          5       /* Union        */

    #define BTF_KIND_ENUM           6       /* Enumeration  */

    #define BTF_KIND_ENUM           6       /* Enumeration up to 32-bit values */

    #define BTF_KIND_FWD            7       /* Forward      */

    #define BTF_KIND_TYPEDEF        8       /* Typedef      */

    #define BTF_KIND_VOLATILE       9       /* Volatile     */
@@ -87,6 +87,7 @@ sequentially and type id is assigned to each recognized type starting from id 
    #define BTF_KIND_FLOAT          16      /* Floating point       */

    #define BTF_KIND_DECL_TAG       17      /* Decl Tag     */

    #define BTF_KIND_TYPE_TAG       18      /* Type Tag     */

    #define BTF_KIND_ENUM64         19      /* Enumeration up to 64-bit values */



Note that the type section encodes debug info, not just pure types.

``BTF_KIND_FUNC`` is not a type, and it represents a defined subprogram.
@@ -101,10 +102,10 @@ Each type contains the following common data:: 
         * bits 24-28: kind (e.g. int, ptr, array...etc)

         * bits 29-30: unused

         * bit     31: kind_flag, currently used by

         *             struct, union and fwd

         *             struct, union, fwd, enum and enum64.

         */

        __u32 info;

        /* "size" is used by INT, ENUM, STRUCT and UNION.

        /* "size" is used by INT, ENUM, STRUCT, UNION and ENUM64.

         * "size" tells the size of the type it is describing.

         *

         * "type" is used by PTR, TYPEDEF, VOLATILE, CONST, RESTRICT,
@@ -281,10 +282,10 @@ modes exist: 


``struct btf_type`` encoding requirement:

  * ``name_off``: 0 or offset to a valid C identifier

  * ``info.kind_flag``: 0

  * ``info.kind_flag``: 0 for unsigned, 1 for signed

  * ``info.kind``: BTF_KIND_ENUM

  * ``info.vlen``: number of enum values

  * ``size``: 4

  * ``size``: 1/2/4/8



``btf_type`` is followed by ``info.vlen`` number of ``struct btf_enum``.::
@@ -297,6 +298,10 @@ The ``btf_enum`` encoding: 
  * ``name_off``: offset to a valid C identifier

  * ``val``: any value



If the original enum value is signed and the size is less than 4,

that value will be sign extended into 4 bytes. If the size is 8,

the value will be truncated into 4 bytes.



2.2.7 BTF_KIND_FWD

~~~~~~~~~~~~~~~~~~
@@ -493,7 +498,7 @@ the attribute is applied to a ``struct``/``union`` member or 
a ``func`` argument, and ``btf_decl_tag.component_idx`` should be a

valid index (starting from 0) pointing to a member or an argument.



2.2.17 BTF_KIND_TYPE_TAG

2.2.18 BTF_KIND_TYPE_TAG

~~~~~~~~~~~~~~~~~~~~~~~~



``struct btf_type`` encoding requirement:
@@ -516,6 +521,32 @@ type_tag, then zero or more const/volatile/restrict/typedef 
and finally the base type. The base type is one of

int, ptr, array, struct, union, enum, func_proto and float types.



2.2.19 BTF_KIND_ENUM64

~~~~~~~~~~~~~~~~~~~~~~



``struct btf_type`` encoding requirement:

  * ``name_off``: 0 or offset to a valid C identifier

  * ``info.kind_flag``: 0 for unsigned, 1 for signed

  * ``info.kind``: BTF_KIND_ENUM64

  * ``info.vlen``: number of enum values

  * ``size``: 1/2/4/8



``btf_type`` is followed by ``info.vlen`` number of ``struct btf_enum64``.::



    struct btf_enum64 {

        __u32   name_off;

        __u32   val_lo32;

        __u32   val_hi32;

    };



The ``btf_enum64`` encoding:

  * ``name_off``: offset to a valid C identifier

  * ``val_lo32``: lower 32-bit value for a 64-bit value

  * ``val_hi32``: high 32-bit value for a 64-bit value



If the original enum value is signed and the size is less than 8,

that value will be sign extended into 8 bytes.



3. BTF Kernel API

=================