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, vedere Regole di corrispondenza .

Matrice di compatibilità quadro (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 è costituita dalla matrice di compatibilità del sistema, dalla matrice di compatibilità del prodotto e dalla matrice di compatibilità system_ext . I requisiti di FCM devono essere soddisfatti dal manifesto del dispositivo (requisiti applicati in fase di compilazione, runtime e in VTS).

L'FCM system_ext e l'FCM del prodotto sono complementi dell'FCM specifico del dispositivo (installato nella partizione di sistema).

• L'FCM del dispositivo dovrebbe riflettere i requisiti dei moduli nella partizione di sistema .
• L'FCM system_ext dovrebbe 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 dovrebbero essere allineati con le modifiche apportate da un OEM al framework 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 nell'FCM del prodotto.

Esempio di file 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 ulteriori dettagli, consulta Ciclo di vita FCM .

Matrice di compatibilità dei prodotti

Il prodotto FCM è un file 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à System_ext

L'FCM system_ext è un file matrice di compatibilità del framework nella partizione system_ext. L'oggetto VINTF unisce l'FCM system_ext con gli FCM nelle partizioni del sistema e del prodotto in fase di esecuzione. Vedere la matrice di compatibilità del prodotto per un file FCM system_ext di esempio.

Matrice di compatibilità dei dispositivi (DCM)

La matrice di compatibilità del dispositivo descrive una serie di requisiti che il dispositivo si aspetta dal framework (requisiti applicati all'avvio e al momento dell'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 "richiesti" possono mancare dal file sorgente nell'albero dei sorgenti di Android e possono essere scritti da assemble_vintf al momento della compilazione. I tag "richiesti" devono essere presenti nei file corrispondenti sul dispositivo.

?xml

Opzionale. Fornisce solo informazioni al parser XML.

compatibility-matrix.version

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

compatibility-matrix.type

Necessario. Tipo di questa matrice di compatibilità:

• "device" : Matrice di compatibilità del dispositivo.
• "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 (versione FCM) di questo file. Non dichiararlo nella matrice di compatibilità del framework specifico del dispositivo (ad esempio DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE ).

compatibility-matrix.hal

Facoltativo e può essere ripetuto. Elenca un singolo HAL (HIDL o nativo) richiesto dal proprietario della matrice di compatibilità (framework o dispositivo). Le voci HAL sono distinte da un elemento <name> ; ci possono essere diverse voci HAL con lo stesso nome (implica la condizione "e").

compatibility-matrix.hal.format

Opzionale. Il valore può essere uno tra:

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

compatibility-matrix.hal.optional

L'attributo è 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 richiede che sia presente.

compatibility-matrix.hal.name

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

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

compatibility-matrix.hal.version

Un elenco di intervalli di versione (vedi corrispondenze HAL ) che definisce quali versioni si aspetta il proprietario della matrice di compatibilità (framework o dispositivo).

Per HIDL e HAL nativi, 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 che eseguono 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ò ripetere. Un elenco delle interfacce richieste di questo HAL.

compatibility-matrix.hal.interface.name

Necessario. Nome dell'interfaccia.

compatibility-matrix.hal.interface.instance

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

compatibility-matrix.hal.interface.regex-instance

Facoltativo, può ripetere. Un elenco di modelli di nomi di istanza richiesti su questa interfaccia. Utilizza il formato Espressione regolare estesa .

compatibility-matrix.kernel

Facoltativo, può ripetere. Specificare un elenco di configurazioni del kernel che il framework richiede su ogni versione del kernel.
Possono esistere più <kernel> con la stessa <version> per implicare la relazione "e". Ogni <kernel> è un "frammento" dei requisiti che sono abilitati solo quando <conditions> sono soddisfatte.

compatibility-matrix.kernel.version

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

Opzionale. Non deve esistere per il primo <kernel> di ogni versione. Specifica un elenco di condizioni. Quando le condizioni sono soddisfatte, i requisiti indicati in questo frammento <kernel> sono abilitati.

compatibility-matrix.kernel.config

Facoltativo, può ripetere. Elenca gli elementi CONFIG che devono corrispondere per questa versione del kernel. Ogni elemento CONFIG è una coppia chiave-valore; gli elementi di configurazione sono distinti per chiave.

compatibility-matrix.kernel.config.key

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

compatibility-matrix.kernel.config.value

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

• string . Le citazioni sono omesse.
• int . Sono accettati valori decimali ed esadecimali (deve iniziare con 0x o 0X) . Interpretato come numero intero a 64 bit; gli overflow provocano il troncamento. (Il parser accetta valori da -2 ⁶⁴ + 1 a 2 ⁶⁴ - 1, il 65° bit viene troncato; per i dettagli fare riferimento alla pagina man di strtoull .)
• range . Il formato è [int]-[int] , ad esempio 10-20 . I valori esadecimali sono accettati e devono iniziare con 0x o 0X . Due limiti devono essere un numero intero senza segno a 64 bit.
• tristate . I valori validi sono y , m e n .

compatibility-matrix.kernel.config.value.type

Necessario. Tipo del valore dell'elemento CONFIG , uno tra:

• string
• int
• range
• tristate

compatibility-matrix.sepolicy

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

compatibility-matrix.sepolicy.sepolicy-version

Richiesto, può ripetere. Descrive il requisito sulla versione sepolicy. Corrisponde a manifest.sepolicy.version . Ogni istanza di un elemento definisce un intervallo di versioni di sepolicy.

compatibility-matrix.sepolicy.kernel-sepolicy-version

Necessario. Dichiara la versione policydb con cui funziona il framework.

compatibility-matrix.avb.vbmeta-version

Opzionale; utilizzato solo dalla matrice di compatibilità del framework. Dichiara la versione AVB usata per firmare system.img . Deprecato in Android 10.

compatibility-matrix.vendor-ndk

Opzionale; utilizzato solo dalla matrice di compatibilità del dispositivo. Dichiara il requisito dello snapshot del fornitore VNDK. Se mancante, non viene effettuato alcun requisito VNDK sull'immagine di sistema.

compatibility-matrix.vendor-ndk.version

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

compatibility-matrix.vendor-ndk.library

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

compatibility-matrix.system-sdk.version

Facoltativo, può ripetere; utilizzato solo dalla matrice di compatibilità del dispositivo. Dichiara il requisito delle app del fornitore nelle versioni dell'SDK di sistema. Se mancante, non viene richiesto alcun SDK di sistema sull'immagine di sistema.