[PATCH] ref-manual/variables: document KMETA* and KCONF_AUDIT* variables

[PATCH] ref-manual/variables: document KMETA* and KCONF_AUDIT* variables

[Antonin Godard]

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>

Re: [PATCH] ref-manual/variables: document KMETA* and KCONF_AUDIT* variables

[Bruce Ashfield]

[-- Attachment #1: Type: text/plain, Size: 5076 bytes --]

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>
>
>

-- 
- Thou shalt not follow the NULL pointer, for chaos and madness await thee
at its end
- "Use the force Harry" - Gandalf, Star Trek II

[-- Attachment #2: Type: text/html, Size: 6325 bytes --]

Re: [docs] [PATCH] ref-manual/variables: document KMETA* and KCONF_AUDIT* variables

[Quentin Schulz]

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

Re: [docs] [PATCH] ref-manual/variables: document KMETA* and KCONF_AUDIT* variables

[Antonin Godard]

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

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com