Versione: 1.0.2
Ultimo aggiornamento: 12/03/2025
TL;DR
Questo documento intende illustrare come i fornitori possono implementare fwupd per i progetti futuri. Sono incluse anche informazioni tratte direttamente dai manutentori di LVFS. Fwupd è un framework di aggiornamento del firmware open source che può contribuire a centralizzare il modo in cui eseguiamo gli aggiornamenti del firmware in collaborazione con fornitori esterni.
Primo passaggio: raccogliere informazioni e fornire indicazioni
Per i fornitori:
Domande sui componenti aggiornabili
Dimensioni aggiornamento
Ora di aggiornamento
Tipo di aggiornamento esistente (modello A/B o bootloader/runtime)
Cosa succede alla funzionalità del componente durante un aggiornamento?
Che cosa deve succedere al sistema per iniziare a utilizzare un aggiornamento riuscito?
È necessario installare più componenti in un ordine specifico?
Familiarità con l'utilizzo di LVFS/fwupd o conoscenza di questi strumenti
Possibilità di impegnare una risorsa di ingegneria per contribuire a implementare il plug-in (vedi di seguito per maggiori dettagli)
Impegno a rendere open source il plug-in a LGPLv2+ (codice che scrive il firmware in un componente) e a consentire la ridistribuzione del firmware da parte di LVFS
Per i fornitori: indicazioni iniziali:
L'aggiornamento deve ridurre al minimo il tempo di interruzione della funzionalità del componente interno o della periferica, idealmente a un paio di secondi. La parte più lunga dell'aggiornamento dovrebbe avvenire in background senza interrompere l'attività dell'utente
- Se questa periferica influisce sull'esperienza utente in modo evidente (ad es. il display smette di funzionare), questo requisito diventa ancora più stringente
Per abilitare questo tipo di aggiornamento silenzioso, ti consigliamo vivamente di utilizzare gli aggiornamenti A/B
- Gli aggiornamenti A/B che possono essere attivati allo scollegamento della periferica sono ideali per ridurre al minimo la interruzione dell'utente
L'aggiornamento deve essere recuperabile: se spegni il dispositivo, scolleghi la periferica e così via, l'aggiornamento non deve bloccare il dispositivo o la periferica. Deve essere sufficientemente robusto da recuperare senza l'intervento dell'utente.
- L'ipotesi iniziale dovrebbe essere che non viene eseguita alcuna azione da parte dell'utente durante l'intero aggiornamento, poiché gli script e le fasi di aggiornamento appropriati devono essere eseguiti autonomamente.
Secondo passaggio: utilizzo di fwupd
Se un fornitore non ha mai utilizzato fwupd
Chrome OS fornisce all'OEM i requisiti per l'aggiornamento del firmware tramite fwupd. L'OEM deve comunicare queste informazioni direttamente ai fornitori di chip / componenti
In alcuni casi, l'ODM può aiutare l'OEM a interagire direttamente con i fornitori di chip. È responsabilità dell'OEM comunicare e trasmettere questi requisiti di conseguenza
Tieni presente che se fornisci il codice sorgente con licenza LGPLv2 o successiva, in genere non è possibile ricavare il plug-in da questo codice (molte complessità). In questo caso, il fornitore del chip dovrà avere qualcuno che possa collaborare con i manutentori di fwupd e con gli ingegneri di Google.
L'OEM può essere proattivo e contribuire a ottenere l'impegno dei fornitori di chip di collaborare strettamente con i manutentori. La richiesta di assistenza tecnica da parte del fornitore deve soddisfare i seguenti requisiti:
Conoscenza approfondita delle peculiarità e delle funzionalità di progettazione del componente hardware aggiornabile, preferibilmente anche nello stesso team che ha scritto il firmware
Comprendere la differenza tra le licenze open source comuni (ad es. LGPLv2 e MIT)
Avere una buona conoscenza del linguaggio C, con una conoscenza di base di GLib e GObject, in particolare di GErrors
Avere un account GitHub e sapere come aprire e aggiornare una richiesta di pull, eseguire revisioni del codice di GitHub e conoscere la struttura di fwupd con tutti gli helper forniti da fwupd (ad es. chunking, aggancio/sgancio, tentativi di nuovo accoppiamento del dispositivo, HID e così via)
(Facoltativo) Possibilità di inviare campioni hardware nel Regno Unito: molto utile per i manutentori di fwupd per aiutare il fornitore a risolvere i problemi e per aggiungere la scheda ai test di fwupd eseguiti su ogni release. Quest'ultimo è importante per interrompere le regressioni nel ramo di sviluppo.
Parallelamente, l'OEM può iniziare a interagire tramite la mailing list di fwupd o direttamente con Richard Hughes (hughsient@gmail.com) ed esaminare il piano prima che venga scritto il codice del plug-in.
Se un'azienda è piccola, con poche o nessuna risorsa di ingegneria o conoscenza dell'open source, il seguente suggerimento potrebbe essere utile:
Il fornitore del componente potrebbe utilizzare società di consulenza, che hanno familiarità con il lavoro open source (senza costi aggiuntivi)
Sebbene questo suggerimento possa essere utile per scalare, il valore del fornitore che lo esegue internamente è che gli ingegneri acquisiscono familiarità con la procedura e possono facilmente aggiungere VID/PID in futuro per il nuovo hardware. Inoltre, è più rapido rispondere a domande / problemi relativi al debugging sull'hardware
Terzo passaggio: passaggi finali
Alla fine, il codice viene sottoposto a refactoring in piccoli commit esaminabili utilizzando tutte le funzionalità condivise in fwupd
Al termine, il plug-in viene unito a monte
Il codice utilizzato a monte sarà lo stesso codice in ChromeOS
I binari di aggiornamento del firmware utilizzati al di fuori di ChromeOS verranno distribuiti in LVFS
Nello specifico, per ChromeOS:
L'OEM deve caricare il file binario del firmware sui nostri server tramite CPFE
Per il funzionamento dei test di regressione hardware, devono essere ancora presenti archivi del cabinet di aggiornamento ridistribuibili su LVFS
Quarto passaggio (facoltativo) - Aggiunta di nuovi componenti
- Se il framework fwupd è già implementato, l'unico passaggio aggiuntivo è che il fornitore del componente aggiornabile deve lavorare sulle richieste pull per aggiungere peculiarità e VID/PID per le varianti hardware
Altre indicazioni: lavoro su LVFS
Crea un nuovo account fornitore (la configurazione richiede circa 2 minuti)
I fornitori creano utenti per il proprio dominio o utilizzano un servizio come Azure AD per sincronizzare gli account utente con il LVFS. Possono caricare il firmware in modo completamente senza costi su firmware privati e soggetti a embargo del fornitore con pochissimi controlli (quindi spesso sono gli ingegneri a farlo fin dall'inizio).
Alla fine, il passaggio alla versione di test o stabile richiede un qualche tipo di documento del loro reparto legale che indichi chiaramente che LVFS può ridistribuire e analizzare il firmware. Le linee guida in formato PDF sono fornite da Richard. ● Se il fornitore è solo un fornitore di silicio o un ODM, può diventare un "affiliato" dell'OEM e caricare il firmware per suo conto, con l'OEM che ha piena visibilità su cosa succede con il firmware con il proprio nome.
Ci sono molte altre cose da configurare (ad es. l'ID fornitore li limita a un insieme di ID PCI o USB), ma la maggior parte dei fornitori ha già un ID assegnato e la configurazione richiede 20 secondi.
Altre indicazioni: informazioni specifiche per ChromeOS
Nel nostro caso, i file binari di aggiornamento del firmware non vengono estratti direttamente da LVFS. Il file CAB verrà invece archiviato nel file system locale (rootfs)
- Workstream futuro: incorpora il binario del firmware in DLC creando un'ebuild di portage sull'overlay di portage appropriato
fwupd deve essere invocato (tramite il relativo strumento a riga di comando fwupdtool) al momento giusto. Per ogni componente aggiornabile deve essere creata una regola udev (o uno script equivalente) che emetta un evento upstart fwuptool-update. Questo evento verrà gestito automaticamente per eseguire fwupdtool con gli argomenti corretti e la sandboxing corretta (minijail).
Un altro componente decide se è necessaria l'interfaccia utente, solo in determinate circostanze, a seconda della natura del componente aggiornato. Da valutare dal team di PM e di ingegneria. Le indicazioni di livello superiore, come indicato nel primo passaggio, sono volte a ridurre al minimo le azioni da parte dell'utente.
Risorse aggiuntive per i fornitori
Riferimento alla documentazione esterna: https://lvfs.readthedocs.io/
Riferimento ai contratti con i fornitori esterni: fwupd.org/lvfs/docs/agreement
Tutorial sullo sviluppo di plug-in: https://fwupd.github.io/tutorial.html
Tutorial sul debug dei plug-in: https://lvfs.readthedocs.io/en/latest/custom-plugin.html
File quirk di esempio: https://github.com/fwupd/fwupd/blob/master/plugins/wacom-usb/wacom-usb.quirk
Cronologia delle revisioni
| Data | Versione | Note |
|---|---|---|
| 2025-03-12 | 1.0.2 | Convertire il testo da PDF a Markdown |
| 2024-01-31 | 1.0.1 | Ripubblicazione sulla nuova piattaforma |
| 2023-10-12 | 1,0 | Prima pubblicazione |