使用 capsule 和 OSTree 机制在 Qualcomm Linux 上更新固件和操作系统

空中下载（OTA）更新对于保持设备正常运行至关重要，尤其是嵌入式系统和 IoT 设备。这些更新使设备能够接收并安装更新。 Qualcomm Linux 使用 capsule 更新机制来更新固件镜像，并使用 OSTree 更新机制来更新 Linux 操作系统。

​

使用 capsule 更新固件

Capsule 更新是一种在启用了 Qualcomm Linux 的设备上更新固件的方法。UEFI capsule 将固件打包成二进制格式。当设备启动并在正常任务模式下运行时，它会下载 capsule 并将其部署到 EFI 分区。重启后，在下一个启动周期中，UEFI 会处理该 capsule 并将更新应用到设备固件。

​

用于 Linux 操作系统更新的 OSTree

OSTree 是一个用于管理基于 Linux 的操作系统的版本控制、原子更新的工具。它的工作方式类似于整个 Linux 文件系统的 git 仓库。OSTree 将文件系统树的快照存储在仓库中，设备通过网络拉取这些快照。借助 OSTree，更新是原子性的并支持回滚，因此更新中断不会破坏系统。IoT 和边缘设备可以从安全、一致的更新中受益，在出现问题时可以回滚。

​

结合使用 capsule 和 OSTree 实现完整的 OTA 软件更新

要在单个 OTA 系统中管理固件和操作系统更新，请结合使用 capsule 和 OSTree 更新机制。capsule 更新机制首先处理固件更新，更新底层固件。capsule 更新完成后，系统重启并进入 Linux 操作系统，在那里检查并应用 OSTree 更新。Qualcomm Linux 使用 capsule 通过 UEFI 更新底层固件。 系统按照以下流程使用 capsule 更新固件：

1. 一个称为 UEFI capsule 的二进制文件封装了固件更新。
2. 系统通过将 capsule 二进制文件存储在挂载的 /EFI 路径中，将其传递给 UEFI。
3. UEFI 固件在启动周期中处理该 capsule，并将更新应用到设备固件。

Qualcomm Linux 使用 OSTree 管理 Linux 操作系统。系统将 Qualcomm Linux 构建生成的更新包复制到设备上，并使用使用 OSTree 的 Linux 操作系统更新流程中列出的命令将其暂存以待激活。设备重启后应用更新包。 下图显示了带有 OSTree 的 Linux 操作系统的存储视图。 Runtime 视图指示默认部署时存储中的哪些目录在运行时映射到相应的挂载点。 Storage after creation of new deployment 视图显示了当设备成功创建新的 OSTree 部署时闪存存储如何更新。该部署是新创建的，并在下次重启时尝试作为新的 Linux 操作系统。 以下是作为 OTA 一部分更新的 Linux 操作系统和固件镜像列表：

• Linux 操作系统镜像
• efi.bin 文件包含 UKI、initrd 和引导加载程序配置文件。OSTree 在部署期间创建一个新的配置文件。它列出了复制到 EFI 分区的新内核和 initramfs 镜像的路径。
• system.img 文件包含 rootfs，包括 /ostree、/ostree/repo 和 /ostree/deploy 等关键组件。创建新部署时，OSTree 会更新文件系统树以反映操作系统的新版本。
• 固件镜像 有关固件镜像列表的信息，请参阅 GitHub。

​

更新 capsule 和 HLOS

下图显示了 capsule 和高级操作系统（HLOS）更新流程： 要更新 capsule 和 HLOS，请执行以下操作：

1. 将 <capsule>.cap capsule 文件复制到 EFI 分区，该分区在已启动的设备上挂载于 /boot/EFI/UpdateCapsule。
2. 使用 EFI_OS_INDICATIONS_FILE_CAPSULE_DELIVERY_SUPPORTED 设置 EFI 变量（efivar）OsIndications 标志并重启设备。当 UEFI 通过 OsIndications 标志检测到 capsule 更新请求时，会执行以下步骤：
   1. UEFI 从 OsIndications 标志识别出有可用于更新的 capsule。
   2. UEFI 对 capsule 进行身份验证，并从 capsule 中更新固件镜像。
   3. capsule 更新的状态会更新到 EFI 系统资源表（ESRT）中。
   4. 如果 capsule 更新期间出现故障，UEFI 会将固件回滚到先前的版本。UEFI 成功从 capsule 更新固件后，设备将使用新固件启动。
3. 将 OSTree 仓库复制到设备上。使用 OSTree 命令为 HLOS 更新创建新部署，此时会创建一个带有计数标签的新配置文件，然后重启设备。
4. Systemd-boot 选取新的配置文件并启动内核和用户空间。设备使用更新后的固件和 HLOS 软件启动。systemd-bless-boot.service 将新配置标记为良好。
5. 重置 OtaStatus efivar 中的 TrialBootEnabled 标志，以指示固件正常。UEFI 会检查此 efivar 以提交新固件。

​

使用 capsule 更新固件

下图显示了固件更新流程： 要使用 capsule 更新固件，请执行以下操作：

注意 有关 firmware_capsule.cap capsule 生成的更多信息，请参阅 UEFI 中的 capsule 生成。

1. 要在设备上创建 UpdateCapsule 文件夹，请运行以下命令：
   adb shell mkdir /boot/EFI/UpdateCapsule
   
2. 将 capsule 复制到设备上：
   scp -r <firmware_capsule.cap> <user>@<IP_address>:/boot/EFI/UpdateCapsule/<firmware_capsule.cap>
   
3. 在设备上创建包含指定十六进制数据的 data.hex 文件：
   echo -e -n "\x4\x0\x0\x0\x0\x0\x0\x0" > data.hex
   
4. 使用 efivar 工具将设备上 data.hex 的内容写入 UEFI 变量 OsIndications：
   efivar -n 8be4df61-93ca-11d2-aa0d-00e098032b8c-OsIndications -f data.hex -w
   
   有关 UEFI 变量的更多信息，请参阅更新与恢复。
5. 使用 efivar 工具打印 OsIndications UEFI 变量的值：
   efivar -n 8be4df61-93ca-11d2-aa0d-00e098032b8c-OsIndications -p
   
6. 重启设备：
   reboot
   
7. 检查 ESRT 表条目：
   cd /sys/firmware/efi/esrt/entries/entry0
   
   1. 检查 last_attempt_status 命令的输出。如果为 0，则更新成功：
      cat last_attempt_status
      
   2. 检查 last_attempt_version 命令的输出：
      cat last_attempt_version
      
   3. 检查 fw_version 命令的输出。如果 last_attempt_version 和 fw_version 相同，则更新成功：
      cat fw_version
      

​

使用 OSTree 更新 Linux 操作系统

下图显示了 Linux 操作系统更新流程： 要使用 OSTree 更新 Linux 操作系统，请执行以下操作：

1. 要检查 Qualcomm 设备中的当前部署，请运行以下命令：
   ostree admin status
   
   输出：
   * poky 643b332dd72b345b5040a1decbe7e04bd2d208a04ba59417aa667c901c485504.0
      Version: 1.0
      origin refspec: poky:rb3gen2-core-kit
   
   * 表示设备当前启动所使用的部署。
2. ostree_repo 软件包位于主机开发计算机上的 <workspace>/build/tmp/deploy/images/<MACHINE>/ 路径中。例如，<workspace>/build/tmp/deploy/images/rb3gen2-core-kit/。使用以下 scp 命令将 ostree_repo 软件包从主机计算机复制到 Qualcomm 设备：
   scp -r <ostree_repo> <user>@<IP_address>:/tmp
   
3. 在 Qualcomm 设备上拉取本地 OSTree 仓库。
   ostree pull-local /tmp/<ostree_repo> <branch_name>
   
   要查找该命令所需的 branch_name，请运行以下命令：
   ostree refs
   
   输出：
   poky:rb3gen2-core-kit
   
   在上述输出中，rb3gen2-core-kit 是一个示例分支名称。
4. 在 Qualcomm 设备上创建部署：
   ostree admin deploy <branch_name>
   
   这会在 /boot/loader/entries/ 目录中创建 ostree-2-poky.conf 配置文件。有关更多信息，请参阅 Systemd 启动计数 - 成功启动。
5. 重启设备：
   reboot
   
6. 检查设备是否使用所创建的部署启动：
   ostree admin status
   
   输出：
   * poky 1e8a01bcc5cd9b3b34043db494ddcd01ec5c1c84312479a55253358a92250fa3.0
      Version: 1.0
      origin refspec: rb3gen2-core-kit
      poky 643b332dd72b345b5040a1decbe7e04bd2d208a04ba59417aa667c901c485504.0 (rollback)
      Version: 1.0
      origin refspec: poky:rb3gen2-core-kit
   
   要在构建主机计算机上验证新创建的部署，请检查 <workspace>/build/tmp/work/<MACHINE>/<IMAGE>/ota-sysroot/ostree/deploy/poky/deploy 路径中的部署。例如，<workspace>/build/tmp/work/rb3gen2-core-kit/qcom-multimedia-image/ota-sysroot/ostree/deploy/poky/deploy。

​

Systemd-boot 计数 - 成功启动

下图显示了成功启动时的 systemd-boot 计数流程： 为了在成功启动后管理 systemd-boot 中的启动计数，OSTree 执行以下流程：

1. 当 OSTree 部署新配置时，它会创建一个名称中带有 +3 标签的配置文件，表示最大重试次数。这启用了启动计数。
2. systemd-boot 检测到条目文件名中的 +3 标签，并将其重命名为 ostree-conf+2-1.conf，表示已开始一次启动尝试。重命名文件后，启动过程继续。
3. systemd-bless-boot-generator 创建 systemd-bless-boot.service，该服务被设置为在到达 boot-complete.target 时启动。
4. systemd-bless-boot.service 通过移除计数器标签 +2-1 并将文件重命名为 ostree-conf.conf，将新配置标记为成功。

​

Systemd 启动计数 - 启动失败与回滚

下图显示了启动失败和回滚时的 systemd-boot 计数流程： 为了在启动失败和回滚后管理 systemd-boot 中的启动计数，OSTree 执行以下流程：

1. 当 OSTree 部署新配置时，它会创建一个名称中带有 +3 标签的 systemd 配置文件，表示最大重试次数，例如 ostree-boot+3.conf。这启用了启动计数。
2. systemd-boot 检测到配置文件名中的 +3 标签，并将其重命名为 ostree-boot+2-1.conf，表示已开始一次启动尝试。重命名文件后，启动过程继续。
3. systemd-bless-boot-generator 创建 systemd-bless-boot.service，该服务在到达 boot-complete.target 时启动。如果 Linux 启动过程中出现任何故障，systemd-bless-boot.service 不会从配置文件中移除 +2-1 计数器标签。
4. 在随后的启动中，systemd-boot 检测到配置文件名中的 +2-1 标签，将文件重命名为 ostree-boot+1-2.conf，并尝试使用它启动。
5. 如果第二次尝试时 Linux 启动失败，systemd-bless-boot.service 不会从配置文件中移除计数器标签 +1-2。
6. 在下次启动时，systemd-boot 检测到配置文件名中的 +1-2 标签，将文件重命名为 ostree-boot+0-3.conf，并尝试使用它启动。这是启动 Linux 部署的最后一次尝试。
7. 如果设备在第三次尝试中未能启动 Linux，systemd-bless-boot.service 不会从配置文件中移除计数器标签 +0-3。
8. 在随后的启动中，systemd-boot 发现配置文件名中的 +0-3 标签。由于计数器已归零，该条目（配置文件）被视为无效。systemd-boot 通过尝试有效的配置文件条目回退到早期版本。

​

Usrmerge

Linux 中的 Usrmerge 功能通过将某些目录合并到 /usr 路径下来简化文件系统布局。它分别将 /bin、/sbin 和 /lib 与 /usr/bin、/usr/sbin 和 /usr/lib 合并。 启用 Usrmerge 后，/bin、/sbin 和 /lib 中的可执行文件和库分别放置在 /usr/bin、/usr/sbin 和 /usr/lib 中。原始目录成为指向其 /usr 对应目录的符号链接。这种统一的结构使维护更容易并减少冗余，因为二进制文件和库只有一个位置，而不是根级目录和 /usr 目录的单独位置。符号链接确保了兼容性，使引用 /bin 等路径的脚本和软件能够继续运行。 Linux 发行版正在采用 Usrmerge，以符合文件系统层次结构标准（FHS）建议，并简化根文件系统，特别是在容器化和嵌入式系统中。 Debian、Ubuntu 和 Fedora 等发行版已将 Usrmerge 作为其系统布局的一部分，使其成为最新版本中的标准。过渡过程包括创建符号链接，并将原始目录中剩余的文件移动到其 /usr 对应位置。

​

在 Qualcomm Linux 中管理 /var、/home、/media、/mnt、/opt、/srv 和 /usr

OSTree 将 /var 视为持久目录。这意味着用户和运行时在 /var 下创建的内容不会被 OSTree 触及，并在 OTA 更新之间保持不变。有关更多信息，请参阅 OSTree 概述。 在 OTA 更新期间不被 OSTree 触及的其他目录包括 /home、/media、/mnt、/opt 和 /srv。OSTree 将这些目录映射为符号链接，如下所示：

• /home 是指向 /var/rootdirs/home 的符号链接
• /media 是指向 /var/rootdirs/media 的符号链接
• /mnt 是指向 /var/rootdirs/mnt 的符号链接
• /opt 是指向 /var/rootdirs/opt 的符号链接
• /srv 是指向 /var/rootdirs/srv 的符号链接

存储在 /home、/media、/mnt、/opt、/srv 和 /var 下的任何运行时数据在 OTA 更新之间保持持久。 为了保持文件系统的干净和一致，请勿在构建时在上述目录下安装任何产物。在构建时安装在这些目录中的任何产物都不会被打包到由 Qualcomm Linux 构建命令（即 bitbake <image recipe>）生成的 rootfs 镜像中。 要处理持久路径下文件和目录的运行时创建，请执行以下操作： 进程在需要时于运行时创建这些文件或目录。

1. /run/、/var/lib/、/var/cache/ 和 /var/log/ 下的路径可以由相应的 systemd 单元文件创建。这里有一个参考。
2. 使用 systemd-tmpfiles 在启动时创建文件、符号链接和目录。

OSTree 在 /usr 处创建只读绑定挂载，确保核心操作系统文件对用户保持不可变。这种方法有助于维护系统完整性和安全性。OSTree 使用 /usr 挂载点部署下一次更新。

注意

• OSTree 允许在构建时在 /var/local 路径下安装文件和目录。
• 尽管 OSTree 会保留构建时安装在 /usr 下的内容，但它不会将安装在 /usr/local 子目录下的内容打包到 rootfs 镜像中。

在启用了 OSTree 的 Qualcomm Linux 中，/etc 目录的管理方式既支持系统更新，也支持本地定制。

• /etc 目录是可变的，允许在运行时进行修改，以维护需要在更新之间持久保留的系统配置。
• OSTree 支持将 /usr/etc 目录中的配置文件合并到 /etc。这使 OSTree 能够更新默认配置，同时保留所做的任何本地更改。
• 应用更新时，OSTree 会使用文件的原始版本、新更新中的文件版本以及本地修改的文件版本，对 /etc 中的配置文件执行三方合并。
• 如果合并过程中出现冲突，OSTree 会保留运行时的修改。这有助于保持系统稳定性，并确保关键配置不会被覆盖。

​

SOTA 发行版特性

软件空中下载（SOTA）发行版特性允许对嵌入式系统和 IoT 设备进行远程更新。它集成了 OSTree 等系统更新工具，使设备无需物理接触即可接收和安装更新。 要在 Qualcomm Linux 中启用 SOTA 发行版特性，请运行以下构建命令：

kas build meta-qcom/ci/rb3gen2-core-kit.yml:meta-qcom/ci/qcom-distro-sota.yml

此命令会自动为您的构建配置并启用 SOTA 发行版特性。

​

后续步骤

使用配方处理树外内核模块和设备树：

• 要构建树外内核模块，请参阅添加内核模块。注意 Qualcomm Linux 仅在 custom 变体中支持内核外设备树覆盖。
• 有关设备树/设备树 blob 管理，请参阅平台设备树中的内核 DTB 构建支持。