Fwupd 固件更新集成手册

版本：1.0.2
上次更新日期：2025 年 3 月 12 日

要点

本文档旨在介绍供应商如何为未来的项目实现 fwupd。其中还包含直接引用自 LVFS 维护者的见解。Fwupd 是一个开源固件更新框架，可帮助我们集中管理与外部供应商合作进行固件更新的方式。

第 1 步 - 收集信息并提供指导

对于供应商 - 首先询问：

  • 关于可更新组件的问题

    • 更新大小

    • 更新时间

    • 现有更新类型（A/B 或引导加载程序/运行时模型）

    • 更新期间，组件的功能会发生什么变化？

    • 系统必须发生什么情况才能开始使用成功的更新？

    • 是否需要按特定顺序安装多个组件？

  • 熟悉或了解如何使用 LVFS/fwupd

  • 能够提交工程资源来帮助实现插件（如需了解详情，请参阅下文）

  • 承诺将插件开源为 LGPLv2+（将固件写入组件的代码），并允许通过 LVFS 重新分发固件

对于供应商 - 初始指南：

  • 更新必须最大限度地缩短外围设备或内部组件功能受到影响的时间，最好将其缩短到几秒钟。更新的较长部分应在后台静默进行，不会干扰用户

    • 如果此外围设备明显影响用户体验（例如显示屏停止工作），则此要求会更加严格

  • 如需启用此类静默更新，强烈建议使用 A/B 更新

    • 在拔下外围设备时启用的 A/B 更新非常适合尽可能减少对用户的干扰

  • 更新必须可恢复 - 如果您关闭电源、拔下外围设备的电源线等，更新不应导致设备或外围设备变砖。它应能够在无需用户操作的情况下进行可靠恢复。

    • 初始假设应为在整个更新期间没有用户操作，更新的适当脚本和阶段应自行驱动

第 2 步 - 使用 fwupd

如果供应商从未使用过 fwupd

  • ChromeOS 通过 fwupd 向 OEM 提供固件更新要求。OEM 应直接将此信息告知芯片 / 组件供应商

  • 在某些情况下，ODM 可以帮助 OEM 直接与芯片供应商对接。OEM 有责任相应地传达这些要求

  • 请注意，如果提供的源代码采用 LGPLv2+ 许可，通常无法从此代码派生插件（有很多复杂性）。因此，在这种情况下，芯片供应商需要有可以与 fwupd 维护者和 Google 工程师合作的人员。

  • OEM 可以主动帮助争取芯片供应商承诺与维护者密切合作。供应商端的工程支持请求需满足以下要求：

    • 非常熟悉可更新硬件组件的怪癖和设计特征，最好是属于编写固件的同一团队

    • 了解常见开源许可（例如 LGPLv2 和 MIT）之间的区别

    • 精通 C 语言，对 GLib 和 GObject 有基本的了解，并且特别了解 GError

    • 拥有 GitHub 账号，并了解如何打开和更新拉取请求、执行 GitHub 代码审核，以及了解 fwupd 的结构以及 fwupd 提供的所有帮助程序（例如分块、附加/分离、设备重试、HID 等）

    • 可选：能够将硬件样本发送到英国 - 这对 fwupd 维护人员来说非常有用，可帮助供应商调试问题，并将开发板添加到每个版本上运行的 fwupd 测试中。后者对于停止开发分支中的回归问题至关重要。

  • 与此同时，原始设备制造商 (OEM) 可以通过 fwupd 邮寄名单或直接与 Richard Hughes (hughsient@gmail.com) 联系，在编写插件代码之前讨论相关方案

  • 如果公司规模较小，没有或几乎没有工程资源，也不了解开源技术，则以下建议可能有所帮助：

    • 组件供应商可以使用熟悉开源工作的咨询公司（这不会产生额外费用）

    • 虽然此建议有助于扩展，但供应商自行执行此操作的好处在于，工程师会熟悉此流程，日后便可轻松为新硬件添加 VID/PID。您还可以更快地解决问题 / 问题，以便在硬件上进行调试

第 3 步 - 最后的步骤

  • 最终，代码会重构为可审核的小型提交，并使用 fwupd 中的所有共享功能

  • 完成后，该插件会合并到上游

    • 上游使用的代码与 ChromeOS 中的代码相同

    • 在 ChromeOS 之外使用的固件更新二进制文件将分发到 LVFS

具体而言，在 ChromeOS 设备上：

  • OEM 必须通过 CPFE 将固件二进制文件上传到我们的服务器

  • LVFS 上仍需要有可重新分发的更新柜架归档文件，才能运行硬件回归测试

第 4 步（可选）- 添加新组件

  • 如果 fwupd 框架已就绪，唯一的额外步骤是可更新组件供应商必须处理拉取请求，以便为硬件变体添加怪癖和 VID/PID

其他指南 - 处理 LVFS

  • 创建新的供应商账号（设置时间约为 2 分钟）

  • 供应商可以为自己的网域创建用户，也可以使用 Azure AD 等工具将用户账号同步到 LVFS。他们可以免费将固件上传到不公开和供应商禁售渠道，并且只需进行少量检查（因此，工程师通常会从一开始就执行此操作）

  • 最终，如果要推送到测试版或稳定版，则需要他们的法务部门提供某种文件，其中明确说明 LVFS 可以重新分发和分析固件。Richard 提供了 PDF 指南。● 如果供应商只是芯片供应商或 ODM，则可以成为 OEM 的“联属”并代表其上传固件，OEM 可以完全了解带有其品牌的固件的情况。

  • 还有很多其他设置（例如，供应商 ID 会将其限制为一组 PCI 或 USB ID），但大多数供应商已经分配了 ID，并且只需 20 秒即可完成设置。

其他指南 - ChromeOS 专用部分

  • 在我们的示例中，固件更新二进制文件不会直接从 LVFS 拉取。而是将 CAB 文件存储在本地文件系统 (rootfs) 中

    • 未来的工作流：通过在适当的移植叠加层上创建移植 ebuild，将固件二进制文件纳入 DLC

  • 需要在适当的时间调用 fwupd（通过其 CLI fwupdtool）。对于每个可更新的组件，都必须创建一个 udev 规则（或等效的脚本），以发出 fwuptool-update upstart 事件。系统会自动处理此事件，以使用正确的参数和适当的沙盒 (minijail) 执行 fwupdtool

  • 另一个组件用于确定是否需要界面，但只有在特定情况下才需要界面，具体取决于更新的组件的性质。将由 PM 和工程团队进行评估。如第一步中所述，更高级别的指导是尽可能减少用户端的操作

面向供应商的额外资源

  • 外部文档参考：https://lvfs.readthedocs.io/

  • 外部供应商协议参考：fwupd.org/lvfs/docs/agreement

  • 开发插件教程：https://fwupd.github.io/tutorial.html

  • 调试插件教程：https://lvfs.readthedocs.io/zh-CN/latest/custom-plugin.html

  • 奇怪行为文件示例： https://github.com/fwupd/fwupd/blob/master/plugins/wacom-usb/wacom-usb.quirk

修订历史记录

日期 版本 备注
2025-03-12 1.0.2 将 PDF 文本转换为 Markdown
2024-01-31 1.0.1 在新平台上重新发布
2023-10-12 1.0 初始发布