Commit ea70faa1 authored by Ihor Solodrai's avatar Ihor Solodrai Committed by Andrii Nakryiko
Browse files

docs/bpf: Document the semantics of BTF tags with kind_flag 



Explain the meaning of kind_flag in BTF type_tags and decl_tags.
Update uapi btf.h kind_flag comment to reflect the changes.

Signed-off-by: default avatarIhor Solodrai <ihor.solodrai@linux.dev>
Signed-off-by: default avatarAndrii Nakryiko <andrii@kernel.org>
Link: https://lore.kernel.org/bpf/20250130201239.1429648-3-ihor.solodrai@linux.dev
parent 51d1b1d4

Documentation/bpf/btf.rst

+21 −4
Original line number Diff line number Diff line
@@ -102,7 +102,8 @@ 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, fwd, enum and enum64.

         *             struct, union, enum, fwd, enum64,

         *             decl_tag and type_tag

         */

        __u32 info;

        /* "size" is used by INT, ENUM, STRUCT, UNION and ENUM64.
@@ -478,7 +479,7 @@ No additional type data follow ``btf_type``. 


``struct btf_type`` encoding requirement:

 * ``name_off``: offset to a non-empty string

 * ``info.kind_flag``: 0

 * ``info.kind_flag``: 0 or 1

 * ``info.kind``: BTF_KIND_DECL_TAG

 * ``info.vlen``: 0

 * ``type``: ``struct``, ``union``, ``func``, ``var`` or ``typedef``
@@ -489,7 +490,6 @@ No additional type data follow ``btf_type``. 
        __u32   component_idx;

    };



The ``name_off`` encodes btf_decl_tag attribute string.

The ``type`` should be ``struct``, ``union``, ``func``, ``var`` or ``typedef``.

For ``var`` or ``typedef`` type, ``btf_decl_tag.component_idx`` must be ``-1``.

For the other three types, if the btf_decl_tag attribute is
@@ -499,12 +499,21 @@ 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.



If ``info.kind_flag`` is 0, then this is a normal decl tag, and the

``name_off`` encodes btf_decl_tag attribute string.



If ``info.kind_flag`` is 1, then the decl tag represents an arbitrary

__attribute__. In this case, ``name_off`` encodes a string

representing the attribute-list of the attribute specifier. For

example, for an ``__attribute__((aligned(4)))`` the string's contents

is ``aligned(4)``.



2.2.18 BTF_KIND_TYPE_TAG

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



``struct btf_type`` encoding requirement:

 * ``name_off``: offset to a non-empty string

 * ``info.kind_flag``: 0

 * ``info.kind_flag``: 0 or 1

 * ``info.kind``: BTF_KIND_TYPE_TAG

 * ``info.vlen``: 0

 * ``type``: the type with ``btf_type_tag`` attribute
@@ -522,6 +531,14 @@ 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.



Similarly to decl tags, if the ``info.kind_flag`` is 0, then this is a

normal type tag, and the ``name_off`` encodes btf_type_tag attribute

string.



If ``info.kind_flag`` is 1, then the type tag represents an arbitrary

__attribute__, and the ``name_off`` encodes a string representing the

attribute-list of the attribute specifier.



2.2.19 BTF_KIND_ENUM64

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

include/uapi/linux/btf.h

+2 −1
Original line number Diff line number Diff line
@@ -36,7 +36,8 @@ struct btf_type { 
	 * bits 24-28: kind (e.g. int, ptr, array...etc)

	 * bits 29-30: unused

	 * bit     31: kind_flag, currently used by

	 *             struct, union, enum, fwd and enum64

	 *             struct, union, enum, fwd, enum64,

	 *             decl_tag and type_tag

	 */

	__u32 info;

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

tools/include/uapi/linux/btf.h

+2 −1
Original line number Diff line number Diff line
@@ -36,7 +36,8 @@ struct btf_type { 
	 * bits 24-28: kind (e.g. int, ptr, array...etc)

	 * bits 29-30: unused

	 * bit     31: kind_flag, currently used by

	 *             struct, union, enum, fwd and enum64

	 *             struct, union, enum, fwd, enum64,

	 *             decl_tag and type_tag

	 */

	__u32 info;

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