Google is committed to advancing racial equity for Black communities. See how.
Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

Regole di corrispondenza

Le due coppie di matrici e manifesti di compatibilità devono essere riconciliate per verificare che il framework e l'implementazione del fornitore possano funzionare l'uno con l'altro. Questa verifica ha esito positivo su una corrispondenza tra la matrice di compatibilità del framework e il manifesto del dispositivo, nonché tra il manifesto del framework e la matrice di compatibilità del dispositivo.

Questa verifica viene eseguita in fase di compilazione, in fase di generazione del pacchetto di aggiornamento OTA , in fase di avvio e nei test di compatibilità VTS.

Le sezioni seguenti descrivono in dettaglio le regole di corrispondenza utilizzate dai vari componenti.

La versione della matrice di compatibilità del framework corrisponde

Per abbinare un manifest del dispositivo a una matrice di compatibilità del framework, la versione di FCM di spedizione specificata da manifest.target-level deve essere esattamente uguale alla versione di FCM specificata da compatibility-matrix.level . Altrimenti non c'è corrispondenza.

Quando la matrice di compatibilità del framework viene richiesta con libvintf , questa corrispondenza ha sempre successo perché libvintf apre il manifest del dispositivo, recupera la versione di FCM di spedizione e restituisce la matrice di compatibilità del framework a quella versione di FCM di spedizione (più alcuni HAL opzionali dalle matrici di compatibilità a FCM più alto Versioni).

Corrispondenze HAL

La regola di corrispondenza HAL identifica le versioni degli elementi hal in un file manifest che sono considerate supportate dal proprietario della matrice di compatibilità corrispondente.

  • Più elementi <hal> vengono valutati con una singola relazione AND .
  • Più elementi <version> all'interno dello stesso <hal> hanno la relazione OR . Se vengono specificati due o più, è necessario implementare solo una delle versioni. (Vedere l' esempio DRM di seguito.)
  • Più elementi <instance> e <regex-instance> all'interno dello stesso <hal> vengono valutati con una singola relazione AND . (Vedere l' esempio DRM di seguito.)

Esempio: corrispondenza HAL riuscita per il modulo fotocamera

Per un HAL alla versione 2.5, la regola di corrispondenza è la seguente:

Matrice Manifest corrispondente
2.5 2.5-2.∞. Abbreviazione di 2.5-5.
2.5-7 2.5-2.∞. Indica quanto segue:
  • 2.5 è la versione minima richiesta, il che significa che un manifest che fornisce HAL 2.0-2.4 non è compatibile.
  • 2.7 è la versione massima che può essere richiesta, il che significa che il proprietario della matrice di compatibilità (framework o dispositivo) non richiederà versioni successive alla 2.7. Il proprietario del file manifest corrispondente può ancora fornire la versione 2.10 (come esempio) quando viene richiesta la 2.7. Il proprietario della matrice di compatibilità sa solo che il servizio richiesto è compatibile con la versione API 2.7.
  • -7 è solo informativo e non influisce sul processo di aggiornamento OTA.
Pertanto, un dispositivo con un HAL alla versione 2.10 nel suo file manifest rimane compatibile con un framework che afferma camera: 2.5-7 nella sua matrice di compatibilità.

Esempio: corrispondenza HAL riuscita per il modulo DRM

La matrice di compatibilità del framework indica le seguenti informazioni sulla versione per DRM HAL:

<hal>
    <name>android.hardware.drm
    <version>1.0</version>
    <version>3.1-2</version>
    <interface>
        <name>IDrmFactory</name>
        <instance>default</instance>
        <instance>specific</instance>
    </interface>
</hal>
<hal>
    <name>android.hardware.drm
    <version>2.0</version>
    <interface>
        <name>ICryptoFactory</name>
        <instance>default</instance>
        <regex-instance>[a-z]+/[0-9]+</regex-instance>
    </interface>
</hal>

Un fornitore deve implementare UNA delle seguenti istanze; o

android.hardware.drm@1.x::IDrmFactory/default          // where x >= 0
android.hardware.drm@1.x::IDrmFactory/specific         // where x >= 0
OPPURE
android.hardware.drm@3.y::IDrmFactory/default          // where y >= 1
android.hardware.drm@3.y::IDrmFactory/specific         // where y >= 1

E deve anche implementare tutte queste istanze:

android.hardware.drm@2.z::ICryptoFactory/default       // where z >= 0
android.hardware.drm@2.z::ICryptoFactory/${INSTANCE}
            // where z >= 0 and ${INSTANCE} matches [a-z]+/[0-9]+
            // e.g. legacy/0

Corrispondenze del kernel

La sezione <kernel> della matrice di compatibilità del framework descrive i requisiti del framework del kernel Linux sul dispositivo. Queste informazioni devono essere confrontate con le informazioni sul kernel che vengono riportate dall'oggetto VINTF del dispositivo.

Abbina i rami del kernel

Ogni suffisso del ramo del kernel (ad esempio, 5.4- r ) è mappato a una versione FCM del kernel univoca (ad esempio, 5). La mappatura è la stessa della mappatura tra le lettere di rilascio (ad esempio, R) e le versioni FCM (ad esempio, 5).

I test VTS impongono che il dispositivo specifichi esplicitamente la versione FCM del kernel nel manifesto del dispositivo, /vendor/etc/vintf/manifest.xml , se una delle seguenti condizioni è vera:

  • La versione FCM del kernel è diversa dalla versione FCM di destinazione. Ad esempio, il dispositivo di cui sopra ha una versione FCM di destinazione 4 e la versione FCM del kernel è 5 (suffisso del ramo del kernel r ).
  • La versione FCM del kernel è maggiore o uguale a 5 (suffisso del ramo del kernel r ).

I test VTS impongono che, se viene specificata la versione FCM del kernel, la versione FCM del kernel è maggiore o uguale alla versione FCM di destinazione nel manifesto del dispositivo.

Esempio: determinare il ramo del kernel

Se il dispositivo ha la versione 4 di FCM di destinazione (rilasciata in Android 10), ma esegue il kernel dal ramo 4.19-r , il manifesto del dispositivo deve specificare quanto segue:

<manifest version="2.0" type="device" target-level="4">
   <kernel target-level="5" />
</manifest>

L'oggetto VINTF verifica la compatibilità del kernel con i requisiti sul ramo del kernel 4.19-r , che è specificato nella versione 5 di FCM. Questi requisiti sono compilati da kernel/configs/r/android-4.19 nell'albero dei sorgenti di Android.

Abbina le versioni del kernel

Una matrice può includere più sezioni <kernel> , ciascuna con un diverso attributo di version utilizzando il formato:

${ver}.${major_rev}.${kernel_minor_rev}

L'oggetto VINTF considera solo la sezione <kernel> dell'FCM con la versione FCM corrispondente con gli stessi ${ver} e ${major_rev} del kernel del dispositivo (cioè, version="${ver}.${major_rev}.${matrix_minor_rev}") ; altre sezioni vengono ignorate. Inoltre, la revisione minore del kernel deve essere un valore della matrice di compatibilità ( ${kernel_minor_rev} >= ${matrix_minor_rev} ;). Se nessuna sezione <kernel> soddisfa questi requisiti, è una non corrispondenza.

Esempio: selezionare i requisiti per la corrispondenza

Considera il seguente caso ipotetico in cui gli FCM in /system/etc/vintf dichiarano i seguenti requisiti (i tag di intestazione e piè di pagina sono omessi):

<!-- compatibility_matrix.3.xml -->
<kernel version="4.4.107" level="3"/>
<!-- See kernel/configs/p/android-4.4/ for 4.4-p requirements -->
<kernel version="4.9.84" level="3"/>
<!-- See kernel/configs/p/android-4.9/ for 4.9-p requirements -->
<kernel version="4.14.42" level="3"/>
<!-- See kernel/configs/p/android-4.14/ for 4.14-p requirements -->

<!-- compatibility_matrix.4.xml -->
<kernel version="4.9.165" level="4"/>
<!-- See kernel/configs/q/android-4.9/ for 4.9-q requirements -->
<kernel version="4.14.105" level="4"/>
<!-- See kernel/configs/q/android-4.14/ for 4.14-q requirements -->
<kernel version="4.19.42" level="4"/>
<!-- See kernel/configs/q/android-4.19/ for 4.19-q requirements -->

<!-- compatibility_matrix.5.xml -->
<kernel version="4.14.180" level="5"/>
<!-- See kernel/configs/r/android-4.14/ for 4.14-r requirements -->
<kernel version="4.19.123" level="5"/>
<!-- See kernel/configs/r/android-4.19/ for 4.19-r requirements -->
<kernel version="5.4.41" level="5"/>
<!-- See kernel/configs/r/android-5.4/ for 5.4-r requirements -->

La versione FCM di destinazione, la versione FCM del kernel e la versione del kernel insieme selezionano i requisiti del kernel dagli FCM:

Versione FCM di destinazione Versione FCM del kernel Versione del kernel Abbina con
3 (P) non specificato 4.4.106 Nessuna corrispondenza (mancata corrispondenza della versione minore)
3 (P) non specificato 4.4.107 4.4-p
3 (P) non specificato 4.19.42 4.19-q (vedi nota sotto)
3 (P) non specificato 5.4.41 5.4-r (vedi nota sotto)
3 (P) 3 (P) 4.4.107 4.4-p
3 (P) 3 (P) 4.19.42 Nessuna corrispondenza (nessun ramo del kernel 4.19-p )
3 (P) 4 (Q) 4.19.42 4.19-q
4 (Q) non specificato 4.4.107 Nessuna corrispondenza (nessun ramo del kernel 4.4-q )
4 (Q) non specificato 4.9.165 4.9-q
4 (Q) non specificato 5.4.41 5.4-r (vedi nota sotto)
4 (Q) 4 (Q) 4.9.165 4.9-q
4 (Q) 4 (Q) 5.4.41 Nessuna corrispondenza (nessun ramo del kernel 5.4-q )
4 (Q) 5 (R) 4.14.105 4.14-r
4 (Q) 5 (R) 5.4.41 5.4-r
5 (R) non specificato qualunque VTS non riesce (è necessario specificare la versione FCM del kernel per la versione 5 di FCM di destinazione)
5 (R) 4 (Q) qualunque VTS non riesce (versione FCM kernel <versione FCM di destinazione)
5 (R) 5 (R) 4.14.180 4.14-r

Abbina le configurazioni del kernel

Se la sezione <kernel> corrisponde, il processo continua cercando di confrontare gli elementi di config con /proc/config.gz . Per ogni elemento di configurazione nella matrice di compatibilità, cerca /proc/config.gz per vedere se la configurazione è presente. Quando un elemento di configurazione è impostato su n nella matrice di compatibilità per la sezione <kernel> corrispondente, deve essere assente da /proc/config.gz . Infine, un elemento di configurazione non nella matrice di compatibilità può o non può essere presente in /proc/config.gz .

Esempio: corrispondenza delle configurazioni del kernel

  • <value type="string">bar</value> corrisponde a "bar" . Le virgolette sono omesse nella matrice di compatibilità ma sono presenti in /proc/config.gz .
  • <value type="int">4096</value> corrisponde a 4096 o 0x1000 o 0X1000 .
  • <value type="int">0x1000</value> corrisponde a 4096 o 0x1000 o 0X1000 .
  • <value type="int">0X1000</value> corrisponde a 4096 o 0x1000 o 0X1000 .
  • <value type="tristate">y</value> corrisponde a y .
  • <value type="tristate">m</value> corrisponde a m .
  • <value type="tristate">n</value> significa che l'elemento di configurazione NON deve esistere in /proc/config.gz .
  • <value type="range">1-0x3</value> corrisponde a 1 , 2 o 3 o equivalente esadecimale.

Esempio: corrispondenza del kernel riuscita

Una matrice di compatibilità del framework con FCM versione 1 contiene le seguenti informazioni sul kernel:

<kernel version="4.14.42">
   <config>
      <key>CONFIG_TRI</key>
      <value type="tristate">y</value>
   </config>
   <config>
      <key>CONFIG_NOEXIST</key>
      <value type="tristate">n</value>
   </config>
   <config>
      <key>CONFIG_DEC</key>
      <value type="int">4096</value>
   </config>
   <config>
      <key>CONFIG_HEX</key>
      <value type="int">0XDEAD</value>
   </config>
   <config>
      <key>CONFIG_STR</key>
      <value type="string">str</value>
   </config>
   <config>
      <key>CONFIG_EMPTY</key>
      <value type="string"></value>
   </config>
</kernel>

Il ramo del kernel viene abbinato per primo. Il ramo del kernel è specificato nel manifesto del dispositivo in manifest.kernel.target-level , che per impostazione predefinita è manifest.level se il primo non è specificato. Se il ramo del kernel nel manifesto del dispositivo:

  • è 1, procede al passaggio successivo e controlla la versione del kernel.
  • è 2, nessuna corrispondenza con matrix. Gli oggetti VINTF leggono invece i requisiti del kernel dalla matrice nella versione 2 di FCM.

Quindi, la versione del kernel viene abbinata. Se un dispositivo in uname() segnala:

  • 4.9.84 (nessuna corrispondenza con matrix a meno che non ci sia una sezione kernel separata con <kernel version="4.9.x"> , dove x <= 84 )
  • 4.14.41 (nessuna corrispondenza con la matrice, inferiore alla version )
  • 4.14.42 (abbina a matrice)
  • 4.14.43 (abbina a matrice)
  • 4.1.22 (nessuna corrispondenza con matrix a meno che non ci sia una sezione kernel separata con <kernel version="4.1.x"> dove x <= 22 )

Dopo aver selezionato la sezione <kernel> appropriata, per ogni elemento <config> con valore diverso da n , ci aspettiamo che la voce corrispondente sia presente in /proc/config.gz ; per ogni elemento <config> con valore n , ci aspettiamo che la voce corrispondente non sia presente in /proc/config.gz . Ci aspettiamo che il contenuto di <value> corrisponda esattamente al testo dopo il segno di uguale (comprese le virgolette), fino al carattere di nuova riga o # , con gli spazi bianchi iniziali e finali troncati.

La seguente configurazione del kernel è un esempio di una corrispondenza riuscita:

# comments don't matter
CONFIG_TRI=y
# CONFIG_NOEXIST shouldn't exist
CONFIG_DEC = 4096 # trailing comments and whitespaces are fine
CONFIG_HEX=57005  # 0XDEAD == 57005
CONFIG_STR="str"
CONFIG_EMPTY=""   # empty string must have quotes
CONFIG_EXTRA="extra config items are fine too"

La seguente configurazione del kernel è un esempio di una corrispondenza non riuscita:

CONFIG_TRI="y"   # mismatch: quotes
CONFIG_NOEXIST=y # mismatch: CONFIG_NOEXIST exists
CONFIG_HEX=0x0   # mismatch; value doesn't match
CONFIG_DEC=""    # mismatch; type mismatch (expect int)
CONFIG_EMPTY=1   # mismatch; expects ""
# mismatch: CONFIG_STR is missing

Conformità alla politica SE

La politica SE richiede le seguenti corrispondenze:

  • <sepolicy-version> definisce un intervallo chiuso di versioni secondarie per ogni versione principale. La versione separata segnalata dal dispositivo deve rientrare in uno di questi intervalli per essere compatibile con il framework. Le regole di corrispondenza sono simili alle versioni HAL; è corrispondenza se la versione sepolicy è superiore o uguale alla versione minima per la gamma. La versione massima è puramente informativa.
  • <kernel-sepolicy-version> cioè versione policydb. Deve essere inferiore al security_policyvers() riportato dal dispositivo.

Esempio: corretta corrispondenza della politica SE

La matrice di compatibilità del framework riporta le seguenti informazioni separate:

<sepolicy>
    <kernel-sepolicy-version>30</kernel-sepolicy-version>
    <sepolicy-version>25.0</sepolicy-version>
    <sepolicy-version>26.0-3</sepolicy-version>
</sepolicy>

Sul dispositivo:

  • Il valore restituito da security_policyvers() deve essere maggiore o uguale a 30. Altrimenti non è una corrispondenza. Per esempio:
    • Se un dispositivo restituisce 29, non è una corrispondenza.
    • Se un dispositivo restituisce 31, è una corrispondenza.
  • La versione della policy SE deve essere una tra 25.0-∞ o 26.0-∞. Altrimenti non è una corrispondenza. (Il " -3 " dopo " 26.0 " è puramente informativo.)

La versione di AVB corrisponde

La versione AVB contiene una versione MAJOR e una versione MINOR, con il formato MAJOR.MINOR (ad esempio 1.0, 2.1). Per i dettagli, fare riferimento a Controllo delle versioni e compatibilità . La versione AVB ha le seguenti proprietà di sistema:

  • ro.boot.vbmeta.avb_version è la versione di libavb nel bootloader
  • ro.boot.avb_version è la versione di libavb nel sistema operativo Android ( init/fs_mgr )

La proprietà di sistema appare solo quando il libavb corrispondente è stato utilizzato per verificare i metadati AVB (e restituisce OK). È assente se si è verificato un errore di verifica (o non si è verificata affatto).

Una corrispondenza di compatibilità confronta quanto segue:

  • sysprop ro.boot.vbmeta.avb_version con avb.vbmeta-version dalla matrice di compatibilità del framework;
    • ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR
    • ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR
  • sysprop ro.boot.avb_version con avb.vbmeta-version dalla matrice di compatibilità del framework.
    • ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR
    • ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR

Il bootloader o il sistema operativo Android potrebbe contenere due copie delle librerie libavb , ciascuna con una diversa versione MAJOR per dispositivi di aggiornamento e dispositivi di avvio. In questo caso, la stessa immagine di sistema non firmata può essere condivisa ma le immagini di sistema firmate finali sono diverse (con una avb.vbmeta-version diversa):

Figura 1. La versione di AVB corrisponde ( /system è P, tutte le altre partizioni sono O).


Figura 2. Corrispondenza della versione di AVB (tutte le partizioni sono P).

Esempio: corrispondenza della versione AVB riuscita

La matrice di compatibilità del framework riporta le seguenti informazioni AVB:

<avb>
    <vbmeta-version>2.1</vbmeta-version>
</avb>

Sul dispositivo:

ro.boot.avb_version              == 1.0 &&
ro.boot.vbmeta.avb_version       == 2.1  mismatch 
ro.boot.avb_version              == 2.1 &&
ro.boot.vbmeta.avb_version       == 3.0  mismatch 
ro.boot.avb_version              == 2.1 &&
ro.boot.vbmeta.avb_version       == 2.3  match 
ro.boot.avb_version              == 2.3 &&
ro.boot.vbmeta.avb_version       == 2.1  match 

Corrispondenza della versione AVB durante OTA

Per i dispositivi lanciati con Android 9 o inferiore, durante l'aggiornamento ad Android 10, i requisiti della versione AVB nella matrice di compatibilità del framework vengono confrontati con la versione AVB corrente sul dispositivo. Se la versione AVB ha un aggiornamento della versione principale durante un OTA (ad esempio, da 0.0 a 1.0), il controllo VINTF per la compatibilità in OTA non riflette la compatibilità dopo l'OTA.

Per mitigare il problema, un OEM può inserire una versione falsa di AVB nel pacchetto OTA ( compatibility.zip ) per superare il controllo. Fare così:

  1. Scegli i seguenti CL nell'albero dei sorgenti di Android 9:
  2. Definisci BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE per il dispositivo. Il suo valore dovrebbe essere uguale alla versione AVB prima dell'OTA, ovvero la versione AVB del dispositivo quando è stato lanciato.
  3. Ricostruisci il pacchetto OTA.

Queste modifiche posizionano automaticamente BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE come compatibility-matrix.avb.vbmeta-version nei seguenti file:

  • /system/compatibility_matrix.xml (che non è utilizzato in Android 9) sul dispositivo
  • system_matrix.xml in compatibility.zip nel pacchetto OTA

Queste modifiche non influiscono su altre matrici di compatibilità del framework, incluso /system/etc/vintf/compatibility_matrix.xml . Dopo l'OTA, il nuovo valore in /system/etc/vintf/compatibility_matrix.xml viene invece utilizzato per i controlli di compatibilità.

La versione VNDK corrisponde

La matrice di compatibilità del dispositivo dichiara la versione VNDK richiesta in compatibility-matrix.vendor-ndk.version . Se la matrice di compatibilità del dispositivo non ha un <vendor-ndk> , non vengono imposti requisiti e quindi è sempre considerata una corrispondenza.

Se la matrice di compatibilità del dispositivo ha un <vendor-ndk> , viene <vendor-ndk> una voce <vendor-ndk> con una <version> corrispondente dal set di snapshot del fornitore VNDK fornito dal framework nel manifesto del framework. Se una tale voce non esiste, non c'è corrispondenza.

Se tale voce esiste, il set di librerie enumerato nella matrice di compatibilità del dispositivo deve essere un sottoinsieme del set di librerie indicato nel manifesto del framework; in caso contrario, la voce non è considerata una corrispondenza.

  • In un caso speciale, se nessuna libreria è enumerata nella matrice di compatibilità del dispositivo, la voce è sempre considerata una corrispondenza, perché l'insieme vuoto è un sottoinsieme di qualsiasi insieme.

Esempio: corrispondenza della versione VNDK riuscita

Se la matrice di compatibilità del dispositivo indica il seguente requisito su VNDK:

<!-- Example Device Compatibility Matrix -->
<vendor-ndk>
    <version>27</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
</vendor-ndk>

Nel manifesto del framework, viene considerata solo la voce con la versione 27.

<!-- Framework Manifest Example A -->
<vendor-ndk>
    <version>27</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
    <library>libfoo.so</library>
</vendor-ndk>

L'esempio A è una corrispondenza, perché la versione 27 di VNDK è nel manifesto del framework e {libjpeg.so, libbase.so, libfoo.so} ⊇ {libjpeg.so, libbase.so} .

<!-- Framework Manifest Example B -->
<vendor-ndk>
    <version>26</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
</vendor-ndk>
<vendor-ndk>
    <version>27</version>
    <library>libbase.so</library>
</vendor-ndk>

L'esempio B non è una corrispondenza. Anche se VNDK versione 27 è nel manifesto del framework, libjpeg.so non è supportato dal framework in libjpeg.so . La versione 26 di VNDK viene ignorata.

La versione dell'SDK di sistema corrisponde

La matrice di compatibilità del dispositivo dichiara una serie di versioni di System SDK richieste in compatibility-matrix.system-sdk.version . Esiste una corrispondenza solo se il set è un sottoinsieme delle versioni di System SDK fornite come dichiarato in manifest.system-sdk.version nel manifesto del framework.

  • Come caso speciale, se nessuna versione di System SDK è enumerata nella matrice di compatibilità del dispositivo, è sempre considerata una corrispondenza, perché un set vuoto è un sottoinsieme di qualsiasi set.

Esempio: corrispondenza della versione dell'SDK di sistema riuscita

Se la matrice di compatibilità del dispositivo indica il seguente requisito su System SDK:

<!-- Example Device Compatibility Matrix -->
<system-sdk>
    <version>26</version>
    <version>27</version>
</system-sdk>

Quindi, il framework deve fornire System SDK versione 26 e 27 in modo che corrispondano.

<!-- Framework Manifest Example A -->
<system-sdk>
    <version>26</version>
    <version>27</version>
</system-sdk>

L'esempio A è una corrispondenza.

<!-- Framework Manifest Example B -->
<system-sdk>
    <version>26</version>
    <version>27</version>
    <version>28</version>
</system-sdk>

L'esempio B è una corrispondenza.

<!-- Framework Manifest Example C -->
<system-sdk>
    <version>26</version>
</system-sdk>

L'esempio C non corrisponde, perché la versione 27 di System SDK non è fornita.