[PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Dixit Parmar]

This variable controls the kernel module spliting.

Signed-off-by: Dixit Parmar <dixitparmar19@gmail.com>
---
 documentation/ref-manual/variables.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 9768d8f5b..b7dde2604 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5359,6 +5359,20 @@ system and gives an overview of their function and contents.
       the :term:`KERNEL_PATH` variable. Both variables are common variables
       used by external Makefiles to point to the kernel source directory.
 
+   :term:`KERNEL_SPLIT_MODULES`
+      When inheriting the :ref:`ref-classes-kernel-module-split` class, this
+      variable controls whether kernel modules are split into separate packages
+      or bundled into a single package.
+
+      For some use cases, a monolithic kernel module package
+      :ref:`KERNEL_PACKAGE_NAME` (by default named ``kernel``) that contains
+      all modules built from the kernel sources may be preferred. Because a
+      monolithic package can reduce download time and speed up installation.
+
+      By default, this variable is set to ``1``, resulting in one package per
+      module. Setting it to any other value will generate a single monolithic
+      package containing all kernel modules.
+
    :term:`KERNEL_SRC`
       The location of the kernel sources. This variable is set to the value
       of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`
-- 
2.43.0

Re: [docs] [PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Antonin Godard]

On Sun Jun 8, 2025 at 12:44 PM CEST, Dixit Parmar via lists.yoctoproject.org wrote:
> This variable controls the kernel module spliting.
>
> Signed-off-by: Dixit Parmar <dixitparmar19@gmail.com>
> ---
>  documentation/ref-manual/variables.rst | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 9768d8f5b..b7dde2604 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -5359,6 +5359,20 @@ system and gives an overview of their function and contents.
>        the :term:`KERNEL_PATH` variable. Both variables are common variables
>        used by external Makefiles to point to the kernel source directory.
>  
> +   :term:`KERNEL_SPLIT_MODULES`
> +      When inheriting the :ref:`ref-classes-kernel-module-split` class, this
> +      variable controls whether kernel modules are split into separate packages
> +      or bundled into a single package.
> +
> +      For some use cases, a monolithic kernel module package
> +      :ref:`KERNEL_PACKAGE_NAME` (by default named ``kernel``) that contains

This should be :term:`KERNEL_PACKAGE_NAME` (not :ref:). Otherwise fails to
build.

> +      all modules built from the kernel sources may be preferred. Because a
> +      monolithic package can reduce download time and speed up installation.

I think this can be simplified by "...may be preferred to speed up
installation". "Download time" is too context specific, probably related to
package management on the target.

> +
> +      By default, this variable is set to ``1``, resulting in one package per
> +      module. Setting it to any other value will generate a single monolithic
> +      package containing all kernel modules.
> +
>     :term:`KERNEL_SRC`
>        The location of the kernel sources. This variable is set to the value
>        of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`

Thanks,
Antonin

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

Re: [docs] [PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Antonin Godard]

On Tue Jun 10, 2025 at 10:55 AM CEST, Antonin Godard wrote:
> On Sun Jun 8, 2025 at 12:44 PM CEST, Dixit Parmar via lists.yoctoproject.org wrote:
>> This variable controls the kernel module spliting.
>>
>> Signed-off-by: Dixit Parmar <dixitparmar19@gmail.com>
>> ---
>>  documentation/ref-manual/variables.rst | 14 ++++++++++++++
>>  1 file changed, 14 insertions(+)
>>
>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>> index 9768d8f5b..b7dde2604 100644
>> --- a/documentation/ref-manual/variables.rst
>> +++ b/documentation/ref-manual/variables.rst
>> @@ -5359,6 +5359,20 @@ system and gives an overview of their function and contents.
>>        the :term:`KERNEL_PATH` variable. Both variables are common variables
>>        used by external Makefiles to point to the kernel source directory.
>>  
>> +   :term:`KERNEL_SPLIT_MODULES`
>> +      When inheriting the :ref:`ref-classes-kernel-module-split` class, this
>> +      variable controls whether kernel modules are split into separate packages
>> +      or bundled into a single package.
>> +
>> +      For some use cases, a monolithic kernel module package
>> +      :ref:`KERNEL_PACKAGE_NAME` (by default named ``kernel``) that contains
>
> This should be :term:`KERNEL_PACKAGE_NAME` (not :ref:). Otherwise fails to
> build.
>
>> +      all modules built from the kernel sources may be preferred. Because a
>> +      monolithic package can reduce download time and speed up installation.
>
> I think this can be simplified by "...may be preferred to speed up
> installation". "Download time" is too context specific, probably related to
> package management on the target.
>
>> +
>> +      By default, this variable is set to ``1``, resulting in one package per
>> +      module. Setting it to any other value will generate a single monolithic
>> +      package containing all kernel modules.
>> +
>>     :term:`KERNEL_SRC`
>>        The location of the kernel sources. This variable is set to the value
>>        of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`

Not sure about the "kernel" package name. After building with
KERNEL_SPLIT_MODULES to 0:

$ bitbake-getvar KERNEL_PACKAGE_NAME -r virtual/kernel
#
# $KERNEL_PACKAGE_NAME [2 operations]
#   set /build/../work/openembedded-core/meta/conf/documentation.conf:253
#     [doc] "Name prefix for kernel packages. Defaults to 'kernel'."
#   set /build/../work/openembedded-core/meta/classes-recipe/kernel.bbclass:11
#     [_defaultval] "kernel"
# pre-expansion value:
#   "kernel"
KERNEL_PACKAGE_NAME="kernel"

$ oe-pkgdata-util list-pkgs | grep kernel
kernel
kernel-base
kernel-dbg
kernel-dev
kernel-image
kernel-image-image
kernel-modules
kernel-vmlinux

$ oe-pkgdata-util list-pkg-files kernel-modules | head -7
kernel-modules:
        /lib/modules/6.12.30-yocto-standard/kernel/crypto/af_alg.ko
        /lib/modules/6.12.30-yocto-standard/kernel/crypto/algif_aead.ko
        /lib/modules/6.12.30-yocto-standard/kernel/crypto/algif_hash.ko
        /lib/modules/6.12.30-yocto-standard/kernel/crypto/algif_rng.ko
        /lib/modules/6.12.30-yocto-standard/kernel/crypto/algif_skcipher.ko
        /lib/modules/6.12.30-yocto-standard/kernel/crypto/blowfish_common.ko
        ...

So it seems to me that the name of the package is "kernel-modules", not
"kernel"?

Another side question: in my experience I never had to set KERNEL_SPLIT_MODULES
to be able to install *all* kernel modules. Whatever the value of
KERNEL_SPLIT_MODULES, installing the package "kernel-modules" would just install
the modules. So what is the difference after setting this variable?

Antonin

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

Re: [PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Dixit Parmar]

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

Will fix the ref->term typo and the take your suggestion on rewording.

There seem to be confusion related to the kernel package name, however I feel it was additional information. I shall remove the mention of the kernel package name (keep the variable reference only) for simplicity in next version.

Another side question: in my experience I never had to set KERNEL_SPLIT_MODULES
to be able to install *all* kernel modules. Whatever the value of
KERNEL_SPLIT_MODULES, installing the package "kernel-modules" would just install
the modules. So what is the difference after setting this variable?

Yes, you would be able to install "all" the kernel-modules without bothering about KERNEL_SPLIT_MODULES. The issue is having autoload .conf file being installed or not when KERNEL_MODULE_AUTOLOAD is having your modules listed to be autoloader. When KERNEL_SPLIT_MODULES = 0 the .conf files for driver autoload and probeconf is not getting generated.

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

Re: [docs] [PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Antonin Godard]

On Wed Jun 18, 2025 at 2:14 PM CEST, Dixit Parmar via lists.yoctoproject.org wrote:
> Will fix the ref->term typo and the take your suggestion on rewording.
>
> There seem to be confusion related to the kernel package name, however I feel
> it was additional information. I shall remove the mention of the kernel
> package name (keep the variable reference only) for simplicity in next
> version.

Looking forward to it!

> Yes, you would be able to install "all" the kernel-modules without bothering
> about KERNEL_SPLIT_MODULES. The issue is having autoload .conf file being
> installed or not when KERNEL_MODULE_AUTOLOAD is having your modules listed to
> be autoloader. When KERNEL_SPLIT_MODULES = 0 the .conf files for driver
> autoload and probeconf is not getting generated.

This sounds like a bug to me, no? Why would someone expect setting
KERNEL_SPLIT_MODULES to 0 have the autoload files missing?

I ran a some tests. So when I set KERNEL_SPLIT_MODULES to 1, and
KERNEL_MODULE_AUTOLOAD to "xt_limit", a kernel-module-xt-limit.ipk package is
generated like so:

├── etc
│   └── modules-load.d
│       └── xt_limit.conf
└── lib
    └── modules
        └── 6.12.30-yocto-standard
            └── kernel
                └── net
                    └── netfilter
                        └── xt_limit.ko

When KERNEL_SPLIT_MODULES is set to 0, only one kernel-modules.ipk package is
generated, and does _not_ contain xt_limit.conf, but only xt_limit.ko. To me
this sounds like a bug, what do you think?

I would _not_ describe that behavior in the documentation for the
KERNEL_SPLIT_MODULES variables.

The fact that "kernel-modules" is still available when KERNEL_SPLIT_MODULES = 1
is simply because a "fake" kernel-modules.ipk package is generated, and depends
on the other kernel-module-* packages - so you can ignore my remark in my
previous message.

Thanks,
Antonin

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

Re: [PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Dixit Parmar]

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

On Wed, Jun 18, 2025 at 06:30 PM, Antonin Godard wrote:

> 
> On Wed Jun 18, 2025 at 2:14 PM CEST, Dixit Parmar via
> lists.yoctoproject.org wrote:
> 
>> Will fix the ref->term typo and the take your suggestion on rewording.
>> 
>> There seem to be confusion related to the kernel package name, however I
>> feel
>> it was additional information. I shall remove the mention of the kernel
>> package name (keep the variable reference only) for simplicity in next
>> version.
> 
> Looking forward to it!
> 
> 
>> Yes, you would be able to install "all" the kernel-modules without
>> bothering
>> about KERNEL_SPLIT_MODULES. The issue is having autoload .conf file being
>> installed or not when KERNEL_MODULE_AUTOLOAD is having your modules listed
>> to
>> be autoloader. When KERNEL_SPLIT_MODULES = 0 the .conf files for driver
>> autoload and probeconf is not getting generated.
> 
> This sounds like a bug to me, no? Why would someone expect setting
> KERNEL_SPLIT_MODULES to 0 have the autoload files missing?
> 
> I ran a some tests. So when I set KERNEL_SPLIT_MODULES to 1, and
> KERNEL_MODULE_AUTOLOAD to "xt_limit", a kernel-module-xt-limit.ipk package
> is
> generated like so:
> 
> ├── etc
> │   └── modules-load.d
> │   └── xt_limit.conf
> └── lib
> └── modules
> └── 6.12.30-yocto-standard
> └── kernel
> └── net
> └── netfilter
> └── xt_limit.ko
> 
> When KERNEL_SPLIT_MODULES is set to 0, only one kernel-modules.ipk package
> is
> generated, and does _not_ contain xt_limit.conf, but only xt_limit.ko. To
> me
> this sounds like a bug, what do you think?

Exactly, that's the issue reported https://bugzilla.yoctoproject.org/show_bug.cgi?id=15145 ( https://bugzilla.yoctoproject.org/show_bug.cgi?id=15145 ) and I am fixing it here with this solution https://lists.openembedded.org/g/openembedded-core/message/218290.

> 
> I would _not_ describe that behavior in the documentation for the
> KERNEL_SPLIT_MODULES variables.

True, that's why the documentation does not mention anything about the conf files.

> 
> The fact that "kernel-modules" is still available when
> KERNEL_SPLIT_MODULES = 1
> is simply because a "fake" kernel-modules.ipk package is generated, and
> depends
> on the other kernel-module-* packages - so you can ignore my remark in my
> previous message.

Which remark exactly??

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

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

Re: [docs] [PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Antonin Godard]

On Wed Jun 18, 2025 at 3:19 PM CEST, Dixit Parmar via lists.yoctoproject.org wrote:
> On Wed, Jun 18, 2025 at 06:30 PM, Antonin Godard wrote:
>
>> 
>> On Wed Jun 18, 2025 at 2:14 PM CEST, Dixit Parmar via
>> lists.yoctoproject.org wrote:
>> 
>>> Will fix the ref->term typo and the take your suggestion on rewording.
>>> 
>>> There seem to be confusion related to the kernel package name, however I
>>> feel
>>> it was additional information. I shall remove the mention of the kernel
>>> package name (keep the variable reference only) for simplicity in next
>>> version.
>> 
>> Looking forward to it!
>> 
>> 
>>> Yes, you would be able to install "all" the kernel-modules without
>>> bothering
>>> about KERNEL_SPLIT_MODULES. The issue is having autoload .conf file being
>>> installed or not when KERNEL_MODULE_AUTOLOAD is having your modules listed
>>> to
>>> be autoloader. When KERNEL_SPLIT_MODULES = 0 the .conf files for driver
>>> autoload and probeconf is not getting generated.
>> 
>> This sounds like a bug to me, no? Why would someone expect setting
>> KERNEL_SPLIT_MODULES to 0 have the autoload files missing?
>> 
>> I ran a some tests. So when I set KERNEL_SPLIT_MODULES to 1, and
>> KERNEL_MODULE_AUTOLOAD to "xt_limit", a kernel-module-xt-limit.ipk package
>> is
>> generated like so:
>> 
>> ├── etc
>> │   └── modules-load.d
>> │   └── xt_limit.conf
>> └── lib
>> └── modules
>> └── 6.12.30-yocto-standard
>> └── kernel
>> └── net
>> └── netfilter
>> └── xt_limit.ko
>> 
>> When KERNEL_SPLIT_MODULES is set to 0, only one kernel-modules.ipk package
>> is
>> generated, and does _not_ contain xt_limit.conf, but only xt_limit.ko. To
>> me
>> this sounds like a bug, what do you think?
>
> Exactly, that's the issue reported https://bugzilla.yoctoproject.org/show_bug.cgi?id=15145 ( https://bugzilla.yoctoproject.org/show_bug.cgi?id=15145 ) and I am fixing it here with this solution https://lists.openembedded.org/g/openembedded-core/message/218290.
>
>> 
>> I would _not_ describe that behavior in the documentation for the
>> KERNEL_SPLIT_MODULES variables.
>
> True, that's why the documentation does not mention anything about the conf files.
>
>> 
>> The fact that "kernel-modules" is still available when
>> KERNEL_SPLIT_MODULES = 1
>> is simply because a "fake" kernel-modules.ipk package is generated, and
>> depends
>> on the other kernel-module-* packages - so you can ignore my remark in my
>> previous message.
>
> Which remark exactly??

About the possibility to install "kernel-modules" both when KERNEL_SPLIT_MODULES
is 0 or 1. I guess it doesn't hurt to add a note about that at the end of the
definition:

"""
.. note::

   If :term:`KERNEL_SPLIT_MODULES` is set to 0, it is still possible to install
   all kernel modules at once by adding ``kernel-modules`` to
   :term:`IMAGE_INSTALL`. The way it works is that a placeholder
   "kernel-modules" package will be created and will depend on every other
   individual kernel module packages.
"""

So there's no confusion. What do you think?

Antonin

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

Re: [PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Dixit Parmar]

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

On Wed, Jun 18, 2025 at 07:12 PM, Antonin Godard wrote:

> 
> On Wed Jun 18, 2025 at 3:19 PM CEST, Dixit Parmar via
> lists.yoctoproject.org wrote:
> 
>> On Wed, Jun 18, 2025 at 06:30 PM, Antonin Godard wrote:
>> 
>> 
>>> On Wed Jun 18, 2025 at 2:14 PM CEST, Dixit Parmar via
>>> lists.yoctoproject.org wrote:
>>> 
>>> 
>>>> Will fix the ref->term typo and the take your suggestion on rewording.
>>>> 
>>>> There seem to be confusion related to the kernel package name, however I
>>>> feel
>>>> it was additional information. I shall remove the mention of the kernel
>>>> package name (keep the variable reference only) for simplicity in next
>>>> version.
>>> 
>>> Looking forward to it!
>>> 
>>> 
>>> 
>>>> Yes, you would be able to install "all" the kernel-modules without
>>>> bothering
>>>> about KERNEL_SPLIT_MODULES. The issue is having autoload .conf file being
>>>> installed or not when KERNEL_MODULE_AUTOLOAD is having your modules listed
>>>> 
>>>> to
>>>> be autoloader. When KERNEL_SPLIT_MODULES = 0 the .conf files for driver
>>>> autoload and probeconf is not getting generated.
>>> 
>>> This sounds like a bug to me, no? Why would someone expect setting
>>> KERNEL_SPLIT_MODULES to 0 have the autoload files missing?
>>> 
>>> I ran a some tests. So when I set KERNEL_SPLIT_MODULES to 1, and
>>> KERNEL_MODULE_AUTOLOAD to "xt_limit", a kernel-module-xt-limit.ipk package
>>> 
>>> is
>>> generated like so:
>>> 
>>> ├── etc
>>> │   └── modules-load.d
>>> │   └── xt_limit.conf
>>> └── lib
>>> └── modules
>>> └── 6.12.30-yocto-standard
>>> └── kernel
>>> └── net
>>> └── netfilter
>>> └── xt_limit.ko
>>> 
>>> When KERNEL_SPLIT_MODULES is set to 0, only one kernel-modules.ipk package
>>> 
>>> is
>>> generated, and does _not_ contain xt_limit.conf, but only xt_limit.ko. To
>>> me
>>> this sounds like a bug, what do you think?
>> 
>> Exactly, that's the issue reported https://bugzilla.yoctoproject.org/show_bug.cgi?id=15145
>> ( https://bugzilla.yoctoproject.org/show_bug.cgi?id=15145 ) and I am fixing
>> it here with this solution https://lists.openembedded.org/g/openembedded-core/message/218290
>> .
>> 
>> 
>>> I would _not_ describe that behavior in the documentation for the
>>> KERNEL_SPLIT_MODULES variables.
>> 
>> True, that's why the documentation does not mention anything about the
>> conf files.
>> 
>> 
>>> The fact that "kernel-modules" is still available when
>>> KERNEL_SPLIT_MODULES = 1
>>> is simply because a "fake" kernel-modules.ipk package is generated, and
>>> depends
>>> on the other kernel-module-* packages - so you can ignore my remark in my
>>> previous message.
>> 
>> Which remark exactly??
> 
> About the possibility to install "kernel-modules" both when
> KERNEL_SPLIT_MODULES
> is 0 or 1. I guess it doesn't hurt to add a note about that at the end of
> the
> definition:
> 
> """
> .. note::
> 
> If :term:`KERNEL_SPLIT_MODULES` is set to 0, it is still possible to
> install
> all kernel modules at once by adding ``kernel-modules`` to
> :term:`IMAGE_INSTALL`. The way it works is that a placeholder
> "kernel-modules" package will be created and will depend on every other
> individual kernel module packages.
> """
> 
> So there's no confusion. What do you think?

That sounds good to me. I will append this note. Thanks for suggestion.

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

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

Re: [PATCH v2] ref-manual: document KERNEL_SPLIT_MODULES variable

[Antonin Godard]

On Sun, 08 Jun 2025 16:14:54 +0530, Dixit Parmar wrote:
> This variable controls the kernel module spliting.
> 
> 

Applied, thanks!

[1/1] ref-manual: document KERNEL_SPLIT_MODULES variable
      commit: 198179d9c6231b5934d4fb6ede716d1dcb1442bb

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>