通过 fwupd 更新外设固件

版本：2.4.2
最后更新时间：2024 年 10 月 18 日

概览

本指南旨在介绍如何配置 ChromeOS 界面支持的后续固件更新。

fwupd 流程图

背景

fwupd 是一个开源守护程序，可在基于 Linux 的系统上执行外围设备和其他系统固件更新。fwupd 是 ChromeOS 更新外围设备固件的机制。

fwupd 更新载荷由存储在 Linux 供应商固件服务 (LVFS) 中的 .cab 文件组成。在 Linux 中，fwupd 更新上传到 LVFS 后，即可广泛提供。不过，为了在 ChromeOS 中提供更新，ChromeOS 团队会单独验证新的更新并将其列入许可名单，以确保提供最佳用户体验。

fwupd 进程

以下内容仅适用于样本已发送到 Allion 且通过 WWCB 认证的外围设备。

如果 ChromeOS 中的当前 fwupd 版本尚不支持该外围设备，请按照用例 1 和用例 2 中的说明操作。如果 ChromeOS 中当前版本的 fwupd 已经支持外设，请跳至用例 2。

用例 1：ChromeOS 当前版本的 fwupd 不支持外围设备

ChromeOS 中的 fwupd 当前版本尚不支持该外围设备。

图片

  1. ODM 和 OEM 可以直接与芯片组供应商合作，将插件更改提交到 fwupd 代码库。

    1. 请参阅 fwupd 集成手册（第二步 - 使用 fwupd）。
    2. 插件更改：示例 1、示例 2
    3. 匹配 .quirk 文件中的 VIDs:PIDs：示例 3
      • 作为 quirk 文件更改的替代方案，如果现有插件支持 USB 外围设备，则可以遵循 DS20 规范。
    4. 让 fwupd 的 maintainers 合并生成的插件和 Quirk 更改。
    5. 等待 fwupd（即1.8.4），记下版本。

  2. 后续版本会定期镜像到 ChromeOS，并且会遵循 Chromium 发布时间表。

  3. 如果您在即将发布的 Chromium 版本的功能冻结截止日期之后提交插件更改、bug 修复或 quirk 文件更改，但这些更改对下一个 ChromeOS 版本而言是高优先级的，则：

    1. 前往合作伙伴问题跟踪器。
    2. 使用您的 Google 合作伙伴网域账号登录。

    3. 点击左侧菜单中的 Create Issue（创建问题）按钮，即可在您的组件 (ChromeOS > External > WWCB > PERIPHERAL OEM > fwupd) 中创建 bug。这样会提醒 ChromeOS 团队升级 ChromeOS 中的后续版本。

      在 bug 中提供以下信息：

      1. bug 标题：

        [PRODUCT NAME - fwupd]: New Plugin NAME OF THE PLUGIN requires fwupd X.Y.Z version uprev

      2. bug 说明：

        1. fwupd 版本号，包含插件更改：
          • 它添加了哪些功能？
          • 修复了哪些 bug？
          • 它支持哪些硬件？
        2. 设备的品牌/型号
        3. VID、PID
        4. GUID（全局唯一标识符）

      3. 屏幕截图示例：

        fwupd uprev 错误的屏幕截图

  4. 我们会对该 bug 进行分类，并将选择的 fwupd 版本纳入到 Google 工程师的 ChromeOS 映像测试中。

  5. 然后，系统会将该 bug 分配给 chromeOS 中符合条件的升级版本 fwupd，从而确保升级不会破坏 fwupd。

    • 测试团队将选择 5 款产品，并使用 ChromeOS 的测试映像（包含升级后的升级许可）升级/降级固件。

  6. 验证结果将在 bug 中提供。

    • 如果由于升级过程中发现错误，导致验证失败，我们会将该错误重新分配给 Google 工程师。

  7. 测试完成后，随着更改列表获得批准，更新后的 fwupd 版本将被提升到 Canary 渠道。

    • 请就 bug 发表评论，了解 ChromeOS 的哪个 build 版本包含升级后的 fwupd 版本。您还可以使用 CL Finder 在 ChromeOS 合作伙伴控制台 (CPCon) 中搜索 build 版本（需要 Google 公司合作伙伴网域账号，如需访问 CPCon，请与 TAM 联系）。

应用场景 2：ChromeOS 的当前版本 fwupd 支持外围设备

ChromeOS 中当前版本的 fwupd 已支持外围设备，并且有可用的新固件。

图片

  1. 创建 .cab 文件。

    所有固件均以机柜归档文件的形式上传。除了固件二进制文件之外，LVFS 要求归档至少包含一个描述目标设备和固件的 .metainfo.xml 文件。您可以在 Linux 上使用 gcab（用于创建压缩包文件的库）创建压缩包归档。

  2. 将经过测试的最终固件更新（.cab 文件）上传到 LVFS。

    1. 确保稳定版遥控器上有可用更新。

      如果该版本在私享、禁售或测试远程位置上可用，则不会添加到 ChromeOS 镜像中。

    2. 通过签名报告在 LVFS 中标记为已验证的更新。

      确保添加了设备测试。

    3. 如果这是首次上传固件，请确保 LVFS 的稳定远程中至少有 2 个固件，即基础固件（用于测试降级）和新固件（用于测试升级）。

  3. 固件升级应通过签名报告在 ChromeOS 上进行测试。

    1. 将证书上传到 LVFS，以将 DUT 与您的账号相关联。

      1. 使用您的账号登录 LVFS。
      2. 点击右上角的“用户”图标，或点击 https://fwupd.org/lvfs/profile{:.external}。
      3. 点击玩家资料设置。

      4. 在 Chromebook 上找到客户端证书。

        • 注意：Chromebook 必须处于开发者模式
        • 按 ctrl + alt + t 启动 ChromeOS 开发者 shell

        • Type:

          shell

        • 前往 /var/lib/fwupd/pki：

          cd /var/lib/fwupd/pki

        • 将 client.pem 复制到 Chromebook 上的某个文件夹中，例如：Downloads。

          cp client.pm /home/chronos/user/MyFiles/Downloads/

    2. 在 LVFS 网站的客户端证书部分中，点击上传证书按钮，然后上传证书。

      1. 在要用于测试的每台 Chromebook 上重复这些步骤（您可以为不同的计算机上传多个证书）。

    3. 通过 DUT 测试升级并上传已签名的报告。

      1. 如需测试和上传报告，请运行以下命令并在出现提示时进行身份验证。

        fwupdmgr refresh
fwupdmgr update
fwupdmgr report-history --sign

      2. 注意：如果您已上传不带 --sign 标志的报告，则可以使用 fwupdmgr report-history --sign --force 将同一报告重新上传到 LVFS。

        fwupdmgr report-history --sign --force

        • 您可以传递 --verbose 以查看服务器响应。

          fwupdmgr report-history --force --verbose

      3. 在确认对话框中，点击是。

        • 这会将已签名的报告上传到您的账号中。
        • 如需确认，请前往 https://fwupd.org/lvfs/dashboard，然后点击左上角首页部分下的已签名报告。

    4. 验证 LVFS 上的固件版本是否具有签名报告

      • 在 LVFS 上搜索外围设备。
      • 如果上传的已签名报告是在使用 Chromebook 成功升级外围设备上的固件版本后生成的，则 Tested By 部分将显示 ChromeOS 版本、fwupd 版本和实体。请参阅示例。
      • 确保发布限制显示绿色对勾标记“可供 ChromeOS 用户使用”。

    5. 从 M126 开始，只有当固件在 LVFS 上具有已签名报告（已通过 ChromeOS 测试）时，ChromeOS 用户才能获得固件更新。

      • 24 小时后，用户便可以将外围设备连接到 Chromebook，并通过 ChromeOS 界面升级固件。依次前往设置 > 关于 ChromeOS > 固件更新。
      • 注意：假设 ChromeOS 在给定里程碑中提供了所有必需的插件更改，则固件更新将可用。

如需详细了解已签名报告，请参阅 LVFS。

常见问题解答

问：哪些 Chromebook 支持 fwupd？

所有搭载 M101 或更高版本的 ChromeOS 设备。

问题：如何查找与 ChromeOS 集成的 fwupd 版本？

  1. 通过浏览器（M109 或更高版本）打开 chrome://system。
    1. 导航到 fwupd_version。
  2. 或者通过开发者模式、根控制台、
    1. 类型 fwupdmgr --version
    2. 寻找runtime org.freedesktop.fwupd

问：升级升级流程需要多长时间？

fwupd uprev 遵循 Chromium 发布时间表，确保在分支功能冻结截止日期之前提交 fwupd uprev 请求。

问题：在哪里可以详细了解 ChromeOS 发布时间表？

Chromium 发布时间表中。

问：如何将 Chromebook 切换到开发者模式？

  1. 关闭 Chromebook。
  2. 按住 Esc + Refresh，然后按电源按钮。
    • 注意：在某些 Chromebook 上，您需要按 esc+→（向右键）然后按电源按钮。
  3. 设备开机后，您应该会看到“恢复屏幕 / 模式”。
  4. 然后按 ctrl + d 键，再按 Enter 键接受。
    • 注意：如果您在按 Ctrl+d 之前按了任何其他键，设备将不会转换到开发者模式。
  5. 设备将重新启动并发出哔哔声，您会看到“系统正在过渡到开发者模式”。
  6. 大约 30 秒后，您会看到“正在为开发者模式准备系统”。
  7. 最终（可能需要 10 分钟到 1 小时以上，具体取决于磁盘大小），设备将重新启动到常规欢迎屏幕。
  8. 按 ctrl + alt + →（向右箭头键），获取命令提示符。
    • 注意：在某些 Chromebook 上，按 Ctrl+alt+refresh 键。
    • 如需返回浏览器视图，请按 Ctrl+Alt+←（向左键）。
  9. 如需了解更多详情，请访问 [开发者模式]

问：如何将 Chromebook 切换到正常模式（即停用开发者模式）？

重启设备，然后在固件屏幕上按空格键。

如需了解详情，请参阅“开发者模式”。

问题：ChromeOS 是否支持通过 fwupd 降级？

不可以。如果 fwupd 的正式版或固件发生故障，您必须通过 https://fwupd.org/lvfs/dashboard 删除已签名的报告。每当您提交插件更改和/或有新固件可用时，请务必进行测试。确保 LVFS 的稳定远程设备上始终提供固件的基准版本。

问题：如何了解哪些版本的 ChromeOS 将支持哪些 fwupd 更新？

您可以在 bug 中留言，询问更改已纳入哪个 build 版本，Google 工程师应该能够为您提供相关信息。您还可以使用 CL Finder 在 ChromeOS 合作伙伴控制台 (CPCon) 中搜索 build 版本（需要 Google 公司合作伙伴网域账号 - 请与 TAM 联系以访问 CPCon）。我们可能会交叉参考 ChromeOS 配对设备的操作界面 (CPFE) 上的 build 版本，看看它对应于哪个里程碑。

问：如何创建 LVFS 账号？

请参阅获取账号 LVFS 文档。

问：如何将出租车文件上传到 LVFS？

请参阅 Uploading Firmware LVFS 文档。

问题：如何确保固件适用于特定外围设备？

这可通过最众所周知的配置文件来实现。如需了解详情，请参阅 fwupd 最佳已知配置。

问：如何在上传到 LVFS 之前测试后续更新？

提交插件更改并将选择的 fwupd 版本纳入 ChromeOS 测试映像后，您就可以通过 ChromeOS 合作伙伴前端 (CPFE) 访问测试映像（需要 Google 公司合作伙伴网域账号 - 请与 TAM 联系以访问 CPFE）。

请参阅 LVFS 文档 ChromeOS 上的固件测试。 或者，您也可以使用 Moblab 运行后续测试。

问：系统如何通知用户有外围设备固件更新可用？

系统会根据 LVFS 中为更新分配的紧急程度，向用户发送更新可用通知。行为如下：

紧迫感 通知行为
低 用户不会收到通知，必须手动检查更新。
中
高
严重 在更新完成之前，系统会在每次启动时显示通知。

问：fwupd 更新是否会自动进行？

不会。所有后续更新都由用户启动，不会在启动过程中发生，也不会自动发生。

问：DS20 规范的优势是什么？

目前仅针对 USB 外围设备进行验证，如果您使用在其他硬件上使用过的相同协议，则只能使用 DS20 描述符。

供应商可以将 quirk 文件数据放入 USB 描述符，而不是放入 fwupd 项目。这样，插入 USB 设备后，fwupd 会读取描述符数据、匹配插件，并枚举设备，而无需让供应商向 fwupd 提交补丁并等待 fwupd 升级。

问题：DS20 是否是仅限文件更改的 Quirk 的替代方案？

可以；大多数情况下，未来的硬件只需将 VID&PID 添加到现有插件中，而无需进行实际代码更改。如果需要更改代码，供应商必须将插件更改提交给 fwupd。

附录

  1. 开发者指南
  2. 开发者支持
  3. 面向 CrOS 贡献者的 Git 和 Gerrit 简介
  4. 更改源代码
  5. Gerrit 审核/审批流程
  6. fwupd 集成手册

修订历史记录

日期 版本 备注
2024-10-18 2.4.2 更新了后续工作流程图片和上传客户端证书的步骤
2024-07-23 2.4.1 格式更新。
2024-06-26 2.4 更新了升级升级工作流（用例 1）。（与 2.4.1 一起发布）
2024-06-17 2.3 更新了已签名报告的工作流程。（与 2.4.1 一起发布）
2024-02-01 2.2 在新平台上重新发布；更新了少量措辞。
2023-10-12 2.1 在案例 1 和案例 2 中添加了图片，合作伙伴网站中托管的后续集成手册
2022-08-14 2.0 初始合作伙伴网站发布