Ciclo di vita di FCM

Una release del framework Android ha più matrici di compatibilità del framework (FCM), una per ogni versione FCM di destinazione aggiornabile, che definiscono cosa può utilizzare il framework e i requisiti della versione FCM di destinazione. Nell'ambito del ciclo di vita di FCM, Android ritira e rimuove gli HAL HIDL, quindi modifica i file FCM per riflettere lo stato della versione HAL.

Per attivare gli aggiornamenti OTA solo del framework nei propri ecosistemi, i partner che estendono le interfacce del fornitore devono anche ritirare e rimuovere gli HAL HIDL utilizzando gli stessi metodi.

Nota :per ulteriori dettagli sulle HAL HIDL, consulta Matrici di compatibilità, Regole di corrispondenza, Controllo delle versioni delle HAL HIDL.

Terminologia

Matrice di compatibilità dei framework (FCM)

Un file XML che specifica i requisiti del framework per le implementazioni del fornitore conformi. La matrice di compatibilità è versionata e una nuova versione viene bloccata per ogni release del framework. Ogni release del framework contiene più FCM.

Versioni della piattaforma FCM (S_F)

L'insieme di tutte le versioni di FCM in una release del framework. Il framework può funzionare con qualsiasi implementazione del fornitore che soddisfi uno di questi FCM.

Versione FCM (F)

La versione più recente tra tutti i FCM in una release del framework.

Target FCM Version (V)

La versione FCM di destinazione (da S_F), dichiarata esplicitamente nel manifest del dispositivo, che un'implementazione del fornitore soddisfa. L'implementazione di un fornitore deve essere generata in base a un FCM pubblicato, anche se può dichiarare versioni HAL più recenti nel manifest del dispositivo.

HAL Version

Una versione HAL ha il formato foo@x.y, dove foo è il nome HAL e x.y è la versione specifica, ad esempio nfc@1.0, keymaster@3.0 (il prefisso radice, ad esempio android.hardware, viene omesso in tutto il documento).

Manifest del dispositivo

File XML che specificano quali versioni HAL fornisce il lato dispositivo dell'interfaccia fornitore, incluse le immagini del fornitore e dell'ODM. I contenuti di un manifest del dispositivo sono vincolati dalla versione FCM di destinazione del dispositivo, ma possono elencare HAL che sono strettamente più recenti rispetto al FC corrispondente a V.

HAL dei dispositivi

HAL elencate (fornite) nel manifest del dispositivo ed elencate nella matrice di compatibilità del framework (FCM).

Matrice di compatibilità dei dispositivi (DCM)

Un file XML che specifica i requisiti del fornitore per le implementazioni del framework conformi. Ogni dispositivo contiene un DCM.

Manifest del framework

Un file XML che specifica le versioni HAL fornite dal lato framework dell'interfaccia del fornitore, incluse le immagini di sistema, system_ext e prodotto. Gli HAL nel manifest del framework vengono disattivati dinamicamente in base alla versione FCM di destinazione del dispositivo.

HAL del framework

HAL elencati come forniti nel manifest del framework ed elencati nella matrice di compatibilità dei dispositivi (DCM).

Ciclo di vita di FCM nel codebase

Questo documento descrive il ciclo di vita di FCM in astratto. Per visualizzare i manifest supportati, consulta hardware/interfaces/compatibility_matrices/compatibility_matrix.<FCM>.xml, dove FCM è disponibile in system/libvintf/include/vintf/Level.h.

Un dispositivo che spedisce la versione di Android corrispondente dovrebbe avere un valore FCM maggiore o uguale al livello equivalente. Ad esempio, un dispositivo spedito con Android 12 in genere ha FCM di livello 6, ma potrebbe implementare FCM di livello 7 o superiore, il che modifica il comportamento di Android e impone l'utilizzo di API fornitore più recenti, come specificato nelle matrici di compatibilità. I livelli supportati per Android 16 sono:

FCM	Versione di Android
6	Android 12/S
7	Android 13/T
8	Android 14/U
202404	Android 15/V
202504	Android 16/B

Il livello FCM è uguale o più recente del livello API fornitore.

Quando è stato annunciato Project Treble, le immagini di sistema Android sono state create per essere retrocompatibili con le tre versioni precedenti delle implementazioni del fornitore (quattro in totale). Per supportare una durata più lunga dei dispositivi, questo intervallo è stato aumentato per supportare la versione attuale e le sei precedenti di FCM (sette in totale) per 202404 e versioni successive.

Quando Android ritira un livello FCM, questo continua a essere supportato per i dispositivi esistenti. I dispositivi che hanno come target livelli FCM inferiori possono utilizzare implicitamente gli HAL elencati nei livelli FCM superiori, purché siano disponibili nel ramo.

Sviluppare in una nuova versione di FCM

Android incrementa la versione di FCM per ogni release del framework (ad esempio Android 8 e 8.1). Durante lo sviluppo, viene creato il nuovo compatibility_matrix.F.xml e il compatibility_matrix.f.xml esistente (dove f < F) non viene più modificato.

Per iniziare lo sviluppo in una nuova versione di FCM F:

1. Copia l'ultima versione di compatibility_matrix.<F-1>.xml in compatibility_matrix.F.xml.
2. Aggiorna l'attributo level nel file su F.
3. Aggiungi le regole di build corrispondenti per installare questa matrice di compatibilità sul dispositivo.

Introduci un nuovo HAL

Durante lo sviluppo, quando introduci un nuovo HAL (Wi-Fi, NFC e così via) in Android nella versione FCM attuale F, aggiungi l'HAL a compatibility_matrix.F.xml.

Ad esempio, Android 8.1 ha introdotto cas@1.0. I dispositivi lanciati con Android 8.1 possono implementare questo HAL, pertanto la seguente voce è stata aggiunta a compatibility_matrix.F.xml (che durante lo sviluppo di questa release era temporaneamente denominata compatibility_matrix.current.xml):

<hal format="hidl">
    <name>android.hardware.cas</name>
    <version>1.0</version>
    <interface>
        <name>IMediaCasService</name>
        <instance>default</instance>
    </interface>
</hal>

Eseguire l'upgrade di un HAL (secondario)

Le versioni HAL AIDL vengono conteggiate come versioni HAL secondarie. Le versioni dell'interfaccia HIDL hanno versioni major.minor come 1.2.

Durante lo sviluppo, quando una HAL AIDL viene aggiornata dalla versione 2 alla versione 3 nella versione FCM attuale F, la nuova versione viene aggiunta alla voce HAL in compatibility_matrix.F.xml. Il campo della versione di una voce HAL accetta intervalli come 2-3.

Ad esempio, Android FCM F ha introdotto foo@3 come upgrade della versione secondaria dell'HAL. La versione precedente, foo@2, viene utilizzata per i dispositivi che hanno come target FCM precedenti, mentre la versione più recente, foo@3, può essere utilizzata per i dispositivi che hanno come target FCM Android F. La voce nelle FCM precedenti alla versione 2 è simile a questa:

<hal format="aidl">
    <name>foo</name>
    <version>2</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

Questa voce è stata copiata in compatibility_matrix.F.xml e modificata per supportare la versione 3 come segue:

<hal format="aidl">
    <name>foo</name>
    <version>2-3</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

Esegui l'upgrade di un HAL (principale)

Durante lo sviluppo, quando un HAL ha un upgrade della versione principale nella versione FCM attuale F, la nuova versione principale x.0 viene aggiunta a compatibility_matrix.F.xml con le seguenti impostazioni:

• Solo la versione x.0, se i dispositivi forniti con V = F devono essere avviati con x.0.
• Con le versioni principali precedenti nello stesso tag <hal>, se i dispositivi forniti con V = F possono essere avviati con una versione principale precedente.

Ad esempio, la versione F di FCM introduce foo@2.0 come aggiornamento della versione principale dell'HAL 1.0 e ne ritira il supporto. La versione precedente, foo@1.0, viene utilizzata per i dispositivi che hanno come target le versioni precedenti di FCM. I dispositivi che hanno come target la versione F di FCM devono fornire la nuova versione 2.0 se forniscono l'HAL. In questo esempio, le versioni precedenti di FCM contengono questa voce:

<hal format="hidl">
    <name>foo</name>
    <version>1.0</version>;
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

Copia questa voce in compatibility_matrix.F.xml e modificala come segue:

<hal format="hidl">
    <name>foo</name>
    <version>2.0</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

Restrizioni:

• Poiché HAL 1.0 non è in compatibility_matrix.F.xml, i dispositivi che hanno come target la versione FCM F non devono fornire HAL 1.0 (in quanto questa HAL è considerata obsoleta).
• Poiché l'HAL 1.0 è presente nelle versioni FCM precedenti, il framework può comunque funzionare con l'HAL 1.0, quindi è compatibile con i vecchi dispositivi che hanno come target le versioni FCM precedenti.

Nuove versioni di FCM

La procedura di rilascio di una versione FCM sulla partizione di sistema viene eseguita esclusivamente da Google nell'ambito di una release AOSP e include i seguenti passaggi:

1. Assicurati che compatibility_matrix.F.xml abbia l'attributo level="F".
2. Assicurati che tutti i dispositivi vengano compilati e avviati.
3. Aggiorna i test VTS per assicurarti che i dispositivi lanciati con l'ultimo framework (basato sul livello API di spedizione) abbiano la versione FCM di destinazione V >= F.
4. Pubblica il file su AOSP.

Ad esempio, i test VTS garantiscono che i dispositivi lanciati con Android 9 abbiano la versione FCM di destinazione >= 3.

Inoltre, gli FCM di product e system_ext potrebbero anche elencare i requisiti per ciascuna versione FCM della piattaforma. Il rilascio delle versioni FCM sulle partizioni product e system_ext viene eseguito rispettivamente dal proprietario di queste immagini. I numeri di versione di FCM nelle partizioni product e system_ext devono corrispondere a quelli nella partizione system. Analogamente alle versioni FCM nella partizione di sistema, la matrice di compatibilità nella versione FCM F nelle partizioni product e system_ext riflette i requisiti su un dispositivo con la versione FCM di destinazione F.

Ritiro della versione HAL

Il ritiro di una versione HAL è una decisione dello sviluppatore (ad es. per le HAL AOSP, la decisione viene presa da Google). Ciò può accadere quando viene rilasciata una versione HAL superiore (secondaria o principale).

Ritirare un HAL del dispositivo

Quando un determinato HAL foo@x.y del dispositivo viene ritirato nella versione F di FCM, significa che qualsiasi dispositivo lanciato con la versione di destinazione di FCM V = F o successive non deve implementare foo alla versione x.y o a qualsiasi versione precedente a x.y. Una versione HAL deprecata è ancora supportata dal framework per l'upgrade dei dispositivi.

Quando viene rilasciata la versione FCM F, una versione HAL foo@x.y viene considerata obsoleta se la versione HAL specifica non è indicata esplicitamente nell'ultima versione FCM per la versione FCM di destinazione V = F. Per i dispositivi lanciati con V = F, è soddisfatta una delle seguenti condizioni:

• Il framework richiede una versione superiore (principale o secondaria).
• Il framework non richiede più l'HAL.

Ad esempio, in Android 9 viene introdotto health@2.0 come aggiornamento della versione principale di HAL 1.0. health@1.0 viene rimosso da compatibility_matrix.3.xml, ma è presente in compatibility_matrix.legacy.xml, compatibility_matrix.1.xml e compatibility_matrix.2.xml. Pertanto, health@1.0 è considerato deprecato.

Ritirare un HAL framework

Quando una determinata HAL framework foo@x.y viene ritirata nella versione FCM F, significa che qualsiasi dispositivo lanciato con la versione FCM di destinazione V = F o successive non deve aspettarsi che il framework fornisca foo nella versione x.y o in qualsiasi versione precedente alla x.y. Una versione HAL ritirata viene comunque fornita dal framework per l'upgrade dei dispositivi.

Quando viene rilasciata la versione F di FCM, una versione HAL foo@x.y viene considerata obsoleta se il manifest del framework specifica max-level="F - 1" per foo@x.y. Per i dispositivi lanciati con V = F, il framework non fornisce l'HAL foo@x.y. La matrice di compatibilità dei dispositivi che vengono lanciati con V = F non deve elencare HAL del framework con max-level < V.

Ad esempio, in Android 12, schedulerservice@1.0 è deprecato. Il relativo attributo max-level è impostato su 5, la versione di FCM introdotta in Android 11. Consulta il manifest del framework Android 12.

Rimozione del supporto per le versioni FCM di destinazione

Utilizziamo un processo basato sulla pianificazione per determinare la rimozione della versione FCM di destinazione, per mantenere la compatibilità per le durate richieste e supportare i requisiti dei partner per i dispositivi di lunga durata.

Quando rimuoviamo una versione FCM di destinazione dall'insieme S_F della successiva release del framework, eseguiamo entrambi i seguenti passaggi:

1. Rimuovi compatibility_matrix.V.xml dalle regole di build (in modo che non venga installato nell'immagine di sistema) ed elimina qualsiasi codice che implementava o dipendeva dalle funzionalità rimosse.

2. Rimuovi le HAL del framework con max-level inferiore o uguale a V dal manifest del framework ed elimina qualsiasi codice che implementi le HAL del framework rimosse.

Ritiro graduale delle configurazioni della release

La strategia di branching di Trunk Stable, in cui le release della piattaforma trimestrali (QPR) vengono estratte direttamente da git_main anziché da rami di sviluppo delle release separati, richiede un processo di ritiro scaglionato. Una versione di FCM potrebbe essere rimossa per segnalazione anticipata nelle build trunk_staging, pur rimanendo supportata nel ramo di rilascio per ospitare i dispositivi che ricevono QPR durante l'anno.

In genere, una release del framework supporta sei FCM: una versione attuale, quattro versioni precedenti e una versione aggiuntiva per supportare le QPR. Questo numero può aumentare se versioni specifiche di FCM (come 202404 di Android 15) hanno un supporto esteso per la longevità del dispositivo.

I dispositivi con una versione FCM di destinazione al di fuori di S_F per una determinata release del framework non possono eseguire l'upgrade a quella release.

Rimozione delle HAL completamente ritirate

Quando una versione di FCM viene rimossa, alcune interfacce HAL o versioni di interfacce HAL non sono più presenti in alcun FCM. Ciò significa che Android non li supporta più, nemmeno per l'upgrade dei dispositivi.

Quando un HAL non è più supportato, gli sviluppatori rimuovono i riferimenti a questa interfaccia HAL da Android, incluso il codice client nel framework, l'implementazione predefinita e gli scenari di test VTS.

Se non sono presenti HAL supportati che ereditano dall'HAL da rimuovere, la definizione HAL stessa può essere rimossa con alcuni passaggi aggiuntivi.

Nota: è comune che le interfacce HAL HIDL ereditino dalle versioni precedenti dell'interfaccia. Le interfacce HAL AIDL sono implicitamente simili.

1. Rimuovi la definizione dell'interfaccia HAL dal codice sorgente. Sono inclusi i file *.aidl e il modulo Android.bp aidl_interface.
2. Se HIDL, rimuovi l'HASH da hardware/interfaces/current.txt.
3. Se AIDL, rimuovi la directory aidl_api con i file AIDL bloccati.
4. Rimuovi l'interfaccia da hardware/interfaces/compatibility_matrices/exclude/fcm_exclude.cpp.

Stato della versione HAL

Le sezioni seguenti descrivono (in ordine cronologico) i possibili stati di una versione HAL.

Non pubblicate

Per gli HAL dei dispositivi, se una versione HAL non è presente in nessuna delle matrici di compatibilità pubbliche e bloccate, è considerata non rilasciata e probabilmente in fase di sviluppo. Sono incluse le versioni HAL che si trovano solo in compatibility_matrix.F.xml. Esempi:

• Durante lo sviluppo di Android 9, l'HAL health@2.0 è stato considerato un HAL non rilasciato ed era presente solo in compatibility_matrix.3.xml.
• L'teleportation@1.0 HAL non è presente in nessuna matrice di compatibilità rilasciata ed è considerato anche un HAL non rilasciato.

Per le HAL del framework, se una versione HAL è presente solo nel manifest del framework di un ramo di sviluppo non correlato, viene considerata non rilasciata.

Rilasciato e attuale

Per gli HAL dei dispositivi, se una versione HAL si trova in una matrice di compatibilità pubblica e bloccata, viene rilasciata. Ad esempio, dopo che la versione 3 di FCM è stata bloccata e pubblicata in AOSP, la HAL health@2.0 è considerata una versione HAL rilasciata e attuale.

Se una versione HAL si trova in una matrice di compatibilità pubblica e bloccata che ha la versione FCM più recente, la versione HAL è attuale (ovvero non è deprecata). Ad esempio, le versioni HAL esistenti (come nfc@1.0 introdotta in compatibility_matrix.legacy.xml) che continuano a esistere in compatibility_matrix.3.xml sono considerate anche versioni HAL rilasciate e attuali.

Per le HAL del framework, se una versione HAL è nel manifest del framework dell'ultimo ramo rilasciato senza l'attributo max-level o (insolito) un max-level uguale o superiore alla versione FCM rilasciata in questo ramo, viene considerata una versione HAL rilasciata e attuale. Ad esempio, l'HAL displayservice è rilasciato e attuale in Android 12, come specificato dal manifest del framework Android 12.

Rilasciato ma ritirato

Per gli HAL dei dispositivi, una versione HAL viene ritirata se e solo se sono soddisfatte tutte le seguenti condizioni:

• È stato rilasciato.
• Non è presente nella matrice di compatibilità pubblica e bloccata che ha la versione FCM più recente.
• Si trova in una matrice di compatibilità pubblica e bloccata che il framework supporta ancora.

Esempi:

• L'HAL health@1.0 si trova in compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, e compatibility_matrix.2.xml, ma non in compatibility_matrix.3.xml. Pertanto, è considerato obsoleto in Android 9.
• L'HAL di alimentazione ha un aggiornamento della versione secondaria in Android 9, ma power@1.0 è ancora in compatibility_matrix.3.xml.
• power@1.0 compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, e compatibility_matrix.2.xml.
• compatibility_matrix.3.xml contiene power@1.0-1.

Pertanto, power@1.0 è attuale, ma NON è deprecato in Android 9.

Per gli HAL del framework, se una versione HAL si trova nel manifest del framework dell'ultimo ramo rilasciato con un attributo max-level inferiore alla versione di FCM rilasciata in questo ramo, viene considerata una versione HAL rilasciata ma ritirata. Ad esempio, l'HAL schedulerservice viene rilasciato, ma è deprecato in Android 12, come specificato dal manifest del framework Android 12.

Rimosso

Per gli HAL dei dispositivi, una versione HAL viene rimossa se e solo se sono vere le seguenti condizioni:

• È stato rilasciato in precedenza.
• Non è presente in alcuna matrice di compatibilità pubblica e bloccata supportata dal framework.

Le matrici di compatibilità pubbliche, bloccate, ma non supportate dal framework vengono mantenute nel codebase per definire il set di versioni HAL rimosse, in modo che i test VTS possano essere scritti per garantire che gli HAL rimossi non siano presenti sui nuovi dispositivi.

Per le HAL del framework, una versione HAL viene rimossa se e solo se sono soddisfatte le seguenti condizioni:

• È stato rilasciato in precedenza.
• Non è presente in alcun manifest del framework dell'ultimo branch rilasciato.

FCM legacy

Target FCM Version legacy è un valore speciale per tutti i dispositivi non Treble. L'FCM legacy, compatibility_matrix.legacy.xml, elenca i requisiti del framework sui dispositivi legacy (ovvero i dispositivi lanciati prima di Android 8.0).

Se questo file esiste per un FCM con versione F, qualsiasi dispositivo non Treble può essere aggiornato a F a condizione che il manifest del dispositivo sia compatibile con questo file. La sua rimozione segue la stessa procedura delle FCM per altre versioni di FCM di destinazione (rimosse dopo che il numero di dispositivi attivi con Android 7.1 o versioni precedenti scende al di sotto di una determinata soglia).

Versioni FCM rilasciate

L'elenco delle versioni FCM rilasciate è disponibile in hardware/interfaces/compatibility_matrices.

Per trovare la versione di FCM rilasciata con una specifica release di Android, consulta Level.h.