docs/bpf: Add constant values for linkages

Commit Message

Will Hawkins Aug. 19, 2024, 10:30 p.m. UTC

Make the values of the symbolic constants that define the valid linkages
for functions and variables explicit.

Signed-off-by: Will Hawkins <[e-mail]>
---
 Documentation/bpf/btf.rst | 44 +++++++++++++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 4 deletions(-)

Comments

Yonghong Song Aug. 21, 2024, 9:29 p.m. UTC | #1

On 8/19/24 3:30 PM, Will Hawkins wrote:
> Make the values of the symbolic constants that define the valid linkages
> for functions and variables explicit.
>
> Signed-off-by: Will Hawkins <[e-mail]>
> ---
>   Documentation/bpf/btf.rst | 44 +++++++++++++++++++++++++++++++++++----
>   1 file changed, 40 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
> index 257a7e1cdf5d..cce03f1e552a 100644
> --- a/Documentation/bpf/btf.rst
> +++ b/Documentation/bpf/btf.rst
> @@ -368,7 +368,7 @@ No additional type data follow ``btf_type``.
>     * ``info.kind_flag``: 0
>     * ``info.kind``: BTF_KIND_FUNC
>     * ``info.vlen``: linkage information (BTF_FUNC_STATIC, BTF_FUNC_GLOBAL
> -                   or BTF_FUNC_EXTERN)
> +                   or BTF_FUNC_EXTERN - see :ref:`BTF_Function_Linkage_Constants`)
>     * ``type``: a BTF_KIND_FUNC_PROTO type
>   
>   No additional type data follow ``btf_type``.
> @@ -424,9 +424,9 @@ following data::
>           __u32   linkage;
>       };
>   
> -``struct btf_var`` encoding:
> -  * ``linkage``: currently only static variable 0, or globally allocated
> -                 variable in ELF sections 1
> +``btf_var.linkage`` may take the values: BTF_VAR_STATIC (for a static variable),
> +or BTF_VAR_GLOBAL_ALLOCATED (for a globally allocated variable stored in ELF sections 1) -

Let us remove the above '1', just say '(... stored in explicit ELF sections)'.

Actually, for btf_var linkage, we actually have 3 values. See

enum {
	BTF_VAR_STATIC = 0,
	BTF_VAR_GLOBAL_ALLOCATED = 1,
	BTF_VAR_GLOBAL_EXTERN = 2,
};

See https://github.com/torvalds/linux/blob/master/include/uapi/linux/btf.h#L150-L154

Similar to BTF_VAR_GLOBAL_ALLOCATED, BTF_VAR_GLOBAL_EXTERN is encoded in datasec only
if the variable is stored in explicit ELF sections.

Since you are touching this doc, could you add BTF_VAR_GLOBAL_EXTERN as well?

> +see :ref:`BTF_Var_Linkage_Constants`.
>   
>   Not all type of global variables are supported by LLVM at this point.
>   The following is currently available:
> @@ -549,6 +549,42 @@ The ``btf_enum64`` encoding:
>   If the original enum value is signed and the size is less than 8,
>   that value will be sign extended into 8 bytes.
>   
> +2.3 Constant Values
> +-------------------
> +
> +.. _BTF_Function_Linkage_Constants:
> +
> +2.3.1 Function Linkage Constant Values
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +.. list-table::
> +   :widths: 1 1
> +   :header-rows: 1
> +
> +   * - Name
> +     - Value
> +   * - ``BTF_FUNC_STATIC``
> +     - ``0``
> +   * - ``BTF_FUNC_GLOBAL``
> +     - ``1``
> +   * - ``BTF_FUNC_EXTERN``
> +     - ``2``
> +
> +.. _BTF_Var_Linkage_Constants:
> +
> +2.3.2 Variable Linkage Constant Values
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +.. list-table::
> +   :widths: 1 1
> +   :header-rows: 1
> +
> +   * - Name
> +     - Value
> +   * - ``BTF_VAR_STATIC``
> +     - ``0``
> +   * - ``BTF_VAR_GLOBAL_ALLOCATED``
> +     - ``1``
> +
> +

Form the above, could you use similar format as in Documentation/bpf/standardization/instruction-set.rst? For example,

.. table:: Instruction class

   =====  =====  ===============================  ===================================
   class  value  description                      reference
   =====  =====  ===============================  ===================================
   LD     0x0    non-standard load operations     `Load and store instructions`_
   LDX    0x1    load into register operations    `Load and store instructions`_
   ST     0x2    store from immediate operations  `Load and store instructions`_
   STX    0x3    store from register operations   `Load and store instructions`_
   ALU    0x4    32-bit arithmetic operations     `Arithmetic and jump instructions`_
   JMP    0x5    64-bit jump operations           `Arithmetic and jump instructions`_
   JMP32  0x6    32-bit jump operations           `Arithmetic and jump instructions`_
   ALU64  0x7    64-bit arithmetic operations     `Arithmetic and jump instructions`_
   =====  =====  ===============================  ===================================

I would like we have consistant table presentation between instruction set and btf.

>   3. BTF Kernel API
>   =================
>

Will Hawkins Aug. 21, 2024, 9:35 p.m. UTC | #2

On Wed, Aug 21, 2024 at 5:30 PM Yonghong Song <[e-mail]> wrote:
>
>
> On 8/19/24 3:30 PM, Will Hawkins wrote:
> > Make the values of the symbolic constants that define the valid linkages
> > for functions and variables explicit.
> >
> > Signed-off-by: Will Hawkins <[e-mail]>
> > ---
> >   Documentation/bpf/btf.rst | 44 +++++++++++++++++++++++++++++++++++----
> >   1 file changed, 40 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
> > index 257a7e1cdf5d..cce03f1e552a 100644
> > --- a/Documentation/bpf/btf.rst
> > +++ b/Documentation/bpf/btf.rst
> > @@ -368,7 +368,7 @@ No additional type data follow ``btf_type``.
> >     * ``info.kind_flag``: 0
> >     * ``info.kind``: BTF_KIND_FUNC
> >     * ``info.vlen``: linkage information (BTF_FUNC_STATIC, BTF_FUNC_GLOBAL
> > -                   or BTF_FUNC_EXTERN)
> > +                   or BTF_FUNC_EXTERN - see :ref:`BTF_Function_Linkage_Constants`)
> >     * ``type``: a BTF_KIND_FUNC_PROTO type
> >
> >   No additional type data follow ``btf_type``.
> > @@ -424,9 +424,9 @@ following data::
> >           __u32   linkage;
> >       };
> >
> > -``struct btf_var`` encoding:
> > -  * ``linkage``: currently only static variable 0, or globally allocated
> > -                 variable in ELF sections 1
> > +``btf_var.linkage`` may take the values: BTF_VAR_STATIC (for a static variable),
> > +or BTF_VAR_GLOBAL_ALLOCATED (for a globally allocated variable stored in ELF sections 1) -
>
> Let us remove the above '1', just say '(... stored in explicit ELF sections)'.

Great! I only kept that because it was there in the existing documentation!

>
> Actually, for btf_var linkage, we actually have 3 values. See
>
> enum {
>         BTF_VAR_STATIC = 0,
>         BTF_VAR_GLOBAL_ALLOCATED = 1,
>         BTF_VAR_GLOBAL_EXTERN = 2,
> };
>
> See https://github.com/torvalds/linux/blob/master/include/uapi/linux/btf.h#L150-L154
>

Great! I will make that update!

> Similar to BTF_VAR_GLOBAL_ALLOCATED, BTF_VAR_GLOBAL_EXTERN is encoded in datasec only
> if the variable is stored in explicit ELF sections.
>
> Since you are touching this doc, could you add BTF_VAR_GLOBAL_EXTERN as well?
>

Of course!

> > +see :ref:`BTF_Var_Linkage_Constants`.
> >
> >   Not all type of global variables are supported by LLVM at this point.
> >   The following is currently available:
> > @@ -549,6 +549,42 @@ The ``btf_enum64`` encoding:
> >   If the original enum value is signed and the size is less than 8,
> >   that value will be sign extended into 8 bytes.
> >
> > +2.3 Constant Values
> > +-------------------
> > +
> > +.. _BTF_Function_Linkage_Constants:
> > +
> > +2.3.1 Function Linkage Constant Values
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +.. list-table::
> > +   :widths: 1 1
> > +   :header-rows: 1
> > +
> > +   * - Name
> > +     - Value
> > +   * - ``BTF_FUNC_STATIC``
> > +     - ``0``
> > +   * - ``BTF_FUNC_GLOBAL``
> > +     - ``1``
> > +   * - ``BTF_FUNC_EXTERN``
> > +     - ``2``
> > +
> > +.. _BTF_Var_Linkage_Constants:
> > +
> > +2.3.2 Variable Linkage Constant Values
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +.. list-table::
> > +   :widths: 1 1
> > +   :header-rows: 1
> > +
> > +   * - Name
> > +     - Value
> > +   * - ``BTF_VAR_STATIC``
> > +     - ``0``
> > +   * - ``BTF_VAR_GLOBAL_ALLOCATED``
> > +     - ``1``
> > +
> > +
>
> Form the above, could you use similar format as in Documentation/bpf/standardization/instruction-set.rst? For example,
>
> .. table:: Instruction class
>
>    =====  =====  ===============================  ===================================
>    class  value  description                      reference
>    =====  =====  ===============================  ===================================
>    LD     0x0    non-standard load operations     `Load and store instructions`_
>    LDX    0x1    load into register operations    `Load and store instructions`_
>    ST     0x2    store from immediate operations  `Load and store instructions`_
>    STX    0x3    store from register operations   `Load and store instructions`_
>    ALU    0x4    32-bit arithmetic operations     `Arithmetic and jump instructions`_
>    JMP    0x5    64-bit jump operations           `Arithmetic and jump instructions`_
>    JMP32  0x6    32-bit jump operations           `Arithmetic and jump instructions`_
>    ALU64  0x7    64-bit arithmetic operations     `Arithmetic and jump instructions`_
>    =====  =====  ===============================  ===================================
>
> I would like we have consistant table presentation between instruction set and btf.
>

Absolutely. I volunteered to edit the document that will ultimately
turn into the IETF spec draft for BTF and this is the first fix that
jumped out to me when I was proofreading.

Thank you for the review! I will have a v2 of the patch in just a few minutes!

Thank you, again!
Will


> >   3. BTF Kernel API
> >   =================
> >

Patch

diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
index 257a7e1cdf5d..cce03f1e552a 100644
--- a/Documentation/bpf/btf.rst
+++ b/Documentation/bpf/btf.rst
@@ -368,7 +368,7 @@  No additional type data follow ``btf_type``.
   * ``info.kind_flag``: 0
   * ``info.kind``: BTF_KIND_FUNC
   * ``info.vlen``: linkage information (BTF_FUNC_STATIC, BTF_FUNC_GLOBAL
-                   or BTF_FUNC_EXTERN)
+                   or BTF_FUNC_EXTERN - see :ref:`BTF_Function_Linkage_Constants`)
   * ``type``: a BTF_KIND_FUNC_PROTO type
 
 No additional type data follow ``btf_type``.
@@ -424,9 +424,9 @@  following data::
         __u32   linkage;
     };
 
-``struct btf_var`` encoding:
-  * ``linkage``: currently only static variable 0, or globally allocated
-                 variable in ELF sections 1
+``btf_var.linkage`` may take the values: BTF_VAR_STATIC (for a static variable),
+or BTF_VAR_GLOBAL_ALLOCATED (for a globally allocated variable stored in ELF sections 1) -
+see :ref:`BTF_Var_Linkage_Constants`.
 
 Not all type of global variables are supported by LLVM at this point.
 The following is currently available:
@@ -549,6 +549,42 @@  The ``btf_enum64`` encoding:
 If the original enum value is signed and the size is less than 8,
 that value will be sign extended into 8 bytes.
 
+2.3 Constant Values
+-------------------
+
+.. _BTF_Function_Linkage_Constants:
+
+2.3.1 Function Linkage Constant Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. list-table::
+   :widths: 1 1
+   :header-rows: 1
+
+   * - Name
+     - Value
+   * - ``BTF_FUNC_STATIC``
+     - ``0``
+   * - ``BTF_FUNC_GLOBAL``
+     - ``1``
+   * - ``BTF_FUNC_EXTERN``
+     - ``2``
+
+.. _BTF_Var_Linkage_Constants:
+
+2.3.2 Variable Linkage Constant Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. list-table::
+   :widths: 1 1
+   :header-rows: 1
+
+   * - Name
+     - Value
+   * - ``BTF_VAR_STATIC``
+     - ``0``
+   * - ``BTF_VAR_GLOBAL_ALLOCATED``
+     - ``1``
+
+
 3. BTF Kernel API
 =================