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

[Mikko Rapeli <mikko.rapeli@linaro.org>]

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