Fwupd Firmware Updates Integration Handbook

Version: 1.0.2
Zuletzt aktualisiert: 12. März 2025

Zusammenfassung

In diesem Dokument wird beschrieben, wie Anbieter fwupd für zukünftige Projekte implementieren können. Es enthält auch direkt von LVFS-Verantwortlichen zitierte Informationen. Fwupd ist ein Open-Source-Framework für Firmwareupdates, mit dem wir Firmwareupdates in Zusammenarbeit mit externen Anbietern zentralisieren können.

Erster Schritt: Informationen erfassen und Ratschläge geben

Für Anbieter: Stellen Sie zuerst folgende Fragen:

  • Fragen zu aktualisierbaren Komponenten

    • Größe des Updates

    • Aktualisierungszeit

    • Vorhandener Updatetyp (A/B- oder Bootloader-/Laufzeitmodell)

    • Was passiert mit der Funktionalität der Komponente während eines Updates?

    • Was muss mit dem System geschehen, damit ein erfolgreiches Update verwendet werden kann?

    • Müssen mehrere Komponenten in einer bestimmten Reihenfolge installiert werden?

  • Erfahrung mit LVFS/fwupd oder Kenntnisse darüber

  • Möglichkeit, englischsprachige Ressourcen für die Implementierung des Plug-ins zuzuweisen (weitere Informationen finden Sie unten)

  • Verpflichtung zur Open-Sourcing-Veröffentlichung des Plug-ins unter der LGPLv2+ (Code, der die Firmware in die Komponente schreibt) und zur Freigabe der Firmware für die weitere Bereitstellung über LVFS

Für Anbieter – Erste Informationen:

  • Durch das Update muss die Zeit, in der die Funktionalität der Peripheriegeräte oder internen Komponenten beeinträchtigt ist, minimiert werden, idealerweise auf wenige Sekunden. Der längere Teil des Updates sollte im Hintergrund ausgeführt werden, ohne den Nutzer zu stören.

    • Wenn sich dieses Peripheriegerät auf die Nutzerfreundlichkeit auswirkt (z. B. wenn das Display nicht mehr funktioniert), wird diese Anforderung noch strenger.

  • Um diese Art der stillen Aktualisierung zu ermöglichen, werden A/B-Tests dringend empfohlen.

    • A/B-Updates, die beim Trennen von Peripheriegeräten aktiviert werden können, sind ideal, um Unterbrechungen für Nutzer zu minimieren.

  • Das Update muss wiederhergestellt werden können. Wenn Sie das Gerät ausschalten oder das Peripheriegerät trennen, darf das Update das Gerät oder das Peripheriegerät nicht unbrauchbar machen. Sie sollte robust genug sein, um ohne Nutzeraktion wiederhergestellt zu werden.

    • Die anfängliche Annahme sollte sein, dass während des gesamten Updates keine Nutzeraktion erforderlich ist. Die entsprechenden Scripts und Aktualisierungsphasen sollten autonom ausgeführt werden.

Zweiter Schritt – fwupd verwenden

Wenn ein Anbieter noch nie fwupd verwendet hat

  • ChromeOS stellt OEMs Anforderungen an Firmwareupdates über fwupd zur Verfügung. Der OEM sollte dies direkt an die Chip-/Komponentenlieferanten weitergeben.

  • In einigen Fällen kann der ODM dem OEM helfen, direkt mit Chipanbietern zu kommunizieren. Es liegt in der Verantwortung des OEM, diese Anforderungen entsprechend weiterzuleiten.

  • Wenn Sie Quellcode mit der LGPLv2+-Lizenz zur Verfügung stellen, ist es in der Regel nicht möglich, das Plug-in aus diesem Code abzuleiten (aufgrund vieler Komplexitäten). In diesem Fall muss der Chipanbieter also jemanden haben, der mit den fwupd-Verantwortlichen und den Google-Entwicklern zusammenarbeiten kann.

  • Der OEM kann proaktiv vorgehen und die Chipanbieter dazu bewegen, eng mit den Maintainern zusammenzuarbeiten. Für die Anfrage an den technischen Support des Anbieters gelten die folgenden Anforderungen:

    • Sehr vertraut mit den Besonderheiten und Designmerkmalen der aktualisierbaren Hardwarekomponente, vorzugsweise im selben Team wie die Entwickler der Firmware

    • Unterschiede zwischen gängigen Open-Source-Lizenzen (z.B. LGPLv2 und MIT)

    • Sie sollten C-Programmierkenntnisse haben und grundlegende Kenntnisse zu GLib und GObject haben, insbesondere zu GErrors.

    • Sie haben ein GitHub-Konto und wissen, wie Sie einen Pull-Request öffnen und aktualisieren, GitHub-Codeüberprüfungen durchführen und wie fwupd mit allen von fwupd bereitgestellten Hilfsmitteln strukturiert ist (z. B. Chunking, Anhängen/Trennen, Gerätewiederholungen, HID usw.).

    • Optional: Möglichkeit, Hardwaremuster in das Vereinigte Königreich zu senden – sehr nützlich für fwupd-Maintainer, um dem Anbieter bei der Fehlerbehebung zu helfen und das Board den fwupd-Tests hinzuzufügen, die bei jeder Veröffentlichung ausgeführt werden. Letzteres ist wichtig, um Regressionen im Entwicklungszweig zu verhindern.

  • Parallel dazu kann der OEM über die fwupd-Mailingliste oder direkt mit Richard Hughes (hughsient@gmail.com) Kontakt aufnehmen und den Plan besprechen, bevor der Plug-in-Code geschrieben wird.

  • Wenn ein Unternehmen klein ist und nur wenige bis gar keine Entwicklungsressourcen oder Kenntnisse zu Open Source hat, kann der folgende Vorschlag hilfreich sein:

    • Der Komponentenanbieter könnte Beratungsunternehmen beauftragen, die mit Open-Source-Arbeit vertraut sind. Dies verursacht jedoch keine zusätzlichen Kosten.

    • Dieser Vorschlag kann zwar bei der Skalierung helfen, aber der Vorteil, wenn der Anbieter dies intern erledigt, besteht darin, dass die Entwickler mit dem Prozess vertraut werden und in Zukunft ganz einfach VID/PID für neue Hardware hinzufügen können. Außerdem können Fragen / Probleme, die auf der Hardware behoben werden müssen, schneller geschlossen werden.

Dritter Schritt – Letzte Schritte

  • Schließlich wird der Code mit allen freigegebenen Funktionen in fwupd in kleine überprüfbare Commits umstrukturiert.

  • Sobald das erledigt ist, wird das Plug-in mit dem Upstream-Code zusammengeführt.

    • Der Code, der vorgelagert verwendet wird, ist derselbe Code in ChromeOS.

    • Die außerhalb von ChromeOS verwendeten Firmware-Update-Binärdateien werden an LVFS verteilt.

Im Fall von ChromeOS gilt Folgendes:

  • Der OEM muss die Firmware-Binärdatei über CPFE auf unsere Server hochladen.

  • Im LVFS müssen weiterhin redistributierbare Update-Cabinet-Archive vorhanden sein, damit die Hardware-Regressionstests funktionieren.

Vierter Schritt (optional): Neue Komponenten hinzufügen

  • Wenn das fwupd-Framework bereits vorhanden ist, ist der einzige zusätzliche Schritt, dass der Anbieter der aktualisierbaren Komponente Pull-Requests bearbeiten muss, um Quirks und VID/PIDs für Hardwarevarianten hinzuzufügen.

Weitere Hinweise – Arbeit mit LVFS

  • Neues Anbieterkonto erstellen (Einrichtungszeit: ca. 2 Minuten)

  • Anbieter erstellen Nutzer für ihre eigene Domain oder verwenden z. B. Azure AD, um Nutzerkonten mit dem LVFS zu synchronisieren. Sie können Firmware kostenlos und mit nur wenigen Prüfungen in ein privates und Embargos des Anbieters hochladen. Daher tun dies oft die Entwickler von Anfang an.

  • Für die Freigabe von Firmware für die Test- oder Stable-Version ist eine Art Dokument von der Rechtsabteilung erforderlich, aus dem klar hervorgeht, dass das LVFS die Firmware weitergeben und analysieren darf. Die PDF-Richtlinie wird von Richard bereitgestellt. ● Wenn der Anbieter nur ein Siliziumlieferant oder ein ODM ist, kann er „Affiliate“ des OEMs werden und Firmware in seinem Namen hochladen. Der OEM hat dann volle Transparenz darüber, was mit der Firmware passiert, die mit seinem Namen gekennzeichnet ist.

  • Es gibt noch viele andere Dinge, die eingerichtet werden müssen (z.B. schränkt die Anbieter-ID sie auf eine Reihe von PCI- oder USB-IDs ein), aber die meisten Anbieter haben bereits eine zugewiesene ID und die Einrichtung dauert 20 Sekunden.

Weitere Informationen – ChromeOS-spezifische Informationen

  • In unserem Fall werden Firmwareupdate-Binärdateien nicht direkt aus dem LVFS abgerufen. Stattdessen wird die CAB-Datei im lokalen Dateisystem (rootfs) gespeichert.

    • Zukünftiger Arbeitsstream: Firmware-Binary in DLC einbinden, indem ein Portage-Ebuild auf dem entsprechenden Portage-Overlay erstellt wird

  • fwupd muss zum richtigen Zeitpunkt über die Befehlszeile fwupdtool aufgerufen werden. Für jede aktualisierbare Komponente muss eine udev-Regel (oder ein entsprechendes Script) erstellt werden, die ein Upstart-Ereignis vom Typ „fwuptool-update“ auslöst. Dieses Ereignis wird automatisch verarbeitet, um fwupdtool mit den richtigen Argumenten und der richtigen Sandbox (Minijail) auszuführen.

  • Eine weitere Komponente ist die Entscheidung, ob eine Benutzeroberfläche erforderlich ist. Dies ist nur unter bestimmten Umständen und je nach Art der aktualisierten Komponente der Fall. Wird vom PM- und Engineering-Team bewertet. Wie bereits im ersten Schritt erwähnt, besteht die allgemeine Empfehlung darin, die Aktionen auf Nutzerseite zu minimieren.

Zusätzliche Ressourcen für Anbieter

  • Externe Dokumentation: https://lvfs.readthedocs.io/

  • Referenz zu externen Anbietervereinbarungen: fwupd.org/lvfs/docs/agreement

  • Anleitung zum Entwickeln von Plug-ins: https://fwupd.github.io/tutorial.html

  • Anleitung zum Debuggen von Plug-ins: https://lvfs.readthedocs.io/en/latest/custom-plugin.html

  • Beispiel für eine Quirk-Datei: https://github.com/fwupd/fwupd/blob/master/plugins/wacom-usb/wacom-usb.quirk

Überarbeitungsverlauf

Datum Version Hinweise
2025-03-12 1.0.2 Text aus einer PDF-Datei in Markdown konvertieren
2024-01-31 1.0.1 Neue Veröffentlichung auf der neuen Plattform
2023-10-12 1.0 Erstveröffentlichung