Hashing dell'interfaccia

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questo documento descrive l'hashing dell'interfaccia HIDL, un meccanismo per impedire modifiche accidentali dell'interfaccia e garantire che le modifiche dell'interfaccia vengano sottoposte a un'attenta verifica. Questo meccanismo è necessario perché le interfacce HIDL sono versionate, il che significa che, dopo il rilascio di un'interfaccia, non deve essere modificata, tranne che in un modo che preservo l'interfaccia binaria dell'applicazione (ABI) (ad esempio una correzione di un commento).

Layout

Ogni directory principale del pacchetto (ad es. mappatura di android.hardware a hardware/interfaces o mappatura di vendor.foo a vendor/foo/hardware/interfaces) deve contenere un current.txt file che elenca tutti i file di interfaccia HIDL rilasciati.

# current.txt files support comments starting with a '#' character
# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt

# Each line has a SHA-256 hash followed by the name of an interface.
# They have been shortened in this doc for brevity but they are
# 64 characters in length in an actual current.txt file.
d4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here

# types.hal files are also noted in current.txt files
c84da9f5...f8ea2648 vendor.awesome.foo@1.0::types

# Multiple hashes can be in the file for the same interface. This can be used
# to note how ABI sustaining changes were made to the interface.
# For instance, here is another hash for IFoo:

# Fixes type where "FooCallback" was misspelled in comment on "FooStruct"
822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo

Nota: per aiutarti a tenere traccia della provenienza degli hash, Google separa i file HIDL current.txt in sezioni diverse: la prima sezione è Rilasciati in Android 8; la sezione successiva sarà Rilasciati in Android 8 MR1. Ti consigliamo vivamente di utilizzare un layout simile nel file current.txt.

Hash con hidl-gen

Puoi aggiungere un hash a un file current.txt manualmente o utilizzando hidl-gen. Il seguente snippet di codice fornisce esempi di comandi che puoi utilizzare con hidl-gen per gestire un file current.txt (gli hash sono stati abbreviati):

hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::types
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::INfc
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0 >> vendor/awesome/hardware/interfaces/current.txt

Attenzione:non sostituire un hash per un'interfaccia rilasciata in precedenza. Quando modifichi un'interfaccia di questo tipo, aggiungi un nuovo hash alla fine del file current.txt. Per maggiori dettagli, consulta la sezione Stabilità ABI.

Ogni libreria di definizione dell'interfaccia generata da hidl-gen include hash che possono essere recuperati chiamando IBase::getHashChain. Quando hidl-gen compila un'interfaccia, controlla il file current.txt nella directory principale del pacchetto HAL per verificare se l'HAL è stato modificato:

• Se non viene trovato alcun hash per l'HAL, l'interfaccia è considerata non rilasciata (in sviluppo) e la compilazione procede.
• Se vengono trovati hash, vengono controllati rispetto all'interfaccia corrente:
  • Se l'interfaccia corrisponde all'hash, la compilazione procede.
  • Se l'interfaccia non corrisponde a un hash, la compilazione viene interrotta perché significa che è in corso la modifica di un'interfaccia rilasciata in precedenza.
    • Per una modifica che mantiene l'ABI (vedi Stabilità dell'ABI), il file current.txt deve essere modificato prima che la compilazione possa procedere.
    • Tutte le altre modifiche devono essere apportate in un upgrade di versione minore o maggiore dell'interfaccia.

Stabilità dell'ABI

Un ABI include i link binari/le convenzioni di chiamata/ecc. Se l'ABI o l'API cambia, l'interfaccia non funziona più con un system.img generico compilato con interfacce ufficiali.

Assicurarsi che le interfacce siano versionate e che l'ABI sia stabile è fondamentale per diversi motivi:

• Garantisce che la tua implementazione possa superare la Vendor Test Suite (VTS), il che ti consente di eseguire OTA solo per il framework.
• In qualità di OEM, ti consente di fornire un pacchetto di supporto della scheda (BSP) semplice da utilizzare e conforme.
• Ti aiuta a tenere traccia delle interfacce che possono essere rilasciate. Consideracurrent.txt una mappa di una directory delle interfacce che ti consente di visualizzare la cronologia e lo stato di tutte le interfacce fornite nella directory principale di un pacchetto.

Quando aggiungi un nuovo hash per un'interfaccia che ha già una voce in current.txt, assicurati di aggiungere solo gli hash che rappresentano le interfacce che mantengono la stabilità dell'ABI. Esamina i seguenti tipi di modifiche: