ref-manual/variables: document KMETA* and KCONF_AUDIT* variables

Document the variables used to control the outcome of the kernel
configuration auditing done by the kernel-yocto bbclass.

[YOCTO #13835]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/variables.rst | 61 ++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)


---
base-commit: 9f1f9f1a3a2a541ed70df72d4fe391b5b7fd3733
change-id: 20250225-kmeta-audit-vars-826afcf0ee7a

Best regards,

Looks good to me.

Acked-by: Bruce Ashfield <bruce.ashfield@gmail.com>

On Tue, Feb 25, 2025 at 8:42 AM Antonin Godard <antonin.godard@bootlin.com>
wrote:

> Document the variables used to control the outcome of the kernel
> configuration auditing done by the kernel-yocto bbclass.
>
> [YOCTO #13835]
>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>  documentation/ref-manual/variables.rst | 61
> ++++++++++++++++++++++++++++++++++
>  1 file changed, 61 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst
> b/documentation/ref-manual/variables.rst
> index
> adbef69d8f39d33be87c5db6688a807156540410..c842774f0d383e34077b2e558c3347f2abcdb7d2
> 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4563,6 +4563,53 @@ system and gives an overview of their function and
> contents.
>        ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`"
>        section in the Yocto Project Linux Kernel Development Manual.
>
> +   :term:`KCONF_AUDIT_LEVEL`
> +      When inheriting the :ref:`ref-classes-kernel-yocto` class, the
> +      :term:`KCONF_AUDIT_LEVEL` variable specifies whether to report
> Kernel
> +      configuration values that are different from the user-specified
> value. Its
> +      value is either 0 or 1 (default: 1):
> +
> +      -  0: no reporting is done.
> +
> +      -  1: report the problems as warnings and trigger and error if
> +         :term:`KMETA_AUDIT_WERROR` is set.
> +
> +      For more details see the :ref:`ref-classes-kernel-yocto` class and
> the
> +      :yocto_git:`symbol_why.py
> </yocto-kernel-tools/tree/tools/symbol_why.py>`
> +      script in :yocto_git:`yocto-kernel-tools </yocto-kernel-tools>`.
> +
> +   :term:`KCONF_BSP_AUDIT_LEVEL`
> +      When inheriting the :ref:`ref-classes-kernel-yocto` class, the
> +      :term:`KCONF_BSP_AUDIT_LEVEL` variable can be set to report:
> +
> +      #.  User-specified Kernel configurations that did not make it into
> the final
> +          Kernel configuration.
> +
> +      #.  Configurations defined in multiple input files with differing
> values.
> +
> +      Its value is a positive integer (default: 0):
> +
> +      -  0: no reporting is done.
> +
> +      -  1: reporting of configuration options that did not make it in the
> +         final configuration is done and is not limited to the current
> +         architecture (``ARCH``) in use.
> +
> +      -  2: reporting of configuration options that did not make it in the
> +         final configuration is done and is strictly limited to the
> current
> +         architecture (``ARCH``) in use.
> +
> +      -  3: report the problems found when this variable is equals 2, and
> also
> +         report configurations options defined in multiple input files
> with
> +         differing values.
> +
> +      For value 1, 2 and 3 an error is produced if
> :term:`KMETA_AUDIT_WERROR`
> +      is set.
> +
> +      For more details see the :ref:`ref-classes-kernel-yocto` class and
> the
> +      :yocto_git:`symbol_why.py
> </yocto-kernel-tools/tree/tools/symbol_why.py>`
> +      script in :yocto_git:`yocto-kernel-tools </yocto-kernel-tools>`.
> +
>     :term:`KCONFIG_MODE`
>        When used with the :ref:`ref-classes-kernel-yocto`
>        class, specifies the kernel configuration values to use for options
> @@ -4967,6 +5014,20 @@ system and gives an overview of their function and
> contents.
>        However, the OpenEmbedded build system understands the machine as
>        "core2-32-intel-common".
>
> +   :term:`KMETA_AUDIT`
> +      When inheriting the :ref:`ref-classes-kernel-yocto` class, the
> +      :term:`KMETA_AUDIT` variable enables or disables auditing of Linux
> Kernel
> +      configuration. The default value for this variable is "yes", and
> auditing
> +      is enabled. Set this variable to an empty string to disable
> auditing.
> +
> +   :term:`KMETA_AUDIT_WERROR`
> +      When inheriting the :ref:`ref-classes-kernel-yocto` class and when
> the
> +      :term:`KMETA_AUDIT` variable is set, when the
> :term:`KMETA_AUDIT_WERROR`
> +      variable is set to a non-empty string, produce an error if Linux
> kernel
> +      configuration problems were detected, instead of warnings only. For
> more
> +      details on the Linux Kernel configuration auditing feature, see
> +      :term:`KCONF_AUDIT_LEVEL` and :term:`KCONF_BSP_AUDIT_LEVEL`.
> +
>     :term:`KTYPE`
>        Defines the kernel type to be used in assembling the configuration.
>        The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
>
> ---
> base-commit: 9f1f9f1a3a2a541ed70df72d4fe391b5b7fd3733
> change-id: 20250225-kmeta-audit-vars-826afcf0ee7a
>
> Best regards,
> --
> Antonin Godard <antonin.godard@bootlin.com>
>
>

Hi Antonin,

On 2/25/25 2:42 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Document the variables used to control the outcome of the kernel
> configuration auditing done by the kernel-yocto bbclass.
> 
> [YOCTO #13835]
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/ref-manual/variables.rst | 61 ++++++++++++++++++++++++++++++++++
>   1 file changed, 61 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index adbef69d8f39d33be87c5db6688a807156540410..c842774f0d383e34077b2e558c3347f2abcdb7d2 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4563,6 +4563,53 @@ system and gives an overview of their function and contents.
>         ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`"
>         section in the Yocto Project Linux Kernel Development Manual.
>   
> +   :term:`KCONF_AUDIT_LEVEL`
> +      When inheriting the :ref:`ref-classes-kernel-yocto` class, the
> +      :term:`KCONF_AUDIT_LEVEL` variable specifies whether to report Kernel
> +      configuration values that are different from the user-specified value. Its
> +      value is either 0 or 1 (default: 1):
> +
> +      -  0: no reporting is done.
> +
> +      -  1: report the problems as warnings and trigger and error if

s/and/an/ ?

> +         :term:`KMETA_AUDIT_WERROR` is set.
> +

There's also 2!

C.f. comment above the variable default and at the end of 
do_kernel_configme.

> +      For more details see the :ref:`ref-classes-kernel-yocto` class and the
> +      :yocto_git:`symbol_why.py </yocto-kernel-tools/tree/tools/symbol_why.py>`
> +      script in :yocto_git:`yocto-kernel-tools </yocto-kernel-tools>`.
> +

KMETA_AUDIT needs to be anything but the empty string too for this to 
apply, no?

> +   :term:`KCONF_BSP_AUDIT_LEVEL`
> +      When inheriting the :ref:`ref-classes-kernel-yocto` class, the
> +      :term:`KCONF_BSP_AUDIT_LEVEL` variable can be set to report:
> +
> +      #.  User-specified Kernel configurations that did not make it into the final
> +          Kernel configuration.
> +
> +      #.  Configurations defined in multiple input files with differing values.
> +
> +      Its value is a positive integer (default: 0):
> +
> +      -  0: no reporting is done.
> +
> +      -  1: reporting of configuration options that did not make it in the
> +         final configuration is done and is not limited to the current
> +         architecture (``ARCH``) in use.
> +
> +      -  2: reporting of configuration options that did not make it in the
> +         final configuration is done and is strictly limited to the current
> +         architecture (``ARCH``) in use.
> +
> +      -  3: report the problems found when this variable is equals 2, and also

-is

> +         report configurations options defined in multiple input files with
> +         differing values.
> +
> +      For value 1, 2 and 3 an error is produced if :term:`KMETA_AUDIT_WERROR`
> +      is set.
> +
> +      For more details see the :ref:`ref-classes-kernel-yocto` class and the
> +      :yocto_git:`symbol_why.py </yocto-kernel-tools/tree/tools/symbol_why.py>`
> +      script in :yocto_git:`yocto-kernel-tools </yocto-kernel-tools>`.
> +
>      :term:`KCONFIG_MODE`
>         When used with the :ref:`ref-classes-kernel-yocto`
>         class, specifies the kernel configuration values to use for options
> @@ -4967,6 +5014,20 @@ system and gives an overview of their function and contents.
>         However, the OpenEmbedded build system understands the machine as
>         "core2-32-intel-common".
>   
> +   :term:`KMETA_AUDIT`
> +      When inheriting the :ref:`ref-classes-kernel-yocto` class, the
> +      :term:`KMETA_AUDIT` variable enables or disables auditing of Linux Kernel
> +      configuration. The default value for this variable is "yes", and auditing
> +      is enabled. Set this variable to an empty string to disable auditing.
> +
> +   :term:`KMETA_AUDIT_WERROR`
> +      When inheriting the :ref:`ref-classes-kernel-yocto` class and when the

s/and //

and maybe even

s/and when //

> +      :term:`KMETA_AUDIT` variable is set, when the :term:`KMETA_AUDIT_WERROR`

s/, when/ and/ if you take the second search and replace above.

Aside from this, not too familiar with the code and won't have time to 
dig into it, so don't wait for further review from me :)

Cheers,
Quentin

Hi Quentin,

On Mon Mar 3, 2025 at 5:40 PM CET, Quentin Schulz wrote:
[...]
> Aside from this, not too familiar with the code and won't have time to 
> dig into it, so don't wait for further review from me :)

Thanks a lot for the review! I'll send a v2 soon.

Antonin