Skip to main content
Use the OTA upgrade software to migrate from Qualcomm Linux 1.0 to Qualcomm Linux 2.0 using a robust and scalable OTA update framework through OSTree and capsule. In Qualcomm Linux 1.0, OSTree is supported as the default mechanism for managing Linux upgrades. OSTree provides a version-controlled, immutable file system structure that enables the following:
  • Atomic upgrades
  • Rollback capabilities
  • Efficient delta-based updates
This mechanism makes it suitable for embedded and edge platforms, ensuring that system updates are reliable, consistent, and recoverable in case of failures. For firmware updates, UEFI capsule updates are used, which offer a secure and standardized method for delivering low-level binaries. The UEFI firmware validates the capsule updates during the boot process, ensuring integrity, authenticity, and compatibility with secure boot environments. This mechanism minimizes the risk of crashing devices and supports seamless integration with the existing boot loader infrastructure. Qualcomm Linux 2.0 supports the same update mechanisms. That is, OSTree for Linux and capsule updates for firmware. This unified approach simplifies the migration process to enhance system resilience and lays the foundation for scalable OTA update management of future Qualcomm Linux releases.

​
Use capsule and OSTree repos to upgrade devices

To upgrade devices running Qualcomm Linux 1.0 to Qualcomm Linux 2.0, use the following:
  • OTA upgrade through capsule for the boot firmware
  • OSTree repos for Linux
When upgrading, it’s recommended that the OTA upgrade operation covers the OSTree repo and capsule together. Consider the following limitations and considerations when upgrading a device running Qualcomm Linux 1.0.

​
Partitioning operation limitations

The following operations aren’t supported for OTA upgrade as they make the device susceptible to crashes in the field:
  • Repartitioning to resize any partition, that is, partition size can’t be increased or decreased
  • Changing partition labels
  • Changing partition GUIDs
  • Changing the attribute flags of partitions
  • Moving a partition from LUN-X to LUN-Y
  • Deleting partitions from any logical unit number (LUN)

​
Boot firmware partitions size considerations for non-Linux partitions

For any device running Qualcomm Linux 1.0, the boot firmware LUN has partitions dedicated to images, such as XBL, TZ, UEFI, and DTB. The partition sizes are defined when the device is provisioned with Qualcomm Linux 1.0. These partitions may have some unused space. For example, the unused space in QCS6490 is as follows:
  • 700 KB for UEFI
  • 25 KB for TZ
  • 60 MB for DTB
You can use the unused space for features or other modules that can fit within it. If the feature added increases the firmware binary size such that it can fit the partition size already pre-allocated, you can use capsule to update the image in the target partition. It’s recommended that the OTA path doesn’t upgrade the hypervisor. That is, if the device is using Qualcomm Linux 1.0 with Gunyah, upgrades must continue supporting it.

​
Linux image partitions considerations for EFI

In Qualcomm Linux 1.0, the EFI partition GUID and part-label are already standard: C12A7328-F81F-11D2-BA4B-00A0C93EC93B and EFI, respectively. Therefore, you can upgrade from Qualcomm Linux 1.0 to Qualcomm Linux 2.0 through OTA, and the EFI partition mounts as expected. The system mounts this partition to the /boot mount point. Note The label and GUID can’t be changed over OTA.

​
Linux image partitions considerations for Rootfs

For an OSTree-enabled build, the root file system is searched using the OTAROOT label, which is standard in Qualcomm Linux 1.0. Hence, on OTA upgrade from Qualcomm Linux 1.0 to Qualcomm Linux 2.0 using OSTree rootfs mounting works as expected. A Qualcomm Linux 1.0 device going through the upgrade can’t change the partition label (partition name) to rootfs. The partition label continues to read system when inspected with tools, such as gdisk or sgdisk. Note The standard GUID in use for the rootfs partition for both Qualcomm Linux 1.0 and Qualcomm Linux 2.0 is B921B045-1DF0-41C3-AF44-4C6F280D3FAE.

​
Persist partition considerations

In Qualcomm Linux 1.0, the persist partition resides on LUN0. When you update a device from Qualcomm Linux 1.0 to the mainline, you can’t move the persist partition from Linux images LUN0 to the boot-firmware LUN4. After Qualcomm Linux 1.0 to Qualcomm Linux 2.0 OTA upgrade, systemd units mount the persist partition using the part-label to /var/lib/tee.

​
Userspace reference to partition labels

If your userspace utilities or libraries refer to the root partition label system in Qualcomm Linux 1.0, you must update them to use either the boot specification GUID or findmnt to discover the root partition. This change preserves compatibility when you upgrade to Qualcomm Linux 2.0. Note Libraries must use the GUID-based reference method to be able to reliably find the rootfs partition.

​
Image considerations

A Qualcomm Linux 1.0 device may be running with one of the following image variants:
  • Base variant, that is, qcom-multimedia-image built with qcom-base-bsp and qcom-base-distro overrides
  • Custom variant, that is, qcom-multimedia-image built with qcom-custom-bsp and qcom-custom-distro overrides
The corresponding images in Qualcomm Linux 2.0 are as follows:
  • The qcom-multimedia-image image built with qcom-base-bsp and qcom-base-distro overrides in Qualcomm Linux 1.0 correspond to qcom-multimedia-image in Qualcomm Linux 2.0.
  • The qcom-multimedia-image image built with qcom-custom-bsp and qcom-custom-distro overrides in Qualcomm Linux 1.0 correspond to qcom-multimedia-proprietary-image in Qualcomm Linux 2.0.

​
Deploy Qualcomm Linux 2.0 image on devices running Qualcomm Linux 1.0 images

After development is complete for Qualcomm Linux 2.0, select an image between Config #1 and Config #4, based on your product requirements. Images for the following two configurations are already predefined as recipes in meta-qcom-distro:
  • Config #1: qcom-multimedia-image
  • Config #2: qcom-multimedia-proprietary-image
You can define the images for Config #3 and Config #4 on your own. For instructions, see Define the image recipe for Config #3 and Config #4. Ensure that you enable DISTRO_FEATURE sota for the image defined for your product, so that the OSTree framework is enabled in the image. OTA with OSTree and capsule handles the following partitions:
  • EFI: OSTree
  • ROOTFS: OSTree
  • Boot firmware: Capsule

​
OTA update commands considerations

The OTA update steps are similar between Qualcomm Linux 1.0 and Qualcomm Linux 2.0. For instructions, see Qualcomm Linux Yocto Guide. In Qualcomm Linux 2.0, you don’t need to perform the following OTA-update step. This command is supported only in Qualcomm Linux 1.0.
  • Running the uefi_sec app on the device to save the efivars to replay protected memory block (RPMB): 
    /usr/bin/uefi_sec 1
The step is skipped in Qualcomm Linux 2.0 because the EFI variables are stored in the EFI partition when you run the following step: 
efivar -n <node name> -f data.hex -w