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 dell'FCM devono essere soddisfatti dal manifest del dispositivo (requisiti applicati in fase di compilazione, runtime e in VTS).

L'FCM system_ext e l'FCM del prodotto sono complementari all'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 dovrebbe riflettere i requisiti dei moduli nella partizione del prodotto .

Tutti gli FCM dovrebbero essere in linea 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 di 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, vedere Ciclo di vita FCM .

Matrice di compatibilità del prodotto

L'FCM del prodotto è un file di 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 di 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 runtime. Consulta la matrice di compatibilità del prodotto per un esempio di file FCM system_ext.

Matrice di compatibilità del dispositivo (DCM)

La matrice di compatibilità del dispositivo descrive una serie di requisiti che il dispositivo si aspetta dal framework (requisiti applicati al momento del lancio 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" potrebbero mancare nel file sorgente nell'albero dei sorgenti Android e scritti da assemble_vintf in fase di 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, sono consentiti file di 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 specifica del dispositivo (ad esempio DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE ).
compatibility-matrix.hal
Facoltativo e può ripetere. Elenca un singolo HAL (HIDL o nativo) richiesto dal proprietario della matrice di compatibilità (framework o dispositivo) per essere presente. Le voci HAL sono distinte da un elemento <name> ; possono esserci più 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" : HAL AIDL . Valido solo sulla matrice di compatibilità meta-versione 2.0.
  • "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 versioni (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ò ripetersi senza duplicati. Il formato è uno dei seguenti:
  • MAJOR . MINOR_MIN - MINOR_MAX
  • MAJOR . MINOR (equivalente a MAJOR . MINOR - MINOR )

Per gli HAL AIDL, non devono essere presenti sui dispositivi che eseguono 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 delle espressioni regolari estese .
compatibility-matrix.kernel
Facoltativo, può ripetere. Specificare un elenco di configurazioni del kernel richieste dal framework su ciascuna versione del kernel.
Possono esistere più <kernel> con la stessa <version> per implicare la relazione "e". Ogni <kernel> è un "frammento" dei requisiti che vengono 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 minore 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 si distinguono per chiave.
compatibility-matrix.kernel.config.key
Necessario. Nome chiave della voce CONFIG . Inizia con CONFIG_ .
compatibility-matrix.kernel.config.value
Necessario. Valore della voce CONFIG . Il formato dipende dal tipo:
  • string . Le virgolette vengono 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 64 + 1 a 2 64 - 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 . Sono accettati valori esadecimali e devono iniziare con 0x o 0X . Due limiti devono essere un numero intero a 64 bit senza segno.
  • tristate . I valori validi sono y , m e n .
compatibility-matrix.kernel.config.value.type
Necessario. Tipo del valore della voce CONFIG , uno tra:
  • string
  • int
  • range
  • tristate
compatibility-matrix.sepolicy
Necessario. Contiene tutte le voci relative alla 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 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 utilizzata 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 i requisiti delle app del fornitore nelle versioni dell'SDK di sistema. Se mancante, non viene effettuato alcun requisito dell'SDK di sistema sull'immagine di sistema.