[PATCH v2] kernel-dev: document KCONFIG_MODE

[PATCH v2] kernel-dev: document KCONFIG_MODE

[Daniel Wagenknecht]

Signed-off-by: Daniel Wagenknecht <dwagenknecht@emlix.com>
---
 documentation/kernel-dev/common.rst    |  9 ++++++
 documentation/ref-manual/variables.rst | 38 ++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 3f35d8412..5935d6f56 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -650,6 +650,15 @@ extends the :term:`FILESPATH`
 variable (search directories) to include the ``${PN}`` directory you
 created to hold the configuration changes.
 
+You can also use a regular ``defconfig`` file, as generated by the
+:ref:`ref-tasks-savedefconfig`
+task instead of a complete ``.config`` file. This only specifies the
+non-default configuration values.  You need to additionally set
+:term:`KCONFIG_MODE`
+in the linux-yocto ``.bbappend`` file in your layer::
+
+   KCONFIG_MODE = "alldefconfig"
+
 .. note::
 
    The build system applies the configurations from the ``defconfig``
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index c339d45e1..a2db34520 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3745,6 +3745,44 @@ 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:`KCONFIG_MODE`
+      When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
+      class, specifies the kernel configuration values to use for options
+      not specified in the provided ``defconfig`` file. Valid options are::
+
+         KCONFIG_MODE = "alldefconfig"
+         KCONFIG_MODE = "allnoconfig"
+
+      In ``alldefconfig`` mode the options not explicitely specified will be
+      assigned their Kconfig default value. In ``allnoconfig`` mode the
+      options not explicitely specified will be disabled in the kernel
+      config.
+
+      In case ``KCONFIG_MODE`` is unset the behaviour will depend on where
+      the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file
+      will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed
+      in ``${WORKDIR}`` through a meta-layer will be handled in
+      ``allnoconfig`` mode.
+
+      An "in-tree" ``defconfig`` file can be selected via the
+      :term:`KBUILD_DEFCONFIG` variable. ``KCONFIG_MODE`` does not need to
+      be explicitely set.
+
+      A ``defconfig`` file compatible with ``allnoconfig`` mode can be
+      generated by copying the ``.config`` file from a working Linux kernel
+      build, renaming it to ``defconfig`` and placing it into the Linux
+      kernel ``${WORKDIR}`` through your meta-layer. ``KCONFIG_MODE`` does
+      not need to be explicitely set.
+
+      A ``defconfig`` file compatible with ``alldefconfig`` mode can be
+      generated using the
+      :ref:`ref-tasks-savedefconfig`
+      task and placed into the Linux kernel ``${WORKDIR}`` through your
+      meta-layer. Explicitely set ``KCONFIG_MODE``::
+
+         KCONFIG_MODE = "alldefconfig"
+
+
    :term:`KERNEL_ALT_IMAGETYPE`
       Specifies an alternate kernel image type for creation in addition to
       the kernel image type specified using the
-- 
2.25.1

Re: [PATCH v2] kernel-dev: document KCONFIG_MODE

[Quentin Schulz]

Hi Daniel,

Many thanks for the v2!

On Wed, May 05, 2021 at 10:57:50AM +0200, Daniel Wagenknecht wrote:
> Signed-off-by: Daniel Wagenknecht <dwagenknecht@emlix.com>
> ---
>  documentation/kernel-dev/common.rst    |  9 ++++++
>  documentation/ref-manual/variables.rst | 38 ++++++++++++++++++++++++++
>  2 files changed, 47 insertions(+)
> 
> diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
> index 3f35d8412..5935d6f56 100644
> --- a/documentation/kernel-dev/common.rst
> +++ b/documentation/kernel-dev/common.rst
> @@ -650,6 +650,15 @@ extends the :term:`FILESPATH`
>  variable (search directories) to include the ``${PN}`` directory you
>  created to hold the configuration changes.
>  
> +You can also use a regular ``defconfig`` file, as generated by the
> +:ref:`ref-tasks-savedefconfig`
> +task instead of a complete ``.config`` file. This only specifies the
> +non-default configuration values.  You need to additionally set
> +:term:`KCONFIG_MODE`
> +in the linux-yocto ``.bbappend`` file in your layer::
> +
> +   KCONFIG_MODE = "alldefconfig"
> +
>  .. note::
>  
>     The build system applies the configurations from the ``defconfig``
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index c339d45e1..a2db34520 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3745,6 +3745,44 @@ 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:`KCONFIG_MODE`
> +      When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
> +      class, specifies the kernel configuration values to use for options
> +      not specified in the provided ``defconfig`` file. Valid options are::
> +
> +         KCONFIG_MODE = "alldefconfig"
> +         KCONFIG_MODE = "allnoconfig"
> +
> +      In ``alldefconfig`` mode the options not explicitely specified will be
> +      assigned their Kconfig default value. In ``allnoconfig`` mode the
> +      options not explicitely specified will be disabled in the kernel
> +      config.
> +
> +      In case ``KCONFIG_MODE`` is unset the behaviour will depend on where
> +      the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file
> +      will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed
> +      in ``${WORKDIR}`` through a meta-layer will be handled in
> +      ``allnoconfig`` mode.
> +
> +      An "in-tree" ``defconfig`` file can be selected via the
> +      :term:`KBUILD_DEFCONFIG` variable. ``KCONFIG_MODE`` does not need to
> +      be explicitely set.
> +
> +      A ``defconfig`` file compatible with ``allnoconfig`` mode can be
> +      generated by copying the ``.config`` file from a working Linux kernel
> +      build, renaming it to ``defconfig`` and placing it into the Linux
> +      kernel ``${WORKDIR}`` through your meta-layer. ``KCONFIG_MODE`` does
> +      not need to be explicitely set.

s/explicitely/explicitly/

> +
> +      A ``defconfig`` file compatible with ``alldefconfig`` mode can be
> +      generated using the
> +      :ref:`ref-tasks-savedefconfig`
> +      task and placed into the Linux kernel ``${WORKDIR}`` through your
> +      meta-layer. Explicitely set ``KCONFIG_MODE``::
> +

s/Explicitely/Explicitly/

Otherwise:
Reviewed-by: Quentin Schulz <foss@0leil.net>

Thanks!
Quentin

Re: [docs] [PATCH v2] kernel-dev: document KCONFIG_MODE

[Michael Opdenacker]

Hi Daniel,

Many thanks for the new version.

On 5/5/21 10:57 AM, Daniel Wagenknecht wrote:
> +
> +      In case ``KCONFIG_MODE`` is unset the behaviour will depend on where

From an English perspective, I believe that "unset" means "not set", but
from a UNIX perspective, it makes me think about corresponding shell
command, that unsets an variable that was set previously.

Could we just say "not set" instead of "unset"?

Any thoughts?

Other than that, happy to merge your patch. I can take care of fixing
"explicitely".

Cheers,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH v2] kernel-dev: document KCONFIG_MODE

[Daniel Wagenknecht]

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

Hello Michael, hello Quentin,

> From an English perspective, I believe that "unset" means "not set", but
> from a UNIX perspective, it makes me think about corresponding shell
> command, that unsets an variable that was set previously.
> 
> Could we just say "not set" instead of "unset"?

It reduces ambiguity and I can see no reasons against "not set". Will you do
this little fixup when merging?
Thanks!

Cheers
-- 
Daniel Wagenknecht

emlix GmbH, http://www.emlix.com
Fon +49 551 30664-0, Fax +49 551 30664-11
Gothaer Platz 3, 37083 Göttingen, Germany
Sitz der Gesellschaft: Göttingen, Amtsgericht Göttingen HR B 3160
Geschäftsführung: Heike Jordan, Dr. Uwe Kracke
Ust-IdNr.: DE 205 198 055

emlix - smart embedded open source

On Wed, 2021-05-05 at 11:30 +0200, Michael Opdenacker wrote:
> Hi Daniel,
> 
> Many thanks for the new version.
> 
> On 5/5/21 10:57 AM, Daniel Wagenknecht wrote:
> > +
> > +      In case ``KCONFIG_MODE`` is unset the behaviour will depend on where
> 
> From an English perspective, I believe that "unset" means "not set", but
> from a UNIX perspective, it makes me think about corresponding shell
> command, that unsets an variable that was set previously.
> 
> Could we just say "not set" instead of "unset"?
> 
> Any thoughts?
> 
> Other than that, happy to merge your patch. I can take care of fixing
> "explicitely".
> 
> Cheers,
> 
> Michael.
> 
> 
> 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: [docs] [PATCH v2] kernel-dev: document KCONFIG_MODE

[Michael Opdenacker]

Hi Daniel

On 5/6/21 7:46 AM, Daniel Wagenknecht wrote:
> Hello Michael, hello Quentin,
>
>> From an English perspective, I believe that "unset" means "not set", but
>> from a UNIX perspective, it makes me think about corresponding shell
>> command, that unsets an variable that was set previously.
>>
>> Could we just say "not set" instead of "unset"?
> It reduces ambiguity and I can see no reasons against "not set". Will you do
> this little fixup when merging?


Yes, done!
Merged in the "master-next" branch of yocto-docs.

Thanks again,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com