Ciclo di vita di FCM

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

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

Terminologia

Framework Compatibility Matrix (FCM)

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

Versioni FCM della piattaforma (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 moduli FCM in una release del framework.

Versione FCM target (V)

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

Versione HAL

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

File manifest del dispositivo

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

HAL del dispositivo

HAL elencati (forniti) nel manifest del dispositivo e nella matrice di compatibilità del framework (FCM).

Device Compatibility Matrix (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, tra cui system, system_ext e le immagini dei prodotti. Gli HAL nel manifest del framework vengono disattivati dinamicamente in base alla versione FCM di destinazione del dispositivo.

HAL di framework

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

Ciclo di vita di FCM nella base di codice

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

Un dispositivo con la versione di rilascio di Android corrispondente dovrebbe avere un valore FCM maggiore o uguale al livello equivalente. Ad esempio, un dispositivo con Android 11 in genere ha il livello FCM 5, ma implementa FCM 6 o versioni successive, che prevede vari requisiti aggiuntivi specificati nelle matrici di compatibilità. I livelli supportati per Android 15 sono:

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

Quando Android ritira un livello FCM, questo rimane supportato per i dispositivi esistenti. I dispositivi che hanno come target livelli FCM inferiori sono implicitamente autorizzati a utilizzare gli HAL elencati nei livelli FCM più recenti, a condizione che 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 valore compatibility_matrix.f.xml esistente (dove f < F) non viene più modificato.

Per iniziare a sviluppare in una nuova versione 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 compilazione corrispondenti per installare questa matrice di compatibilità sul dispositivo.

Introduzione di un nuovo HAL

Durante lo sviluppo, quando introduci un nuovo HAL (Wi-Fi, NFC e così via) in Android sulla versione corrente di FCM 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 voce seguente è stata aggiunta a compatibility_matrix.F.xml (che in precedenza si chiamava compatibility_matrix.current.xml temporaneamente durante lo sviluppo di questa release):

<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 (minore)

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

Durante lo sviluppo, quando un HAL AIDL esegue l'upgrade della versione da 2 a 3 con la versione FCM corrente 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 minore 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 per Android F. La voce nelle FCM precedenti alla versione 2 ha il seguente aspetto:

<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>

Eseguire l'upgrade di un HAL (principale)

Durante lo sviluppo, quando un HAL esegue l'upgrade a una versione principale nella versione F di FCM, 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 lanciati con x.0.
• Con le versioni principali precedenti nello stesso <hal> tag, se i dispositivi forniti con V = F possono essere lanciati con una versione principale precedente.

Ad esempio, la versione F di FCM introduce foo@2.0 come upgrade della versione principale dell'HAL 1.0 e ritira l'HAL 1.0. 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é l'HAL 1.0 non è in compatibility_matrix.F.xml, i dispositivi che hanno come target la versione F di FCM non devono fornire l'HAL 1.0 (poiché questo HAL è considerato deprecato).
• Poiché l'HAL 1.0 è presente nelle versioni precedenti di FCM, il framework può comunque lavorare con l'HAL 1.0, quindi è compatibile con le versioni precedenti di FCM.

Nuove versioni di FCM

La procedura di rilascio di una versione FCM nella 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 la compilazione e l'avvio avvengano su tutti i dispositivi.
3. Aggiorna i test VTS per assicurarti che i dispositivi lanciati con il framework più recente (in base al livello API di spedizione) abbiano la versione FCM target V >= F.
4. Pubblica il file in AOSP.

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

Inoltre, i messaggi FCM di product e system_ext possono elencare anche i requisiti per ogni versione FCM della piattaforma. La release delle versioni FCM nelle partizioni product e system_ext viene eseguita rispettivamente dal proprietario di queste immagini. I numeri della versione FCM nelle partizioni product e system_ext devono essere in linea con quelli della partizione system. Analogamente alle versioni FCM nella partizione di sistema, la tabella di compatibilità della versione FCM F nelle partizioni product e system_ext riflette i requisiti di un dispositivo con la versione FCM F di destinazione.

Ritiro della versione HAL

Il ritiro di una versione HAL è una decisione dello sviluppatore (ad es. per gli HAL AOSP, la decisione spetta a Google). Ciò potrebbe accadere quando viene rilasciata una versione HAL successiva (minore o maggiore).

Rifiutare un HAL del dispositivo

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

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

• Il framework richiede una versione più recente (maggiore o minore);
• Il framework non richiede più l'HAL.

Ad esempio, in Android 9 viene introdotto health@2.0 come upgrade della versione principale dell'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. Di conseguenza, health@1.0 è considerato deprecato.

Ritirare un HAL del framework

Quando un determinato HAL del framework foo@x.y viene ritirato nella versione FCM F, significa che qualsiasi dispositivo lanciato con la versione FCM di destinazione V = F o successiva non deve aspettarsi che il framework fornisca foo nella versione x.y o in una versione precedente a x.y. Il framework fornisce ancora una versione HAL deprecata per l'upgrade dei dispositivi.

Quando viene rilasciata la versione F di FCM, una versione HAL foo@x.y è considerata ritirata 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 sui dispositivi lanciati con V = F non deve elencare gli HAL di framework con max-level < V.

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

Rimozione del supporto per le versioni FCM di destinazione

Quando i dispositivi attivi di una determinata versione FCM target V scendono al di sotto di una determinata soglia, la versione FCM target viene rimossa dall'insieme S_F della successiva release del framework. Questa operazione viene eseguita in entrambi i seguenti passaggi:

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

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

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

Rimozione di HAL completamente ritirati

Quando una versione di FCM viene rimossa, alcune interfacce HAL o versioni di interfacce HAL non sono più presenti in nessun 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 all'interfaccia HAL da Android, inclusi il codice client nel framework, l'implementazione predefinita e i casi di test VTS.

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

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 si tratta di 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 potenzialmente in fase di sviluppo. Sono incluse le versioni HAL disponibili solo in compatibility_matrix.F.xml. Esempi:

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

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

Uscite e attuali

Per gli HAL del dispositivo, se una versione HAL è presente 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, l'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 è corrente (ovvero non è deprecata). Ad esempio, le versioni HAL esistenti (ad esempio nfc@1.0 introdotta in compatibility_matrix.legacy.xml) che continuano a esistere in compatibility_matrix.3.xml sono considerate anche come versioni HAL rilasciate e attuali.

Per gli HAL del framework, se una versione HAL è nel manifest del framework del ramo rilasciato più recente senza l'attributo max-level o (in modo insolito) un max-level uguale o superiore alla versione FCM rilasciata in questo ramo, è considerata una versione HAL rilasciata e corrente. Ad esempio, il displayservice HAL è rilasciato e aggiornato in Android 12, come specificato dal manifest del framework Android 12.

Rilasciato, ma deprecato

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

• Viene rilasciato.
• Non è presente nella matrice di compatibilità pubblica e bloccata con 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 è in compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, e compatibility_matrix.2.xml, ma non in compatibility_matrix.3.xml. Di conseguenza, è considerata obsoleta in Android 9.
• L'HAL di gestione dell'alimentazione ha un upgrade di versione minore 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.

Di conseguenza, power@1.0 è corrente, ma NON deprecato in Android 9.

Per gli HAL del framework, se una versione HAL è nel manifest del framework del ramo di release più recente con un attributo max-level inferiore alla versione FCM rilasciata in questo ramo, è considerata una versione HAL rilasciata, ma deprecata. Ad esempio, l'HAL schedulerservice è stato rilasciato, ma è deprecato in Android 12, come specificato dal manifest del framework Android 12.

Rimosso

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

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

Le matrici di compatibilità pubbliche e bloccate, ma non supportate dal framework, vengono conservate nella base di codice per definire l'insieme delle versioni HAL rimosse in modo da poter scrivere i test VTS per garantire che gli HAL rimossi non siano presenti sui nuovi dispositivi.

Per gli HAL di framework, una versione HAL viene rimossa se e solo se vengono soddisfatti i seguenti requisiti:

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

FCM legacy

La versione FCM target precedente è un valore speciale per tutti i dispositivi non Treble. La versione precedente di FCM, compatibility_matrix.legacy.xml, elenca i requisiti del framework sui dispositivi precedenti (ovvero quelli lanciati prima di Android 8.0).

Se questo file esiste per un FCM con la versione F, è possibile eseguire l'upgrade a F di qualsiasi dispositivo non Treble, a condizione che il manifest del dispositivo sia compatibile con questo file. La sua rimozione segue la stessa procedura delle notifiche push per le altre versioni di FCM target (vengono rimosse quando il numero di dispositivi pre-8.0 attivi 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 release Android specifica, consulta Level.h.