> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 处理 capsule

设备上的固件通过 UEFI 使用 capsule 进行更新。此过程将固件更新负载封装在 capsule \[.cap 文件] 中，然后由系统固件对其进行处理以更新设备固件。

<Note>
  上述 capsule 更新仅适用于 Qualcomm Linux 高级（advanced）和基础（base）变体。
</Note>

## **capsule 更新中使用的 UEFI 变量**

与平台固件交互的协议和服务实现了操作系统与 UEFI 之间的通信。UEFI 提供标准启动环境、包含平台信息的数据表，以及供操作系统加载程序和操作系统使用的启动/运行时服务调用。

<Frame caption="**表：capsule 更新中使用的 UEFI 变量**" />

| 变量名称                                        | 描述                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OsIndications**                           | 该变量由操作系统拥有，用于指示操作系统希望固件启用的功能或希望固件执行的操作。操作系统设置该变量，UEFI 将其清除。                                                                                                                                                                                                                                                                                           |
| **OsIndicationsSupported**                  | 该变量由固件拥有，指示固件支持哪些操作系统指示功能和操作。                                                                                                                                                                                                                                                                                                                         |
| **OsTrialBootStatus**<br />*（32 位 UEFI 变量）* | **位图：**<br /><br />• **7:0 – Version**：`OsTrialBootStatus` 的版本号<br />• **11:8 – TrialBootMaxCount**：由操作系统在触发 capsule 更新之前设置<br />• **15:12 – TrialBootCount**：由 UEFI 设置或递增（如果操作系统未清除 `TrialBootEnabled`）。操作系统可将其设置为 `TrialBootMaxCount` 以触发固件回滚<br />• **16 – TrialBootEnabled**：capsule 更新后由 UEFI 设置为 `1`，并在 OTA 更新成功后由操作系统清除<br />• **31:17 – 未使用** |
| **EFI 系统资源表（ESRT）**                         | ESRT 表在 capsule 更新后由 UEFI 设置。                                                                                                                                                                                                                                                                                                                         |

有关 OsIndications 和 OsIndicationsSupported 变量的更多信息，请参阅[操作系统与固件之间的信息交换](https://uefi.org/specs/UEFI/2.10/08_Services_Runtime_Services.html?highlight=osindications#exchanging-information-between-the-os-and-firmware)。

<Note>
  * 如果 ESP 分区（EFI/UpdateCapsule 中）中有多个 capsule，则将所有 capsule 纳入更新范围，并按字母顺序进行更新。
  * 将所有 UEFI 非易失性变量存储在回滚保护内存块（RPMB）分区中，该分区必须处于已预配（Provisioned）状态。
    * 在启用了 Qualcomm 安全启动的设备上自动预配 RPMB。
    * 在 Qualcomm 非安全设备上，不自动预配 RPMB；而是使用测试密钥进行预配。
    * 如果在非安全设备上使用测试密钥预配了 RPMB，则在为设备启用 Qualcomm 安全启动时，无法使用设备密钥重新预配 RPMB。
    * 从 Linux 使用 `rpmbClient` 应用程序进行 RPMB 预配。有关详细信息，请参阅 [Qualcomm 安全 Linux 指南](https://dragonwingdocs.qualcomm.com/System/Security/verify-the-security-configurations-of-qualcomm-linux)。
</Note>

## **用于 capsule 更新状态的 EFI 系统资源表（ESRT）**

ESRT 是一种可选机制，用于标识用于提供固件更新的设备和系统固件资源。每个 ESRT 条目描述一个可更新的固件资源，并报告上次尝试更新的状态。下表列出了用于报告上次尝试更新状态的 ESRT 条目：

<Frame caption="**表：ESRT 条目**" />

| **ESRT 字段**              | **描述**                                                                 |
| ------------------------ | ---------------------------------------------------------------------- |
| FwClass                  | 包含一个 GUID，用于标识通过 *UpdateCapsule()* 更新的固件组件。                            |
| FwType                   | 标识固件资源的类型。                                                             |
| FwVersion                | 表示固件资源的当前版本。该值必须始终递增，数值越大表示版本越新。                                       |
| LowestSupportedFwVersion | 指定系统或设备可回滚到的最低固件资源版本。                                                  |
| CapsuleFlags             | 包含 capsule 头中设置的 *EFI\_CAPSULE\_HEADER* 中定义的 *CapsuleGuid* 标志（位 0-15）。 |
| LastAttemptVersion       | 指示系统上次尝试更新的固件版本（使用与固件版本相同的格式）。                                         |
| LastAttemptStatus        | 描述该固件资源条目上次固件更新尝试的结果。                                                  |

操作系统通过 sysfs 路径公开 ESRT 内容。

```text theme={null}
/sys/firmware/efi/esrt/entries/entry0/
sh-5.1# cd /sys/firmware/efi/esrt/entries/entry0/
sh-5.1# ls
capsule_flags  fw_type     last_attempt_status   lowest_supported_fw_version
w_class       fw_version  last_attempt_version
```

UEFI 在 capsule 更新后设置 ESRT 表。X 表示 capsule 更新前的固件版本。Y 是 capsule \[.cap] 文件中包含的固件版本。

<Note>
  只有在 RPMB 已预配的情况下才能获取上次尝试的固件版本。
</Note>

| **上次尝试的固件版本** | **当前固件版本** | **last\_attempt\_status** | **capsule 更新场景** |
| ------------- | ---------- | ------------------------- | ---------------- |
| Y             | Y          | 0                         | 更新成功             |
| Y             | X          | 1                         | capsule 更新失败     |
| 0             | X          | 0                         | capsule 元数据失败    |
| Y             | X          | 0                         | 已完成固件回滚          |

有关 ESRT 的更多信息，请参阅[固件更新和报告 - UEFI 规范 2.10 文档](https://uefi.org/specs/UEFI/2.10/23_Firmware_Update_and_Reporting.html#efi-system-resource-table)。

## **使用 Capsule 进行固件更新**

流程图展示了如何使用 UEFI capsule 方法更新设备固件，利用不同的 UEFI 变量并支持回滚。

<div style={{ textAlign: 'center', width: '100%' }}>
  <img src="https://mintcdn.com/qualcomm-prod/eYaEBFH0xlFq53OY/System/Boot/media/k2c-qli-boot/capsule-flowchart.svg?fit=max&auto=format&n=eYaEBFH0xlFq53OY&q=85&s=d0b38a10300beb9d381b22b53e030cfa" alt="Capsule 流程图" style={{ display: 'block', margin: '0 auto' }} width="879" height="1014" data-path="System/Boot/media/k2c-qli-boot/capsule-flowchart.svg" />
</div>

1. **启动**：空中下载（OTA）更新过程开始，操作系统准备更新 capsule，（通过设置 `OsIndications`）向 UEFI 发出开始更新的信号。操作系统设置 `TrialBootMaxCount` 以跟踪允许的试启动次数，然后重启设备。
2. **UEFI 更新**：重启后，系统检查 `OsIndications`。如果存在，则执行 capsule 更新，更新 EFI 系统资源表（ESRT），清除 `OsIndications`；如果设置了 `TrialBootMaxCount`，则启用 `TrialBootEnabled` 并再次重启系统。
3. **试启动处理**：
   * 如果未设置 `OsIndications`，系统检查 `TrialBootEnabled` 是否处于激活状态。
   * 如果 `TrialBootEnabled` 处于激活状态且 `TrialBootCount` 等于 `TrialBootMaxCount`，则检查回滚计数。
     * 如果允许回滚，UEFI 将恢复固件、更新 ESRT 并重启。
     * 如果不允许回滚，则表示已达到回滚上限。
   * 如果 `TrialBootCount` 小于 `TrialBootMaxCount`，则递增 `TrialBootCount` 并继续该流程。
4. **完成**：系统启动到操作系统，检查 ESRT，如果操作系统成功启动，则重置 `TrialBootEnabled` 字段。
5. **结果**：
   * 如果 `TrialBootEnabled` 未激活，则确认 OTA 更新已完成。
   * 系统清除 `OtaTrialBootStatus`，并将 `LwSupportedFwVersion` 设置为当前固件版本以禁用回滚。
6. **恢复**：如果固件 capsule 更新在更新过程中失败，UEFI 具有恢复机制以保持稳定性和功能性。
   1. **回滚**：如果允许回滚，UEFI 将恢复到以前的固件版本，并将固件还原到更新尝试之前的状态。
   2. **ESRT 更新**：系统更新 ESRT 以反映回滚。
   3. **重启**：回滚完成后，UEFI 触发重启，以确保运行的是先前的稳定固件版本。此过程应用更新，并在试用期内出现问题时启用回滚。

身份验证对于在固件更新期间保持安全性和稳定性至关重要。它有助于实现以下目标：

* 确保系统仅应用来自受信任来源的更新。
* 防止恶意或未经授权的更新。
* 验证数字签名以确认传输过程中的完整性。
* 仅安装经过验证和测试的更新。
* 降低因固件故障导致系统崩溃或功能异常的风险。