[PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Christos Gavros]

This variable specifies the maximum allowed size
of the initramfs image in bytes.
Fixes [YOCTO #15797]

CC: Yoann Congal <yoann.congal@smile.fr>
CC: Randy MacLeod <randy.macleod@windriver.com>
CC: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Christos Gavros <gavrosc@yahoo.com>
---
 documentation/ref-manual/variables.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 62e339ed8..c9c042096 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4474,6 +4474,13 @@ system and gives an overview of their function and contents.
       See the :term:`MACHINE` variable for additional
       information.
 
+   :term:`INITRAMFS_MAXSIZE`
+      Specifies the maximum allowed size of the initramfs image in bytes.
+      The build will fail in case the initramfs image size is bigger than
+      the value of this variable.
+      There is a week default value assignment (INITRAMFS_MAXSIZE ??= "131072" ) 
+      in bitbake.conf.
+
    :term:`INITRAMFS_MULTICONFIG`
       Defines the multiconfig to create a multiconfig dependency to be used by
       the :ref:`ref-classes-kernel` class.
-- 
2.34.1

Re: [docs] [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Quentin Schulz]

Hi Christos,

Thanks for the patch!

On 3/28/25 9:52 PM, Christos Gavros via lists.yoctoproject.org wrote:
> This variable specifies the maximum allowed size
> of the initramfs image in bytes.
> Fixes [YOCTO #15797]
> 
> CC: Yoann Congal <yoann.congal@smile.fr>
> CC: Randy MacLeod <randy.macleod@windriver.com>
> CC: Antonin Godard <antonin.godard@bootlin.com>
> Signed-off-by: Christos Gavros <gavrosc@yahoo.com>
> ---
>   documentation/ref-manual/variables.rst | 7 +++++++
>   1 file changed, 7 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 62e339ed8..c9c042096 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4474,6 +4474,13 @@ system and gives an overview of their function and contents.
>         See the :term:`MACHINE` variable for additional
>         information.
>   
> +   :term:`INITRAMFS_MAXSIZE`
> +      Specifies the maximum allowed size of the initramfs image in bytes.

Is it really in bytes? The error message specifies "(K)" which I assume 
means those are Kilobytes?

> +      The build will fail in case the initramfs image size is bigger than
> +      the value of this variable.
> +      There is a week default value assignment (INITRAMFS_MAXSIZE ??= "131072" )

s/week/weak/

> +      in bitbake.conf.
> +

I would suggest to reword like this:

"""
The default value is set as follows in the BitBake configuration file::

    INITRAMFS_MAXSIZE ??= "131072"

"""

to follow the same convention we used for other variables' default value.

It's not entirely clear on what this limit applies when compression is 
enabled, on the uncompressed content or compressed? This needs to be 
made explicit.

Cheers,
Quentin

Re: [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Christos Gavros]

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

hi Quentin,

thank you for your comments. i will prepare a v2.
I dont have the answer about the 'compression' question you set. i would have to look at that.

Br
Christos

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

Re: [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Christos Gavros]

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

hi Quentin,

when you write "compression is enabled", do you mean that the variable "INITRAMFS_FSTYPES" is set to one of the compression formats (by default is set to cpio.gz)?
If so , then i think that "INITRAMFS_MAXSIZE" applies the compressed image.

Br
Christos

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

Re: [docs] [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Quentin Schulz]

Hi Christos,

On 4/1/25 9:43 PM, Christos Gavros via lists.yoctoproject.org wrote:
> hi Quentin,
> 
> when you write "compression is enabled", do you mean that the variable "INITRAMFS_FSTYPES" is set to one of the compression formats (by default is set to cpio.gz)?

I mean if the compressed (so not .cpio) size is used or uncompressed 
(.cpio).

You may want max size for the compressed size as this is likely the 
space it's going to take on the storage medium. You probably are more 
interested in the uncompressed size (even for a compressed image!) 
because that's the space it's going to take in RAM at runtime.

If I'm not mistaken, even if the initramfs is compressed on the storage 
medium, the kernel will uncompress it in RAM before using it.

> If so , then i think that "INITRAMFS_MAXSIZE" applies the compressed image.
> 

Reading the introducing commit 155ba626b46bf71acde6c24402fce1682da53b90 
in OE-Core, it seems like this was done for limiting the size in RAM.

Reading the code (meta/classes-recipe/image.bbclass:get_rootfs_size()), 
it's the size of the IMAGE_ROOTFS directory accounting for an overhead 
factor (IMAGE_OVERHEAD_FACTOR) and alignment (IMAGE_ROOTFS_ALIGNMENT). 
IMAGE_OVERHEAD_FACTOR variable is explained in code 
(meta/conf/bitbake.conf) as some free space for "stuff" to happen at 
boot. I am not entirely sure this is necessary for the initramfs (but it 
for sure is for rootfs stored on a storage medium). Then this computed 
size is compared to the value of INITRAMFS_MAXSIZE. So then it means 
this is the uncompressed size we're checking.

What I don't understand is the

"""
# Check the initramfs size against INITRAMFS_MAXSIZE (if set)
if image_fstypes == initramfs_fstypes != ''  and initramfs_maxsize:
"""

check... Why do we care that IMAGE_FSTYPES is equal to INITRAMFS_FSTYPES 
in order to check for the initramfs size? What happens when you have 
setups with an initramfs AND a rootfs on another medium (e.g. typical 
setup for PC distros, or when secureboot is involved (initramfs checking 
the rootfs + switch_root))?

Cheers,
Quentin

Re: [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Antonin Godard]

Hi Christos,

On Fri Mar 28, 2025 at 9:52 PM CET, Christos Gavros wrote:
> This variable specifies the maximum allowed size
> of the initramfs image in bytes.
> Fixes [YOCTO #15797]
>
> CC: Yoann Congal <yoann.congal@smile.fr>
> CC: Randy MacLeod <randy.macleod@windriver.com>
> CC: Antonin Godard <antonin.godard@bootlin.com>
> Signed-off-by: Christos Gavros <gavrosc@yahoo.com>
> ---
>  documentation/ref-manual/variables.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 62e339ed8..c9c042096 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4474,6 +4474,13 @@ system and gives an overview of their function and contents.
>        See the :term:`MACHINE` variable for additional
>        information.
>  
> +   :term:`INITRAMFS_MAXSIZE`
> +      Specifies the maximum allowed size of the initramfs image in bytes.
> +      The build will fail in case the initramfs image size is bigger than
> +      the value of this variable.
> +      There is a week default value assignment (INITRAMFS_MAXSIZE ??= "131072" )

Not sure this was covered by Quentin but either the default value here needs to
be enclosed with ticks: (``INITRAMFS_MAXSIZE ??= "131072" ``).

Or better I think, we should specify where it is defined without specifying the
default value, which may evolve over time.
Like so: :oe_git:`meta/conf/bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>`

> +      in bitbake.conf.
> +
>     :term:`INITRAMFS_MULTICONFIG`
>        Defines the multiconfig to create a multiconfig dependency to be used by
>        the :ref:`ref-classes-kernel` class.

Looking at the code of image.bbclass, we have:

  size_kb = oe.utils.directory_size(d.getVar("IMAGE_ROOTFS")) / 1024

So, it seems that the size is calculated regardless of any compression parameter
since it calculates the size of the directory?

Otherwise, there are more considerations to take into account. We have the
overhead_factor and rootfs_alignment.

Actually, INITRAMFS_MAXSIZE is going though the same operations as
IMAGE_ROOTFS_MAXSIZE, from what I read from the code.

It would be nice to include how IMAGE_OVERHEAD_FACTOR and IMAGE_ROOTFS_ALIGNMENT
affect this variable too. This is missing in the IMAGE_ROOTFS_MAXSIZE
documentation as well. :/

Antonin

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

Re: [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Christos Gavros]

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

hi

thank you for your comments! I would need to investigate more!!

Br
Christos

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

Re: [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Christos Gavros]

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

hi Antonin and Quentin

i had a further look on that.

When initramfs is included in build (INITRAMFS_IMAGE = "core-image-minimal-initramfs" in local.conf)
then the 'IMAGE_ROOTFS' is pointing to build/tmp/work/qemux86_64-poky-linux/core-image-minimal-initramfs/1.0/rootfs.
This directory is approximately 115000kb.
If INITRAMFS_MAXSIZE = "1100000" then the error is generated.
If INITRAMFS_MAXSIZE = "1600000" then the build is ok.
So i think that the INITRAMFS_MAXSIZE refers to the size of the directory and not the final image type.

The condition " if image_fstypes == initramfs_fstypes != ''  and initramfs_maxsize: ", exists
because in the recipe "core-image-minimal-initramfs" there is the assignment IMAGE_FSTYPES = "${INITRAMFS_FSTYPES}".
So the INITRAMFS_MAXSIZE is evaluated only when one of the initramfs recipes is included.

Shall i submit a v2 ?

Br
Christos

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

Re: [docs] [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Antonin Godard]

Hi Christos,

On Wed Apr 23, 2025 at 9:24 PM CEST, Christos Gavros via lists.yoctoproject.org wrote:
> hi Antonin and Quentin
>
> i had a further look on that.
>
> When initramfs is included in build (INITRAMFS_IMAGE = "core-image-minimal-initramfs" in local.conf)
> then the 'IMAGE_ROOTFS' is pointing to build/tmp/work/qemux86_64-poky-linux/core-image-minimal-initramfs/1.0/rootfs.
> This directory is approximately 115000kb.
> If INITRAMFS_MAXSIZE = "1100000" then the error is generated.
> If INITRAMFS_MAXSIZE = "1600000" then the build is ok.
> So i think that the INITRAMFS_MAXSIZE refers to the size of the directory and not the final image type.

How were your IMAGE_OVERHEAD_FACTOR and IMAGE_ROOTFS_ALIGNMENT variables set
during your test? I'm pretty sure they affect the final condition when I looked
at the code a couple of weeks ago.

Could you include how these two variables affect the final condition with
regards to INITRAMFS_MAXSIZE?

> The condition " if image_fstypes == initramfs_fstypes != ''  and initramfs_maxsize: ", exists
> because in the recipe "core-image-minimal-initramfs" there is the assignment IMAGE_FSTYPES = "${INITRAMFS_FSTYPES}".
> So the INITRAMFS_MAXSIZE is evaluated only when one of the initramfs recipes is included.
>
> Shall i submit a v2 ?

I think Quentin had valid comments on your patch:
week -> weak
the size is in kilobytes, not bytes

I'll let you take a second look at their comments.

Thanks,
Antonin

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

Re: [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Christos Gavros]

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

hi Antonin

my plan was to include text for all the comments from you and Quentin.
I didnt mention the others because are small changes.

Regarding the 2 variables. The values are:
IMAGE_OVERHEAD_FACTOR = 1.3
IMAGE_ROOTFS_ALIGNMENT = 1
size (initial size of IMAGE_ROOTFS) = 120840kb
size (after applying IMAGE_OVERHEAD_FACTOR ) = 157092kb
size (after applying IMAGE_ROOTFS_ALIGNMENT ) = 157092kb

There are more variables involved in the final calculation like 'IMAGE_ROOTFS_SIZE', 'IMAGE_ROOTFS_EXTRA_SPACE' (calc of base_size2).

My suggestion related to variables is to add a sentence like " The variables IMAGE_OVERHEAD_FACTOR, IMAGE_ROOTFS_ALIGNMENT , IMAGE_ROOTFS_SIZE, IMAGE_ROOTFS_EXTRA_SPACE
are applied in the final calculation of initramfs size."

Br
Christos

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

Re: [docs] [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Antonin Godard]

Hi Christos,

On Thu Apr 24, 2025 at 5:18 PM CEST, Christos Gavros via lists.yoctoproject.org wrote:
> hi Antonin
>
> my plan was to include text for all the comments from you and Quentin.
> I didnt mention the others because are small changes.
>
> Regarding the 2 variables. The values are:
> IMAGE_OVERHEAD_FACTOR = 1.3
> IMAGE_ROOTFS_ALIGNMENT = 1
> size (initial size of IMAGE_ROOTFS) = 120840kb
> size (after applying IMAGE_OVERHEAD_FACTOR ) = 157092kb
> size (after applying IMAGE_ROOTFS_ALIGNMENT ) = 157092kb
>
> There are more variables involved in the final calculation like 'IMAGE_ROOTFS_SIZE', 'IMAGE_ROOTFS_EXTRA_SPACE' (calc of base_size2).
>
> My suggestion related to variables is to add a sentence like " The variables IMAGE_OVERHEAD_FACTOR, IMAGE_ROOTFS_ALIGNMENT , IMAGE_ROOTFS_SIZE, IMAGE_ROOTFS_EXTRA_SPACE
> are applied in the final calculation of initramfs size."

Right, so it would be great if your v2 includes these details. I would even go
further and detail every calculation steps, before `base_size` is compared
against INITRAMFS_MAXSIZE.

I am talking about this part of the code:

    size_kb = oe.utils.directory_size(d.getVar("IMAGE_ROOTFS")) / 1024

    base_size = size_kb * overhead_factor
    bb.debug(1, '%f = %d * %f' % (base_size, size_kb, overhead_factor))
    base_size2 = max(base_size, rootfs_req_size) + rootfs_extra_space
    bb.debug(1, '%f = max(%f, %d)[%f] + %d' % (base_size2, base_size, rootfs_req_size, max(base_size, rootfs_req_size), rootfs_extra_space))

    base_size = base_size2
    if base_size != int(base_size):
        base_size = int(base_size + 1)
    else:
        base_size = int(base_size)
    bb.debug(1, '%f = int(%f)' % (base_size, base_size2))

    base_size_saved = base_size
    base_size += rootfs_alignment - 1
    base_size -= base_size % rootfs_alignment
    bb.debug(1, '%d = aligned(%d)' % (base_size, base_size_saved))

That way, a user knows exactly what to expect when they fill in the
INITRAMFS_MAXSIZE variable for their need.

And as you can see, IMAGE_ROOTFS_MAXSIZE and INITRAMFS_MAXSIZE follow the same
rules:

        if base_size > rootfs_maxsize_int:
            bb.fatal("The rootfs size %d(K) exceeds IMAGE_ROOTFS_MAXSIZE: %d(K)" % \
                (base_size, rootfs_maxsize_int))

and

        if base_size > initramfs_maxsize_int:
            bb.error("The initramfs size %d(K) exceeds INITRAMFS_MAXSIZE: %d(K)" % \
                (base_size, initramfs_maxsize_int))

So that means that your patch could also be applied to the definition of
IMAGE_ROOTFS_MAXSIZE, which currently lacks any of these details.

Thanks!
Antonin

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

Re: [PATCH] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Christos Gavros]

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

hi Antonin,

thank you!

I will prepare a v2 and include detail description of calculation steps.

Br
Christos

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