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

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(+)

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

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

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

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

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

hi

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

Br
Christos