Yocto Bundled Initramfs: Explain the Extra Kernel Pass Without Creating a Dependency Cycle
An initramfs needs a kernel module to reach the real root filesystem. The kernel image must also contain that initramfs. A naive task dependency says the kernel needs the image first, while the image needs kernel output first, creating a cycle.
Yocto's bundled-initramfs flow separates the initial kernel/module production from the later bundling pass. The extra pass is part of the dependency design, not evidence that the same complete build was accidentally scheduled twice.
Select an image recipe and enable bundling separately
The INITRAMFS_IMAGE reference identifies the providing image recipe. That recipe should produce the configured initramfs format. The variable names a recipe provider, not an arbitrary cpio file copied into the deploy directory.
The separate INITRAMFS_IMAGE_BUNDLE setting enables a combined kernel/initramfs binary through an extra compilation pass using CONFIG_INITRAMFS_SOURCE. Set this control in configuration, as the reference requires, rather than hiding it inside an image recipe.
For an illustrative recovery image, the configuration could select INITRAMFS_IMAGE = "sensor-initramfs" and INITRAMFS_IMAGE_BUNDLE = "1". The named recipe must exist and contain the early-userspace components actually required by the product.
Selecting an initramfs and bundling it are distinct choices. The examined implementation also supports building the selected image standalone when bundling is disabled; that does not establish that the deployed kernel contains it.
Follow the late dependency rather than adding an early one
The examined kernel class attaches the selected image's do_image_complete dependency to do_bundle_initramfs. It places bundling after kernel installation and before deployment.
That placement permits kernel output, including module packages needed by the initramfs, to be produced before the completed initramfs becomes an input to the final kernel pass. The documented purpose is to avoid the circular relationship that would arise if initial kernel production waited on an image containing those modules.
Inspect bitbake -g virtual/kernel for the actual product graph. Follow the initramfs image's module-package dependencies and the kernel bundling dependency as separate edges. If a custom class makes do_configure or initial do_compile depend on completion of that image, investigate whether it has reintroduced the cycle.
The class retains an older INITRAMFS_TASK mechanism with an explicit warning about circular dependencies involving modules. Do not copy an old example into a current configuration merely because its variable name sounds more direct.
Inspect the archive consumed by the second pass
The initramfs build guide describes the image and bundling workflow. For a failure in the second pass, start with its generated log and the effective INITRAMFS_IMAGE_NAME and deploy directory.
The examined class searches supported cpio archive forms, copies the selected image into the kernel build area and decompresses it when needed. It then invokes kernel compilation with CONFIG_INITRAMFS_SOURCE pointing at that local cpio input. A wrong image name or unavailable archive is therefore a different failure from a dependency cycle.
The implementation preserves the original kernel output while saving a separate initramfs-bearing output. Inspect the artifact selected by the product's deployment and boot configuration. Finding a successful bundle task does not prove that the boot path selected the bundled variant.
Keep the fix at the failing boundary
If BitBake reports a circular dependency, correct task ordering rather than supplying an old archive manually. If bundling cannot find its input, inspect image completion, naming and supported archive output. If boot lacks the expected early userspace, confirm the actual selected kernel artifact before changing module packaging.
Use an initramfs marker or narrowly scoped early-boot diagnostic in a controlled test image to distinguish the intended early filesystem from another boot input. Check that required modules correspond to the kernel being booted. The late pass solves build ordering; it does not validate module compatibility, early-userspace behavior or the product's final boot selection.
