diff mbox series

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

Message ID 20250305-kmeta-audit-vars-v2-1-aa6bb0d514e4@bootlin.com
State Accepted
Headers show
Series [v2] ref-manual/variables: document KMETA* and KCONF_AUDIT* variables | expand

Commit Message

Antonin Godard March 5, 2025, 8:40 a.m. UTC
Document the variables used to control the outcome of the kernel
configuration auditing done by the kernel-yocto bbclass.

[YOCTO #13835]

Acked-by: Bruce Ashfield <bruce.ashfield@gmail.com>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v2:
- Typos and suggestions from Quentin Schulz (thank you!)
- Link to v1: https://lore.kernel.org/r/20250225-kmeta-audit-vars-v1-1-d39d3e253b00@bootlin.com
---
 documentation/ref-manual/variables.rst | 68 ++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)


---
base-commit: 36fb1e9e5099aa0d858d5478530143e9bac39588
change-id: 20250225-kmeta-audit-vars-826afcf0ee7a

Best regards,
diff mbox series

Patch

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 60984cc8f34cb7529968f7ba45cc918bcccd0710..0e5c8fefaf3b145555dd0d236be32fe6d4ff7179 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4572,6 +4572,60 @@  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 and when the
+      :term:`KMETA_AUDIT` variable is set to a non-empty string, the
+      :term:`KCONF_AUDIT_LEVEL` variable specifies whether to report Kernel
+      configuration values that are different from the user-specified value. Its
+      value is a positive integer (default: 1):
+
+      -  0: no reporting is done.
+
+      -  1: report the problems as warnings and trigger an error if
+         :term:`KMETA_AUDIT_WERROR` is set.
+
+      -  2: if the :ref:`ref-tasks-kernel_configme` has failed to generate a
+         ``.config`` file, print the content of the ``merge_config_build.log``
+         file containing the errors, instead of just providing the path to
+         that file.
+
+      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 and when the
+      :term:`KMETA_AUDIT` variable is set to a non-empty string, 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 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
@@ -4976,6 +5030,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` and the :term:`KMETA_AUDIT_WERROR` variables are set
+      to non-empty strings, 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"