Questa pagina è stata tradotta dall'API Cloud Translation.

Matrici di compatibilità

Questa sezione descrive le matrici di compatibilità del framework e dei dispositivi e lo schema della matrice di compatibilità. Per le regole di corrispondenza, consulta Regole di corrispondenza.

Matrice di compatibilità del framework (FCM)

La matrice di compatibilità del framework (FCM) descrive i requisiti del framework sul dispositivo su cui viene eseguito. La matrice di compatibilità del framework è composta dalla matrice di compatibilità del sistema, dalla matrice di compatibilità dei prodotti e dalla matrice di compatibilità system_ext. I requisiti di FCM devono essere soddisfatti dal manifest del dispositivo (requisiti applicati in fase di compilazione, di runtime e nei test VTS).

Il servizio FCM system_ext e il servizio FCM del prodotto sono complementari al servizio FCM specifico del dispositivo (installato nella partizione di sistema).

Il servizio FCM del dispositivo deve riflettere i requisiti dei moduli nella partizione di sistema.
Il servizio FCM system_ext deve riflettere i requisiti dei moduli nella partizione system_ext.
L'FCM del prodotto deve riflettere i requisiti dei moduli nella partizione del prodotto.

Tutti gli FCM devono essere in linea con le modifiche apportate dal framework di un OEM nelle partizioni system, product e system_ext. Ad esempio, se un'app installata nella partizione del prodotto utilizza un'estensione del fornitore di un'interfaccia HAL, il requisito dell'interfaccia HAL deve essere dichiarato nel FCM del prodotto.

Esempio di file della matrice di compatibilità del sistema:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="framework" level="3">
    <hal>
        <name>android.hardware.camera</name>
        <version>1.0</version>
        <version>3.1-4</version>
        <interface>
            <name>ICameraProvider</name>
            <instance>default</instance>
            <regex-instance>[a-z_]+/[0-9]+</regex-instance>
        </interface>
    </hal>
    <hal>
        <name>android.hardware.nfc</name>
        <version>1.0</version>
        <interface>
            <name>INfc</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal optional="true">
        <name>android.hardware.graphics.composer</name>
        <version>2.1</version>
        <interface>
            <name>IComposer</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="aidl" optional="true">
        <name>android.hardware.light</name>
        <version>1-2</version>
        <interface>
            <name>ILights</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="native">
        <name>GL</name>
        <version>1.1</version>
        <version>3.0</version>
    </hal>
    <hal format="native">
        <name>EGL</name>
        <version>1.1</version>
    </hal>
    <kernel version="3.18.51">
        <!-- common configs -->
    </kernel>
    <kernel version="3.18.51">
        <!-- arm specific configs -->
        <condition>
            <config>
                <key>CONFIG_ARM</key>
                <value type="tristate">y</value>
            </config>
        <condition>
        <config>
            <key>CONFIG_A</key>
            <value type="string"></value>
        </config>
        <config>
            <key>CONFIG_B</key>
            <value type="tristate">y</value>
        </config>
    </kernel>
    <kernel version="4.1.22">
        <!-- common configs -->
        <config>
            <key>CONFIG_A</key>
            <value type="string">foo</value>
        </config>
        <config>
            <key>CONFIG_B2</key>
            <value type="int">1024</value>
        </config>
    </kernel>
    <sepolicy>
        <kernel-sepolicy-version>30</kernel-sepolicy-version>
        <sepolicy-version>25.0</sepolicy-version>
        <sepolicy-version>26.0-3</sepolicy-version>
    </sepolicy>
    <avb>
        <vbmeta-version>2.1</vbmeta-version>
    </avb>
    <xmlfile format="dtd">
        <name>media_profile</name>
        <version>1.0</version>
        <path>/system/etc/media_profile_V1_0.dtd</path>
    </xmlfile>
</compatibility-matrix>

Per maggiori dettagli, consulta la sezione Ciclo di vita di FCM.

Matrice di compatibilità dei prodotti

L'FCM del prodotto è un file della matrice di compatibilità del framework nella partizione del prodotto. L'oggetto VINTF unisce l'FCM del prodotto con gli FCM nelle partizioni system e system_ext in fase di runtime.

Esempio di file FCM del prodotto:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="framework">
    <hal>
        <name>vendor.foo.camera</name>
        <version>1.0</version>
        <interface>
            <name>IBetterCamera</name>
            <instance>default</instance>
        </interface>
    </hal>
</compatibility-matrix>

Matrice di compatibilità di System_ext

L'FCM system_ext è un file della matrice di compatibilità del framework nella partizione system_ext. L'oggetto VINTF unisce l'attributo FCM system_ext agli attributi FCM nelle partizioni del sistema e del prodotto in fase di esecuzione. Consulta la matrice di compatibilità dei prodotti per un esempio di file FCM system_ext.

Matrice di compatibilità dei dispositivi (DCM)

La matrice di compatibilità dei dispositivi descrive un insieme di requisiti previsti dal dispositivo per il framework (requisiti applicati al momento del lancio e del trasferimento OTA).

File DCM di esempio:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="device">
    <hal>
        <name>android.hidl.manager</name>
        <version>1.0</version>
        <interface>
            <name>IServiceManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.memory</name>
        <version>1.0</version>
        <interface>
            <name>IMemory</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.allocator</name>
        <version>1.0</version>
        <interface>
            <name>IAllocator</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.framework.sensor</name>
        <version>1.0</version>
        <interface>
            <name>ISensorManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <vendor-ndk>
        <version>27</version>
    </vendor-ndk>
    <system-sdk>
        <version>27</version>
    </system-sdk>
</compatibility-matrix>

Schema della matrice di compatibilità

Questa sezione descrive il significato di questi tag XML. Alcuni tag "obbligatori" possono essere mancanti nel file di origine nella struttura di origine di Android e scritti da assemble_vintf al momento della compilazione. I tag "Required" devono essere presenti nei file corrispondenti sul dispositivo.

?xml

Facoltativo. Fornisce solo informazioni al parser XML.

compatibility-matrix.version

Obbligatorio. Meta-versione di questa matrice di compatibilità. Descrive gli elementi previsti nella matrice di compatibilità. Non correlato alla versione XML.

compatibility-matrix.type

Obbligatorio. Tipo di questa matrice di compatibilità:

"device": matrice di compatibilità dei dispositivi.
"framework": matrice di compatibilità del framework.

manifest.level

Obbligatorio per la matrice di compatibilità del framework. In Android 12 e versioni successive, consentito nei file della matrice di compatibilità del framework nelle partizioni product e system_ext. Specifica la versione della matrice di compatibilità del framework (FCM Version) di questo file. Non dichiararlo nella matrice di compatibilità del framework specifica del dispositivo (ad es. DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE).

compatibility-matrix.hal

Facoltativo e può essere ripetuto. Elenca un singolo HAL (HIDL o nativo) che deve essere presente obbligatoriamente per il proprietario della matrice di compatibilità (framework o dispositivo). Le voci HAL sono distinte da un elemento <name>. Possono essere presenti più voci HAL con lo stesso nome (implica la condizione "e").

compatibility-matrix.hal.format

Facoltativo. Il valore può essere uno dei seguenti:

"hidl": HAL HIDL. Questa è l'impostazione predefinita.
"aidl": HAL AIDL. Valido solo per la meta-versione 2.0 della matrice di compatibilità.
"native": HAL native.

compatibility-matrix.hal.optional (Android 15 o versioni precedenti)

è facoltativo e il valore predefinito è false. Indica se questo HAL è facoltativo per il proprietario della matrice di compatibilità (framework o dispositivo). Se una voce <hal> è contrassegnata come facoltativa, significa che il proprietario può lavorare con questo HAL, se presente, ma non ne richiede la presenza.

Avviso: questo attributo è stato ritirato dopo Android 15 e non ha più alcun effetto. Se è necessario installare HAL, questo requisito deve essere applicato nei test.

compatibility-matrix.hal.name

Obbligatorio. Nome completo del pacchetto di questo HAL. Esempi:

android.hardware.camera (HAL HIDL o AIDL)
GLES (HAL nativo, richiede solo il nome)

compatibility-matrix.hal.version

Un elenco di intervalli di versioni (vedi Corrispondenze HAL) che definisce le versioni previste dal proprietario della matrice di compatibilità (framework o dispositivo).

Per HIDL e HAL native, obbligatorio, può essere ripetuto senza duplicati. Il formato è uno dei seguenti:

MAJOR.MINOR_MIN-MINOR_MAX
MAJOR.MINOR (equivalente a MAJOR.MINOR-MINOR)

Per gli HAL AIDL, non deve essere presente sui dispositivi con Android 11 e versioni precedenti. Facoltativo sui dispositivi con versioni successive. Se specificato, il formato è uno dei seguenti:

VERSION_MIN-VERSION_MAX
VERSION (equivalente a VERSION-VERSION)

Se non specificato, il valore predefinito è 1.

compatibility-matrix.hal.interface

Facoltativo, può essere ripetuto. Un elenco di interfacce richieste di questo HAL.

compatibility-matrix.hal.interface.name

Obbligatorio. Nome dell'interfaccia.

compatibility-matrix.hal.interface.instance

Facoltativo, può essere ripetuto. Un elenco di istanze richieste di questa interfaccia.

compatibility-matrix.hal.interface.regex-instance

Facoltativo, può essere ripetuto. Un elenco di pattern di nomi di istanze obbligatori in questa interfaccia. Utilizza il formato espressione regolare avanzata.

compatibility-matrix.kernel

Facoltativo, può essere ripetuto. Specifica un elenco di configurazioni del kernel richieste dal framework su ogni versione del kernel.
Possono essere presenti più <kernel> con lo stesso <version> per indicare una relazione "e". Ogni <kernel> è un "frammento" degli obblighi che vengono attivati solo quando vengono soddisfatti i <conditions>.

compatibility-matrix.kernel.version

Obbligatorio. Versione del kernel. Il formato è VERSION.MAJOR_REVISION.MINOR_REVISION. La versione e la revisione principale devono corrispondere esattamente. La revisione secondaria definisce la versione LTS minima del kernel prevista dal framework.

compatibility-matrix.kernel.condition

Facoltativo. Non deve esistere per i primi <kernel> di ogni versione. Specifica un elenco di condizioni. Quando le condizioni sono soddisfatte, vengono attivati i requisiti indicati in questo frammento <kernel>.

compatibility-matrix.kernel.config

Facoltativo, può essere ripetuto. Elenca gli elementi CONFIG che devono essere abbinati per questa versione del kernel. Ogni elemento CONFIG è una coppia chiave-valore; gli elementi di configurazione sono distinti in base alla chiave.

compatibility-matrix.kernel.config.key

Obbligatorio. Nome della chiave dell'elemento CONFIG. Inizia con CONFIG_.

compatibility-matrix.kernel.config.value

Obbligatorio. Valore dell'elemento CONFIG. Il formato dipende dal tipo:

string. Le virgolette sono omesse.
int. Sono accettati valori decimali ed esadecimali (devono iniziare con 0x o 0X)). Interpretato come numero intero a 64 bit; gli overflow comportano il troncamento. Il parser accetta valori da -2⁶⁴ + 1 a 2⁶⁴ - 1, il 65° bit viene troncato; per maggiori dettagli, consulta la pagina di manuali strtoull.)
range. Il formato è [int]-[int], ad es. 10-20. Sono accettati valori esadecimali che devono iniziare con 0x o 0X. I due limiti devono essere numeri interi a 64 bit senza segno.
tristate. I valori validi sono y, m e n.

compatibility-matrix.kernel.config.value.type

Obbligatorio. Tipo del valore dell'elemento CONFIG, uno dei seguenti:

string
int
range
tristate

compatibility-matrix.sepolicy

Obbligatorio. Contiene tutte le voci relative a sepolicy. Utilizzato solo dalla matrice di compatibilità del framework.

compatibility-matrix.sepolicy.sepolicy-version

Obbligatorio, può essere ripetuto. Descrive il requisito relativo alla versione di sepolicy. Corrisponde a manifest.sepolicy.version. Ogni istanza di un elemento definisce un intervallo di versioni di sepolicy.

compatibility-matrix.sepolicy.kernel-sepolicy-version

Obbligatorio. Dichiara la versione di policydb con cui funziona il framework.

compatibility-matrix.avb.vbmeta-version

Facoltativo; utilizzato solo dalla matrice di compatibilità del framework. Dichiara la versione AVB utilizzata per firmare system.img. È stata ritirata in Android 10.

compatibility-matrix.vendor-ndk

Facoltativo; utilizzato solo dalla matrice di compatibilità dei dispositivi. Dichiara il Requisito dello snapshot del fornitore VNDK. Se mancante, non viene richiesto alcun requisito VNDK sull'immagine di sistema.

compatibility-matrix.vendor-ndk.version

Obbligatorio. Un numero intero positivo che dichiara una versione VNDK richiesta dall'immagine del fornitore.

compatibility-matrix.vendor-ndk.library

Facoltativo, può essere ripetuto. Dichiara un insieme di librerie VNDK richieste dall'immagine del fornitore. Stessa semantica di manifest.vendor-ndk.library.

compatibility-matrix.system-sdk.version

Facoltativo, può essere ripetuto; utilizzato solo dalla matrice di compatibilità dei dispositivi. Dichiara il requisito delle app del fornitore per le versioni dell'SDK di sistema. Se non è presente, non viene richiesto alcun SDK di sistema per l'immagine di sistema.