Hash dell'interfaccia

Questo documento descrive l'hashing dell'interfaccia HIDL, un meccanismo per evitare modifiche accidentali all'interfaccia e assicurati che le modifiche apportate all'interfaccia siano attentamente verificate. Questo meccanismo è necessario perché le interfacce HIDL sono soggette al controllo delle versioni, il che significa che dopo il rilascio dell'interfaccia non deve essere modificata che preserva l'ABI (Application Binary Interface, ad esempio un commento) corretta).

Layout

Ogni directory root del pacchetto (ovvero android.hardware con mappatura Mappatura di hardware/interfaces o vendor.foo a vendor/foo/hardware/interfaces) deve contenere un current.txt che elenca tutti i file dell'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 tenere traccia degli hash disponibili da dove, Google separa i file HIDL current.txt in diverse sezioni: la prima sezione viene rilasciata in Android 8; la sezione successiva verrà rilasciato su Android 8 MR1. Ti consigliamo vivamente di utilizzare layout simile nel tuo file current.txt.

Hash con hidl-gen

Puoi aggiungere un hash a un file current.txt manualmente o tramite utilizzando hidl-gen. Il seguente snippet di codice fornisce esempi che puoi utilizzare con hidl-gen per gestire current.txt file (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

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

Ogni libreria di definizione dell'interfaccia generata da hidl-gen include hash, che possono essere recuperati richiamando IBase::getHashChain. Quando hidl-gen compila a riga di comando, controlla il file current.txt nella directory radice il pacchetto HAL per vedere se l'HAL è stato modificato:

  • Se non viene trovato alcun hash per l'HAL, l'interfaccia viene considerata non rilasciata (in sviluppo) e i proventi della compilazione.
  • Se vengono rilevati degli hash, questi vengono confrontati con l'interfaccia corrente:
    • Se l'interfaccia corrisponde all'hash, la compilazione continua.
    • Se l'interfaccia non corrisponde a un hash, la compilazione viene interrotta, perché ciò significa che l'interfaccia rilasciata in precedenza è stata modificata.
      • Per una modifica che tutela l'ABI (vedi stabilità ABI), il file current.txt deve essere modificato prima di procedere con la compilazione.
      • Tutte le altre modifiche devono essere apportate in un upgrade della versione secondaria o principale del a riga di comando.

Stabilità ABI

Un'ABI include il file binario collegamenti/convenzione di chiamata/ecc. Se l'ABI o l'API cambiano, l'interfaccia non lavora più a lungo con un system.img generico compilato con interfacce ufficiali.

Il controllo delle versioni per le interfacce e la stabilità di ABI fondamentali per diversi motivi:

  • Garantisce che l'implementazione superi il Vendor Test Suite (VTS), che ti consente di gestire OTA solo con framework.
  • In qualità di OEM, puoi fornire un Board Support Package (BSP) facile da usare e conforme.
  • Ti aiuta a tenere traccia delle interfacce che possono essere rilasciate. Prendi in considerazione current.txt una mappa di una directory delle interfacce che ti consente di vedere la cronologia e lo stato di tutte le interfacce fornite in una radice pacchetto.

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

Modifiche consentite
  • Modifica di un commento (a meno che non modifichi il significato di un metodo).
  • Modifica del nome di un parametro.
  • Modifica del nome di un parametro restituito.
  • Modifica delle annotazioni.
Modifiche non consentite
  • Riordinare argomenti, metodi e così via
  • Ridenominazione di un'interfaccia o spostamento in un nuovo pacchetto.
  • Ridenominazione di un pacchetto.
  • Aggiungi un campo di metodo/struct e così via. in qualsiasi punto dell'interfaccia.
  • Qualsiasi elemento che potrebbe danneggiare una tabella V++.
  • e così via.