linksys,homewrk: factory.ubi does not match raw-kernel flash layout

Describe the bug

The Linksys HomeWRK squashfs-factory.ubi image does not match the device's actual boot and flash layout.

HomeWRK uses separate raw kernel and rootfs partitions:

mtd21  kernel
mtd22  rootfs
mtd23  alt_kernel
mtd24  alt_rootfs

Stock U-Boot reads the FIT directly from the selected raw kernel / alt_kernel partition, then attaches the corresponding rootfs / alt_rootfs UBI.

However, the HomeWRK image recipe calls Device/UbiFit, which sets KERNEL_IN_UBI := 1. The resulting factory.ubi therefore contains the kernel inside UBI as volume 0, followed by the rootfs.

The documented HomeWRK installation method writes that image only to the rootfs partition:

ubiformat /dev/mtd22 -y -f openwrt-*-linksys_homewrk-squashfs-factory.ubi

That never writes an OpenWrt kernel to raw mtd21, which is where U-Boot actually loads the primary kernel.

This appears to have been present since the original HomeWRK support was added, rather than being a regression from the current HomeWRK boot/A-B fixes.

OpenWrt version

r33051-f5dae5ece4

OpenWrt release

25.12.5

OpenWrt target/subtarget

qualcommax/ipq807x

Device

Linksys HomeWRK

Image kind

Official downloaded image

Steps to reproduce

1. Obtain the official OpenWrt 25.12.5 HomeWRK images.

2. Observe that the generated factory image is:

openwrt-25.12.5-qualcommax-ipq807x-linksys_homewrk-squashfs-factory.ubi

3. Inspect the HomeWRK image recipe. Device/linksys_homewrk calls:

$(call Device/FitImage)
$(call Device/UbiFit)

Device/UbiFit sets:

KERNEL_IN_UBI := 1

so the generated UBI contains the kernel as a UBI volume rather than as a separate raw kernel image.

4. Compare this with the actual HomeWRK flash layout and stock U-Boot environment.

The relevant partitions are:

mtd21  kernel
mtd22  rootfs
mtd23  alt_kernel
mtd24  alt_rootfs

Stock U-Boot uses separate raw kernel offsets, including:

prikern=1240000
altkern=c180000
kernsize=800000

and its boot commands perform a raw NAND read of the selected kernel before bootm.

5. The currently documented factory installation command writes only the rootfs MTD:

ubiformat /dev/mtd22 -y -f openwrt-25.12.5-qualcommax-ipq807x-linksys_homewrk-squashfs-factory.ubi

No corresponding write is made to raw mtd21.

No destructive flash of the factory.ubi is required to reproduce the layout mismatch.

Actual behaviour

OpenWrt generates a HomeWRK factory.ubi whose kernel is stored inside the UBI image.

The documented installation procedure writes that UBI only to mtd22, while stock U-Boot loads the primary kernel directly from raw mtd21.

Therefore the generated factory image and documented installation procedure do not match the device's boot architecture.

There is a second inconsistency with the corrected sysupgrade layout: the factory.ubi places the kernel at UBI volume 0, while normal HomeWRK sysupgrade writes the kernel to raw kernel / alt_kernel and creates rootfs as UBI volume 0.

Expected behaviour

The generated HomeWRK factory image should match the device's actual raw-kernel + UBI-rootfs flash layout.

Possible fixes include:

1. Replace the current Device/UbiFit factory image with an image that contains a raw kernel followed by the rootfs UBI, similar to the related Linksys MX devices, with an appropriate KERNEL_SIZE check; or

2. Stop generating the HomeWRK factory.ubi if there is no valid supported installation use for it.

The installation documentation should not recommend writing the current factory.ubi directly to mtd22.

Additional info

The raw-kernel / UBI-rootfs layout has been verified on four physical Linksys HomeWRK units.

Complete stock backups from all four units show identical factory images across both A/B slots and across all four devices.

Factory kernel SHA256:

cfb760f910e674cb1e8133bf4b58d053cbd4ead0911ab470d6743b6efb6b6bf9

For every unit:

mtd21 == mtd23

and all eight mtd21/mtd23 images across the four units have that same hash.

Factory rootfs SHA256:

0fc0f4a62be0bb887775a73ee7b4690a5b709b6abb54a4ca14cca08e0adc9fb9

For every unit:

mtd22 == mtd24

and all eight mtd22/mtd24 images across the four units have that same hash.

The common factory rootfs image contains UBI volume 0 named squashfs.

The known-good installation path is to boot the OpenWrt initramfs and use:

sysupgrade -n openwrt-*-linksys_homewrk-squashfs-sysupgrade.bin

That path writes the raw kernel partition and rootfs UBI separately.

The corrected HomeWRK A/B sysupgrade implementation has been tested in both directions, including installation from OEM firmware, successful-boot counter reset, and automatic U-Boot rollback. The same functional changes built against OpenWrt 25.12.5 have been deployed successfully on all four physical HomeWRK units.

Related:

• PR #24867 - qualcommax: ipq807x: fix Linksys HomeWRK boot integration
• #24836 - HomeWRK stock -> OpenWrt sysupgrade boot failure
• Original HomeWRK support commit: 07f8319d2d9166a41c2fd94ec1422bcd80ada991

The original HomeWRK support commit documents both the known-good initramfs -> sysupgrade.bin installation and the ubiformat ... factory.ubi alternative. The latter appears to have been inconsistent with the raw-kernel boot layout from the time support was introduced.

The OpenWrt wiki currently also documents the ubiformat /dev/mtd22 ... factory.ubi alternative and should be corrected to remove it unless/until a compatible factory image is provided.

Diffconfig

Terms

• I am reporting an issue for OpenWrt, not an unsupported fork.

Inspect the linksys_homewrk image recipe and the Device/UbiFit and Device/FitImage definitions first, then compare the related Linksys MX image recipes and PR #24867. Verify the generated factory and sysupgrade artifacts against the documented raw kernel and UBI partitions. Done means the factory path matches the boot layout, or is removed, and the wiki no longer recommends the incompatible command.