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

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

[Christos Gavros]

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

CC: Yoann Congal <yoann.congal@smile.fr>
CC: Randy MacLeod <randy.macleod@windriver.com>
CC: Antonin Godard <antonin.godard@bootlin.com>
CC: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Christos Gavros <gavrosc@yahoo.com>
---
v1->v2
* any reference to bytes changed to kilobytes
* description regarding default value is changed
* add text to clarify that limit applies to the directory
* add text to describe the calculation steps for directory size
* add text to clarify the role of other variables in calculation steps
---
 documentation/ref-manual/variables.rst | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index d17f81036..3ab9d72f3 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4708,6 +4708,27 @@ system and gives an overview of their function and contents.
       See the :term:`MACHINE` variable for additional
       information.
 
+   :term:`INITRAMFS_MAXSIZE`
+      Defines the maximum allowed size of the initramfs image in kilobytes.
+      The build will fail if the initramfs image size is larger than the value of this variable.
+
+      The initramfs image size undergoes several calculation steps before it is compared with ``INITRAMFS_MAXSIZE``.
+      In the first step, the size of the directory pointed to by ``IMAGE_ROOTFS`` is calculated.
+      In the second step, the result from the first step is multiplied by ``IMAGE_OVERHEAD_FACTOR``.
+      In the third step, the result from the second step is compared with ``IMAGE_ROOTFS_SIZE``.
+      The larger value of these is added to ``IMAGE_ROOTFS_EXTRA_SPACE``.
+      In the fourth step, the result from the third step is checked for a decimal part. If it has one,
+      it is rounded up to the next integer. If it does not, it is simply converted into an integer.
+      In the fifth step, the ``IMAGE_ROOTFS_ALIGNMENT`` is added to the result from the fourth step
+      and the value "-1" is subtracted.
+      In the sixth step, the remainder of the division between the result from the fifth step
+      and ``IMAGE_ROOTFS_ALIGNMENT`` is subtracted from the result of the fifth step.
+      In this way, the result from the fourth step is rounded up to the nearest multiple of ``IMAGE_ROOTFS_ALIGNMENT``.
+
+      Thus, ``INITRAMFS_MAXSIZE`` is compared with the result of the above calculations
+      and is independent of the final image type.
+      A default value for ``INITRAMFS_MAXSIZE`` is set in ``meta/conf/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 v2] ref-manual/variables.rst: document the INITRAMFS_MAXSIZE variable

[Mikko Rapeli]

Hi,

On Mon, Apr 28, 2025 at 05:41:03PM +0200, Christos Gavros via lists.yoctoproject.org wrote:
> This variable specifies the maximum allowed size
> of the initramfs image in kilobytes.
> Fixes [YOCTO #15797]
> 
> CC: Yoann Congal <yoann.congal@smile.fr>
> CC: Randy MacLeod <randy.macleod@windriver.com>
> CC: Antonin Godard <antonin.godard@bootlin.com>
> CC: Quentin Schulz <quentin.schulz@cherry.de>
> Signed-off-by: Christos Gavros <gavrosc@yahoo.com>
> ---
> v1->v2
> * any reference to bytes changed to kilobytes
> * description regarding default value is changed
> * add text to clarify that limit applies to the directory
> * add text to describe the calculation steps for directory size
> * add text to clarify the role of other variables in calculation steps
> ---
>  documentation/ref-manual/variables.rst | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index d17f81036..3ab9d72f3 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4708,6 +4708,27 @@ system and gives an overview of their function and contents.
>        See the :term:`MACHINE` variable for additional
>        information.
>  
> +   :term:`INITRAMFS_MAXSIZE`
> +      Defines the maximum allowed size of the initramfs image in kilobytes.
> +      The build will fail if the initramfs image size is larger than the value of this variable.
> +
> +      The initramfs image size undergoes several calculation steps before it is compared with ``INITRAMFS_MAXSIZE``.
> +      In the first step, the size of the directory pointed to by ``IMAGE_ROOTFS`` is calculated.
> +      In the second step, the result from the first step is multiplied by ``IMAGE_OVERHEAD_FACTOR``.
> +      In the third step, the result from the second step is compared with ``IMAGE_ROOTFS_SIZE``.
> +      The larger value of these is added to ``IMAGE_ROOTFS_EXTRA_SPACE``.
> +      In the fourth step, the result from the third step is checked for a decimal part. If it has one,
> +      it is rounded up to the next integer. If it does not, it is simply converted into an integer.
> +      In the fifth step, the ``IMAGE_ROOTFS_ALIGNMENT`` is added to the result from the fourth step
> +      and the value "-1" is subtracted.
> +      In the sixth step, the remainder of the division between the result from the fifth step
> +      and ``IMAGE_ROOTFS_ALIGNMENT`` is subtracted from the result of the fifth step.
> +      In this way, the result from the fourth step is rounded up to the nearest multiple of ``IMAGE_ROOTFS_ALIGNMENT``.
> +
> +      Thus, ``INITRAMFS_MAXSIZE`` is compared with the result of the above calculations
> +      and is independent of the final image type.
> +      A default value for ``INITRAMFS_MAXSIZE`` is set in ``meta/conf/bitbake.conf``.
> +
>     :term:`INITRAMFS_MULTICONFIG`
>        Defines the multiconfig to create a multiconfig dependency to be used by
>        the :ref:`ref-classes-kernel` class.

While these are all true, somewhere could be mentioned that this is the uncompressed
size of all files on the file system. Often initramfs'es are stored on disk and
flash storage as compressed cpio archives, e.g. cpio.gz, which are a lot smaller
than INITRAMFS_MAXSIZE. For example core-image-initramfs-boot on genericarm64
can have file system size reported in
buildhistory/images/genericarm64/glibc/core-image-initramfs-boot/image-info.txt

IMAGESIZE = 47432

47 Mb which is basically from "du -k" output on ext4 file system on build machine
but the cpio.gz file size only 14 Mb.

$ ls -l tmp/deploy/images/genericarm64/core-image-initramfs-boot-genericarm64*cpio.gz -h
-rw-r--r-- 2 mcfrisk mcfrisk 14M Apr 28 13:08 tmp/deploy/images/genericarm64/core-image-initramfs-boot-genericarm64-20250428130023.cpio.gz

The 47 Mb is used on target HW when the image is extracted to RAM but on
disk/flash storage only 14 Mb is used on UEFI system ESP partition or UKI
binary, or if the image is merged into kernel binary.

Depending on details, the size after cpio and compression may be important too,
or the INITRAMFS_MAXSIZE may be less important if there is plenty of storage and RAM
which is then freed when real target rootfs is booted into.

Then initramfs is usually used as read-only so the overhead things are mostly
unused and the image could be squeezed to remove all extra space...

Cheers,

-Mikko

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

[Christos Gavros]

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

hi Mikko,

thank you for the comment.

i thought that this is covered from the sentence *" Thus, ``INITRAMFS_MAXSIZE`` is compared with the result of the above calculations
and is independent of the final image type. "* but apparently it didnt. What do you wish to add more?

Br
Christos

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

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

[Mikko Rapeli]

Hi,

On Tue, Apr 29, 2025 at 06:15:08AM -0700, Christos Gavros via Lists.Yoctoproject.Org wrote:
> hi Mikko
> 
> thank you for the comment.
> 
> I thought this is covered from this sentence " Thus, ``INITRAMFS_MAXSIZE`` is compared with the result of the above calculations and is independent of the final image type. "
> but apparently it didnt! What do you wish to add more?

I don't object to your change or even want to change it.

I just think the overall situation with initrd size limit may not be
well described in documentation. It's more than just INITRAMFS_MAXSIZE
which is now well documented with your change. Thanks!

Cheers,

-Mikko

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

[Antonin Godard]

Hi Christos,

Thanks for working on the second version, it looks good. I've got some comments
below.

On Mon Apr 28, 2025 at 5:41 PM CEST, Christos Gavros via lists.yoctoproject.org wrote:
> This variable specifies the maximum allowed size
> of the initramfs image in kilobytes.
> Fixes [YOCTO #15797]
>
> CC: Yoann Congal <yoann.congal@smile.fr>
> CC: Randy MacLeod <randy.macleod@windriver.com>
> CC: Antonin Godard <antonin.godard@bootlin.com>
> CC: Quentin Schulz <quentin.schulz@cherry.de>
> Signed-off-by: Christos Gavros <gavrosc@yahoo.com>
> ---
> v1->v2
> * any reference to bytes changed to kilobytes
> * description regarding default value is changed
> * add text to clarify that limit applies to the directory
> * add text to describe the calculation steps for directory size
> * add text to clarify the role of other variables in calculation steps
> ---
>  documentation/ref-manual/variables.rst | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index d17f81036..3ab9d72f3 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4708,6 +4708,27 @@ system and gives an overview of their function and contents.
>        See the :term:`MACHINE` variable for additional
>        information.
>  
> +   :term:`INITRAMFS_MAXSIZE`
> +      Defines the maximum allowed size of the initramfs image in kilobytes.
> +      The build will fail if the initramfs image size is larger than the value of this variable.

If possible please try to wrap the text to 80 chars, we try to do that as per
our standards.md document.

> +
> +      The initramfs image size undergoes several calculation steps before it is compared with ``INITRAMFS_MAXSIZE``.

For INITRAMFS_MAXSIZE and all the other yocto variables below, please use
the :term: role, e.g.: ":term:`INITRAMFS_MAXSIZE`" instead of
"``INITRAMFS_MAXSIZE``".

This will create a hyperlink to the other variables (they need to be documented
too of course, if not you can try adding documentation for them or leave the ``
syntax).

> +      In the first step, the size of the directory pointed to by ``IMAGE_ROOTFS`` is calculated.
> +      In the second step, the result from the first step is multiplied by ``IMAGE_OVERHEAD_FACTOR``.
> +      In the third step, the result from the second step is compared with ``IMAGE_ROOTFS_SIZE``.
> +      The larger value of these is added to ``IMAGE_ROOTFS_EXTRA_SPACE``.
> +      In the fourth step, the result from the third step is checked for a decimal part. If it has one,
> +      it is rounded up to the next integer. If it does not, it is simply converted into an integer.
> +      In the fifth step, the ``IMAGE_ROOTFS_ALIGNMENT`` is added to the result from the fourth step
> +      and the value "-1" is subtracted.
> +      In the sixth step, the remainder of the division between the result from the fifth step
> +      and ``IMAGE_ROOTFS_ALIGNMENT`` is subtracted from the result of the fifth step.
> +      In this way, the result from the fourth step is rounded up to the nearest multiple of ``IMAGE_ROOTFS_ALIGNMENT``.
> +
> +      Thus, ``INITRAMFS_MAXSIZE`` is compared with the result of the above calculations
> +      and is independent of the final image type.
> +      A default value for ``INITRAMFS_MAXSIZE`` is set in ``meta/conf/bitbake.conf``.

You can use:

:oe_git:`meta/conf/bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>`

To create a link to that file in OE-Core.

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

Do you think you could port this documentation to the definition of
IMAGE_ROOTFS_MAXSIZE, to my understanding they're calculated the same way.

I would maybe do it that way:

- A first patch rewrites the documentation for IMAGE_ROOTFS_SIZE with what you
  described above (all the details above).
- A second patch documents the INITRAMFS_MAXSIZE variable but does not
  duplicate the content of IMAGE_ROOTFS_MAXSIZE's description, but rather create
  a link to the IMAGE_ROOTFS_MAXSIZE definition.

What do you think?

Antonin

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

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

[Christos Gavros]

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

hi Antonin,

I guess it makes sense what you are suggesting.
I will make all the fixes based on your comments.

You mean a new patch for IMAGE_ROOTFS_MAXSIZE ( and not for IMAGE_ROOTFS_SIZE), right?

Also I will prepare a v3 for INITRAMFS_MAXSIZE.

Thank you
Christos

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

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

[Antonin Godard]

On Mon May 12, 2025 at 10:16 PM CEST, Christos Gavros via lists.yoctoproject.org wrote:
> hi Antonin,
>
> I guess it makes sense what you are suggesting.
> I will make all the fixes based on your comments.
>
> You mean a new patch for IMAGE_ROOTFS_MAXSIZE ( and not for IMAGE_ROOTFS_SIZE), right?

Yes exactly, IMAGE_ROOTFS_MAXSIZE not IMAGE_ROOTFS_SIZE.

>
> Also I will prepare a v3 for INITRAMFS_MAXSIZE.

Thanks!
Antonin

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