[PATCH 0/1] image: introduce IMAGE_INITRD, deprecate INITRD_IMAGE

[PATCH 0/1] image: introduce IMAGE_INITRD, deprecate INITRD_IMAGE

['Cedric Hombourger' via isar-users]

INITRD_IMAGE could be set to the full name of an initrd image to be
found in DEPLOY_DIR_IMAGE. Downstream layers had to assume how Isar
names its image artifacts (${DISTRO}-${IMAGE}-initrd.img suffix for
initrd images) and insert the build of their initramfs recipe into
the image build pipeline.

IMAGE_INITRD is introduced to (1) have a constistent naming convention
for variables consumed by the image class (IMAGE_ prefix) (2) only
require this variable to be set when a custom initrd should be built
and used by the imager.

For instance, cip-core was doing the following:

   INITRAMFS_RECIPE ?= "cip-core-initramfs"
   INITRD_IMAGE = "${INITRAMFS_RECIPE}-${DISTRO}-${MACHINE}.initrd.img"
   do_image_wic[depends] += "${INITRAMFS_RECIPE}:do_build"

And it could now be changed to:

   IMAGE_INITRD ?= "cip-core-initramfs"

(their layer would likely keep their INITRAMFS_RECIPE variable as it
may be considered as an API towards its own downstream users).

INITRD_IMAGE is "only" deprecated; meaning that it may still be used
(but build-time warnings will be raised). If both IMAGE_INITRD and
INITRD_IMAGE are set then the latter will be ignored (a warning noting
that both were set will be emitted).

These changes were tested against (1) new CI test-cases and (2) CIP
Core 1.9.0 both with and without adaptions to its code.

Patch dependencies:
 [1] https://lists.isar-build.org/isar-users/20251101111326.600581-1-cedric.hombourger@siemens.com/T/#t
 [2] https://lists.isar-build.org/isar-users/20251030094451.1303871-1-Quirin.Gylstorff@siemens.com/T/#t

InitRd tests:

  builder@ed1e0b7e8d4e:/work/testsuite$ trun --max-parallel-tasks=1 -p sstate=1 -t initrd citest.py
  JOB ID     : bdf8f7130f426014b0c008d0095ad317a9f66bee
  JOB LOG    : /tmp/tmp72bozbdi/avocado/job-results/job-2025-11-02T18.30-bdf8f71/job.log
   (1/8) citest.py:InitRdTest.test_dracut_in_image: STARTED
   (1/8) citest.py:InitRdTest.test_dracut_in_image: PASS (104.93 s)
   (2/8) citest.py:InitRdTest.test_dracut_build_initrd: STARTED
   (2/8) citest.py:InitRdTest.test_dracut_build_initrd: PASS (34.36 s)
   (3/8) citest.py:InitRdTest.test_dracut_build_failure: STARTED
   (3/8) citest.py:InitRdTest.test_dracut_build_failure: FAIL: Bitbake suceeded but was expected to fail! (143.54 s)
   (4/8) citest.py:InitRdTest.test_var_initrd_image: STARTED
   (4/8) citest.py:InitRdTest.test_var_initrd_image: PASS (259.88 s)
   (5/8) citest.py:InitRdTest.test_var_image_initrd: STARTED
   (5/8) citest.py:InitRdTest.test_var_image_initrd: PASS (237.34 s)
   (6/8) citest.py:InitRdTest.test_var_image_initrd_and_initrd_image: STARTED
   (6/8) citest.py:InitRdTest.test_var_image_initrd_and_initrd_image: PASS (242.03 s)
   (7/8) citest.py:InitRdCrossTests.test_dracut_in_image: STARTED
   (7/8) citest.py:InitRdCrossTests.test_dracut_in_image: PASS (407.83 s)
   (8/8) citest.py:InitRdCrossTests.test_dracut_build_initrd: STARTED
   (8/8) citest.py:InitRdCrossTests.test_dracut_build_initrd: PASS (44.71 s)
  RESULTS    : PASS 7 | ERROR 0 | FAIL 1 | SKIP 0 | WARN 0 | INTERRUPT 0 | CANCEL 0
  JOB TIME   : 1482.17 s

See [1] and/or [2] for an explanation (and proposed fix) for the single
test failure.

Cedric Hombourger (1):
  image: introduce IMAGE_INITRD, deprecate INITRD_IMAGE

 RECIPE-API-CHANGELOG.md    | 28 +++++++++++++
 doc/user_manual.md         |  3 +-
 meta/classes/image.bbclass | 31 ++++++++++++--
 testsuite/citest.py        | 83 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 140 insertions(+), 5 deletions(-)

-- 
2.47.3

-- 
You received this message because you are subscribed to the Google Groups "isar-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/isar-users/20251102190129.727186-1-cedric.hombourger%40siemens.com.

[PATCH 1/1] image: introduce IMAGE_INITRD, deprecate INITRD_IMAGE

['Cedric Hombourger' via isar-users]

INITRD_IMAGE could be set to the full name of an initrd image to be
found in DEPLOY_DIR_IMAGE. Downstream layers had to assume how Isar
names its image artifacts (${DISTRO}-${IMAGE}-initrd.img suffix for
initrd images) and insert the build of their initramfs recipe into
the image build pipeline.

IMAGE_INITRD is introduced to (1) have a constistent naming convention
for variables consumed by the image class (IMAGE_ prefix) (2) only
require this variable to be set when a custom initrd should be built
and used by the imager.

For instance, cip-core was doing the following:

   INITRAMFS_RECIPE ?= "cip-core-initramfs"
   INITRD_IMAGE = "${INITRAMFS_RECIPE}-${DISTRO}-${MACHINE}.initrd.img"
   do_image_wic[depends] += "${INITRAMFS_RECIPE}:do_build"

And it could now be changed to:

   INITRD_IMAGE ?= "cip-core-initramfs"

(their layer would likely keep their INITRAMFS_RECIPE variable as it
may be considered as an API towards its own downstream users).

INITRD_IMAGE is "only" deprecated; meaning that it may still be used
(but build-time warnings will be raised). If both IMAGE_INITRD and
INITRD_IMAGE are set then the latter will be ignored (a warning noting
that both were set will be emitted).

These changes were tested against (1) new CI test-cases and (2) CIP
Core 1.9.0 both with and without adaptions to its code.

Signed-off-by: Cedric Hombourger <cedric.hombourger@siemens.com>
---
 RECIPE-API-CHANGELOG.md    | 28 +++++++++++++
 doc/user_manual.md         |  3 +-
 meta/classes/image.bbclass | 31 ++++++++++++--
 testsuite/citest.py        | 83 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 140 insertions(+), 5 deletions(-)

diff --git a/RECIPE-API-CHANGELOG.md b/RECIPE-API-CHANGELOG.md
index cf04fa5c..78c7eae0 100644
--- a/RECIPE-API-CHANGELOG.md
+++ b/RECIPE-API-CHANGELOG.md
@@ -791,3 +791,31 @@ Set `Rules-Requires-Root: no` in `debian/control` files to prevent unnecessary
 invocation of fakeroot during package builds. This follows Debian guidelines
 recommending not to use fakeroot when no privileged operations (e.g., `chown`,
 root file modifications) are required. 
+
+### IMAGE_INITRD added to replace INITRD_IMAGE
+
+INITRD_IMAGE could be set to the full name of an initrd image to be found in
+DEPLOY_DIR_IMAGE. Downstream layers had to assume how Isar names its image
+artifacts (presently adding a ${DISTRO}-${IMAGE}-initrd.img suffix to initrd
+images) and insert the build of their initramfs recipe into the image build
+pipeline.
+
+IMAGE_INITRD is introduced to (1) have a constistent naming convention for
+variables consumed by the image class (IMAGE_ prefix) (2) only require
+this variable to be set when a custom initrd should be built and used by the
+imager.
+
+For instance, cip-core was doing the following:
+
+     INITRAMFS_RECIPE ?= "cip-core-initramfs"
+     INITRD_IMAGE = "${INITRAMFS_RECIPE}-${DISTRO}-${MACHINE}.initrd.img"
+     do_image_wic[depends] += "${INITRAMFS_RECIPE}:do_build"
+
+And it could now be changed to:
+
+     IMAGE_INITRD ?= "cip-core-initramfs"
+
+INITRD_IMAGE is "only" deprecated; meaning that it may still be used (but
+build-time warnings will be raised). If both IMAGE_INITRD and INITRD_IMAGE
+are set then the latter will be ignored (a warning noting that both were
+set will be emitted).
diff --git a/doc/user_manual.md b/doc/user_manual.md
index 7133b217..230ea1cc 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -574,7 +574,7 @@ Every machine is described in its configuration file. The file defines the follo
    - U-Boot or other boot loader.
    - Machine-specific firmware.
  - `KERNEL_IMAGE` - The name of kernel binary that it installed to `/boot` folder in target filesystem. This variable is used by Isar to extract the kernel binary and put it into the deploy folder. This makes sense for embedded devices, where kernel and root filesystem are written to different flash partitions. This variable is optional.
- - `INITRD_IMAGE` - The name of `ramdisk` binary. The meaning of this variable is similar to `KERNEL_IMAGE`. This variable is optional.
+ - `INITRD_IMAGE` - The name of `initramfs` recipe to be built and used by the imager.
  - `MACHINE_SERIAL` - The name of serial device that will be used for console output.
  - `IMAGE_FSTYPES` - The types of images to be generated for this machine.
 
@@ -583,7 +583,6 @@ Below is an example of machine configuration file for `Raspberry Pi` board:
 IMAGE_PREINSTALL = "linux-image-rpi-rpfv \
                     raspberrypi-bootloader-nokernel"
 KERNEL_IMAGE = "vmlinuz-4.4.0-1-rpi"
-INITRD_IMAGE = "initrd.img-4.4.0-1-rpi"
 MACHINE_SERIAL = "ttyAMA0"
 IMAGE_FSTYPES = "wic"
 WKS_FILE = "rpi-sdimg"
diff --git a/meta/classes/image.bbclass b/meta/classes/image.bbclass
index 441ea936..dff918d7 100644
--- a/meta/classes/image.bbclass
+++ b/meta/classes/image.bbclass
@@ -21,10 +21,35 @@ IMAGE_INSTALL += "${KERNEL_IMAGE_PKG}"
 # Name of the image including distro&machine names
 IMAGE_FULLNAME = "${PN}-${DISTRO}-${MACHINE}"
 
-# These variables are used by wic and start_vm
-KERNEL_IMAGE ?= "${IMAGE_FULLNAME}-${KERNEL_FILE}"
+# Deprecated; this would be set to e.g. "${INITRAMFS_RECIPE}-${DISTRO}-${MACHINE}.initrd.img"
 INITRD_IMAGE ?= ""
-INITRD_DEPLOY_FILE = "${@ d.getVar('INITRD_IMAGE') or '${IMAGE_FULLNAME}-initrd.img'}"
+
+# IMAGE_INITRD should be used instead (variables consumed by this image class should
+# be prefixed with IMAGE_ for consistency)
+IMAGE_INITRD ?= ""
+
+# Name of the deployed initrd image
+INITRD_DEPLOY_FILE = "${@ d.getVar('IMAGE_INITRD') or '${PN}' }-${DISTRO}-${MACHINE}-initrd.img"
+
+# Make sure dependent initramfs recipe is built
+do_image[depends] += "${@ '${IMAGE_INITRD}:do_build' if '${IMAGE_INITRD}' else '' }"
+
+# Produce warning(s) if INITRD_IMAGE is used
+python() {
+    initrd_image = d.getVar('INITRD_IMAGE')
+    image_initrd = d.getVar('IMAGE_INITRD')
+    if initrd_image and image_initrd:
+        bb.warn('both INITRD_IMAGE (deprecated) and IMAGE_INITRD were set, '
+                'ignoring INITRD_IMAGE and using '
+                f'IMAGE_INITRD = "{image_initrd}"')
+        d.setVar('INITRD_IMAGE', '')
+    elif initrd_image:
+        bb.warn('INITRD_IMAGE is deprecated, use IMAGE_INITRD instead')
+        d.setVar('INITRD_DEPLOY_FILE', initrd_image)
+}
+
+# This variable is used by wic and start_vm
+KERNEL_IMAGE ?= "${IMAGE_FULLNAME}-${KERNEL_FILE}"
 
 # This defines the deployed dtbs for reuse by imagers
 DTB_FILES ?= ""
diff --git a/testsuite/citest.py b/testsuite/citest.py
index e53dfa9b..f944ee4a 100755
--- a/testsuite/citest.py
+++ b/testsuite/citest.py
@@ -288,6 +288,13 @@ class InitRdBaseTest(CIBaseTest):
         "IMAGE_INSTALL:remove = 'enable-fsck'",
     ]
 
+    def init(self):
+        super().init()
+        self.deploy_dir = os.path.join(self.build_dir, 'tmp', 'deploy')
+
+    def deploy_dir_image(self, machine):
+        return os.path.join(self.deploy_dir, 'images', machine)
+
     def dracut_in_image(self, targets):
         machine = 'qemuamd64'
         distro = 'bookworm'
@@ -308,6 +315,36 @@ class InitRdBaseTest(CIBaseTest):
                 cmd="systemctl is-active dracut-shutdown"
             )
 
+    def build_image_with_dependent_initrd(self, image, initrd,
+                                          distro="debian-bookworm",
+                                          machine="qemuamd64",
+                                          lines='',
+                                          bb_should_fail=False):
+        mc = f'mc:{machine}-{distro.removeprefix("debian-")}'
+        initrd_image = f'{initrd}-{distro}-{machine}.initrd.img'
+        initrd_path = os.path.join(self.deploy_dir_image(machine), initrd_image)
+
+        # cleansstate if the initrd image was already built/deployed to verify
+        # that a new build does result in the image being deployed
+        ret, _, err = self.exec_cmd(f'{mc}:{initrd}', 'bitbake -c cleansstate')
+        if ret:
+            self.fail(f"failed to clean {initrd}: {err}")
+
+        # Make sure it is no longer deployed
+        if os.path.exists(initrd_path):
+            os.unlink(initrd_path)
+
+        # Build the rootfs image and verify that its dependent initrd image
+        # was built and deployed
+        self.perform_build_test(f'{mc}:{image}', lines=lines, should_fail=bb_should_fail)
+
+        if bb_should_fail is False:
+            if os.path.exists(initrd_path) is False:
+                self.fail(f"initrd image not found: {initrd_path}!")
+        else:
+            if os.path.exists(initrd_path):
+                self.fail(f"initrd found despite bitbake failure: {initrd_path}!")
+
 
 class InitRdTest(InitRdBaseTest):
     """
@@ -332,6 +369,52 @@ class InitRdTest(InitRdBaseTest):
         self.perform_build_test('mc:qemuamd64-bookworm:isar-image-ci',
                                 should_fail=True, lines=lines)
 
+    def test_var_initrd_image(self):
+        """ Check if deprecated INITRD_IMAGE variable may be used. """
+        initrd = 'isar-initramfs'
+        distro = 'debian-bookworm'
+        machine = 'qemuamd64'
+
+        lines = [
+            f"INITRD_IMAGE = '{initrd}-{distro}-{machine}.initrd.img'",
+            f"do_image[depends] += '{initrd}:do_build'"
+        ]
+
+        self.init()
+        self.build_image_with_dependent_initrd('isar-image-ci', initrd,
+                                               distro, machine, lines)
+
+    def test_var_image_initrd(self):
+        """ Check build of an image with a dependent initrd using IMAGE_INITRD. """
+        initrd = 'isar-initramfs'
+        lines = [f"IMAGE_INITRD = '{initrd}'"]
+
+        self.init()
+        self.build_image_with_dependent_initrd('isar-image-ci', initrd, lines=lines)
+
+    def test_var_image_initrd_and_initrd_image(self):
+        """ Check use of both IMAGE_INITRD and INITRD_IMAGE. """
+        initrd = 'isar-initramfs'
+
+        self.init()
+
+        # While both may be set, IMAGE_INITRD takes precedence. Ensure
+        # by specifying an invalid recipe name: bitbake should fail.
+        lines = [
+            "IMAGE_INITRD = 'not-a-valid-initrd-recipe'",
+            f"INITRD_IMAGE = '{initrd}-debian-bookworm-qemuamd64.initrd.img'"
+        ]
+        self.build_image_with_dependent_initrd('isar-image-ci', initrd, lines=lines,
+                                               bb_should_fail=True)
+
+        # The build should succeed if we have a valid IMAGE_INITRD even
+        # with an invalifd INITRD_IMAGE
+        lines = [
+            f"IMAGE_INITRD = '{initrd}'",
+            "INITRD_IMAGE = 'not-a-valid-initrd-file'"
+        ]
+        self.build_image_with_dependent_initrd('isar-image-ci', initrd, lines=lines)
+
 
 class InitRdCrossTests(InitRdBaseTest):
     """
-- 
2.47.3

-- 
You received this message because you are subscribed to the Google Groups "isar-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/isar-users/20251102190129.727186-2-cedric.hombourger%40siemens.com.