Fwupd 韌體更新整合手冊

版本：1.0.2
上次更新日期：2025-03-12

重點摘要

本文旨在逐步說明供應商如何為未來專案實作 fwupd。其中也包含直接引用自 LVFS 維護者的洞察資料。Fwupd 是開放原始碼韌體更新架構，可協助我們集中執行與外部供應商合作的韌體更新方式。

第一步：收集資訊並提供指引

供應商：首先請問：

  • 關於可更新元件的相關問題

    • 更新大小

    • 更新時間

    • 現有更新類型 (A/B 或 Bootloader/執行階段模型)

    • 更新期間元件的功能會發生什麼情況？

    • 系統必須發生什麼事，才能開始使用成功的更新？

    • 是否需要按照特定順序安裝多個元件？

  • 熟悉或具備 LVFS/fwupd 相關知識

  • 能夠提交工程資源，協助實作外掛程式 (詳情請見下文)

  • 承諾將外掛程式開放原始碼至 LGPLv2+ (將韌體寫入元件的程式碼)，並允許 LVFS 重新發布韌體

供應商 - 初步指南：

  • 更新必須盡量縮短周邊或內部元件功能受影響的時間，理想情況是幾秒鐘。更新作業的較長部分應在背景中自動執行，不會干擾使用者

    • 如果這項外接裝置明顯影響使用者體驗 (例如螢幕停止運作)，這項規定就會更加嚴格

  • 如要啟用這類靜默更新功能，強烈建議您使用 A/B 更新

    • 可在周邊裝置拔除時啟用的 A/B 更新，是盡量減少使用者中斷情況的理想做法

  • 更新必須可復原 - 如果您關閉電源、拔除周邊裝置等，更新作業不應導致裝置或周邊裝置變成磚塊。應能以穩健的方式，在無須使用者操作的情況下復原。

    • 初步假設應為在整個更新期間沒有使用者動作，且更新的適當指令碼和階段應由系統自動執行

第二步驟：使用 fwupd

如果廠商從未使用 fwupd

  • ChromeOS 會透過 fwupd 向原始設備製造商 (OEM) 提供韌體更新需求。OEM 應直接向晶片 / 元件供應商提供這項資訊

  • 在某些情況下，ODM 可以協助 OEM 直接與晶片供應商互動。原始設備製造商 (OEM) 有責任根據這些規定傳達相關資訊

  • 請注意，如果提供的來源程式碼採用 LGPLv2+ 授權，則通常無法從這個程式碼衍生外掛程式 (因為有許多複雜之處)。因此，在這種情況下，晶片供應商必須有可與 fwupd 維護人員和 Google 工程師合作的人員。

  • 原始設備製造商可以主動出擊，協助晶片供應商承諾與維護人員密切合作。供應商端工程支援服務的要求如下：

    • 非常熟悉可更新硬體元件的特殊功能和設計功能，最好是與撰寫韌體的團隊同事

    • 瞭解常見的開放原始碼授權 (例如 LGPLv2 和 MIT) 之間的差異

    • 精通 C，並具備 GLib 和 GObject 的基本知識，特別是瞭解 GErrors

    • 擁有 GitHub 帳戶，並瞭解如何開啟及更新提取要求、進行 GitHub 程式碼審查，以及瞭解 fwupd 如何透過 fwupd 提供的所有輔助程式進行結構化 (例如分割、附加/卸除、裝置重試、HID 等)

    • 選用：能夠將硬體樣本傳送至英國 - 這對 fwupd 維護者來說非常實用，可協助供應商偵錯問題，並將主機板新增至每次發布時執行的 fwupd 測試。後者對於停止開發分支中的迴歸情形非常重要。

  • 與此同時，原始設備製造商 (OEM) 可以透過 fwupd 郵寄清單或直接與 Richard Hughes (hughsient@gmail.com) 互動，並在編寫外掛程式碼前查看計畫。

  • 如果貴公司規模較小，工程資源或開放原始碼知識不足，不妨參考以下建議：

    • 元件供應商可以使用熟悉開源工作的顧問公司 (這不會產生額外費用)

    • 雖然這項建議可協助擴大規模，但供應商自行執行這項作業的價值在於，工程師會熟悉相關程序，日後可輕鬆為新硬體新增 VID/PID。而且，您也可以更快速地關閉問題 / 問題，以便在硬體上進行偵錯

第三步驟 - 最後步驟

  • 最後，程式碼會重構為可審查的小型提交，並使用 fwupd 中的所有共用功能

  • 完成後，外掛程式會合併至上游

    • 上游使用的程式碼會與 ChromeOS 中的程式碼相同

    • 在 ChromeOS 以外使用的韌體更新二進位檔會分發至 LVFS

具體來說，在 ChromeOS 中：

  • 原始設備製造商必須透過 CPFE 將韌體二進位檔上傳至我們的伺服器

  • 硬體回歸測試才能運作，仍需要在 LVFS 上提供可重新發布的更新櫃檔案

第四步 (選用) - 新增元件

  • 如果 fwupd 架構已就位，唯一的額外步驟就是更新元件供應商必須處理拉取要求，為硬體變化版本新增怪癖和 VID/PID。

其他指南 - 處理 LVFS

  • 建立新的供應商帳戶 (設定時間約 2 分鐘)

  • 供應商會為自己的網域建立使用者，或使用 Azure AD 之類的工具，將使用者帳戶同步處理至 LVFS。他們可以免費將韌體上傳至私人和供應商禁運的環境，且只需進行少量檢查 (因此工程師通常會從一開始就這麼做)

  • 最終將應用程式推送至測試或穩定版時，需要法律部門提供某種文件，清楚說明 LVFS 可以重新發布及分析韌體。理查提供的 PDF 指南。● 如果供應商只是晶片供應商或 ODM，則可成為 OEM 的「聯盟成員」，並代表對方上傳韌體，讓 OEM 能全面掌握其品牌韌體的相關情況。

  • 還有許多其他設定項目 (例如供應商 ID 會將其限制為一組 PCI 或 USB ID)，但大多數供應商都已指派 ID，因此只需 20 秒即可完成設定。

其他指南 - Chrome OS 專屬資訊

  • 在本例中，韌體更新二進位檔並未直接從 LVFS 提取。而是將 CAB 檔案儲存在本機檔案系統 (rootfs) 中

    • 未來工作流程：在適當的 portage 重疊項目上建立 portage ebuild，將韌體二進位檔納入 DLC

  • fwupd 需要在適當時間叫用 (透過其 CLI fwupdtool)。針對每個可更新的元件，您必須建立 udev 規則 (或等效指令碼)，以便發出 fwuptool-update 啟動事件。系統會自動處理這項事件，以便使用正確的引數和適當的沙箱機制 (minijail) 執行 fwupdtool

  • 另一個元件會決定是否需要使用者介面，但只有在特定情況下才會根據更新的元件性質決定。由 PM 和工程團隊評估。如同第一步所述，較高層級的指導方針是盡量減少使用者端的操作

供應商的額外資源

  • 外部說明文件參考資料：https://lvfs.readthedocs.io/

  • 外部廠商協議參考資料：fwupd.org/lvfs/docs/agreement

  • 開發外掛程式教學課程：https://fwupd.github.io/tutorial.html

  • 外掛程式偵錯教學：https://lvfs.readthedocs.io/en/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 首次發布