Hachage d'interface

Ce document décrit le hachage d'interface HIDL, un mécanisme permettant d'éviter les modifications accidentelles d'interface et de garantir que les modifications d'interface sont minutieusement vérifiées. Ce mécanisme est requis car les interfaces HIDL sont versionnées, ce qui signifie qu'une fois qu'une interface est publiée, elle ne doit pas être modifiée, sauf de manière à préserver l'interface binaire d'application (ABI) (telle qu'une correction de commentaire).

Mise en page

Chaque répertoire racine de package (c'est-à-dire le mappage android.hardware vers hardware/interfaces ou le mappage vendor.foo vers vendor/foo/hardware/interfaces ) doit contenir un fichier current.txt qui répertorie tous les fichiers d'interface HIDL publiés.

# 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

Remarque : Pour vous aider à savoir quels hachages proviennent d'où, Google sépare les fichiers HIDL current.txt en différentes sections : La première section est publiée dans Android O ; la section suivante sera publiée dans Android O MR1 . Nous vous recommandons fortement d'utiliser une mise en page similaire dans votre current.txt .

Hachage avec Hidl-Gen

Vous pouvez ajouter un hachage à un fichier current.txt manuellement ou en utilisant hidl-gen . L'extrait de code suivant fournit des exemples de commandes que vous pouvez utiliser avec hidl-gen pour gérer un fichier current.txt (les hachages ont été raccourcis) :

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

Avertissement : Ne remplacez pas le hachage d'une interface déjà publiée. Lors de la modification d'une telle interface, ajoutez un nouveau hachage à la fin du fichier current.txt . Pour plus de détails, reportez-vous à Stabilité ABI .

Chaque bibliothèque de définition d'interface générée par hidl-gen inclut des hachages, qui peuvent être récupérés en appelant IBase::getHashChain . Lorsque hidl-gen compile une interface, il vérifie le fichier current.txt dans le répertoire racine du package HAL pour voir si le HAL a été modifié :

• Si aucun hachage pour le HAL n'est trouvé, l'interface est considérée comme inédite (en développement) et la compilation se poursuit.
• Si des hachages sont trouvés, ils sont vérifiés par rapport à l'interface actuelle :
  • Si l'interface correspond au hachage, la compilation se poursuit.
  • Si l'interface ne correspond pas à un hachage, la compilation est interrompue car cela signifie qu'une interface précédemment publiée est en cours de modification.
    • Pour une modification préservant l'ABI (voir Stabilité de l'ABI ), le fichier current.txt doit être modifié avant que la compilation puisse continuer.
    • Toutes les autres modifications doivent être apportées dans une mise à niveau de version mineure ou majeure de l'interface.

Stabilité de l'ABI

Une interface binaire d'application (ABI) inclut les liaisons binaires/conventions d'appel/etc. Si l'ABI/API change, l'interface ne fonctionne plus avec un system.img générique qui a été compilé avec les interfaces officielles.

S'assurer que les interfaces sont versionnées et qu'ABI est stable est crucial pour plusieurs raisons :

• Il garantit que votre implémentation peut réussir le Vendor Test Suite (VTS), ce qui vous met sur la bonne voie pour pouvoir réaliser des OTA uniquement sur le framework.
• En tant qu'OEM, il vous permet de fournir un Board Support Package (BSP) simple à utiliser et conforme.
• Il vous aide à garder une trace des interfaces qui peuvent être publiées. Considérez current.txt comme une carte d'un répertoire d'interfaces qui vous permet de voir l'historique et l'état de toutes les interfaces fournies dans la racine d'un package.

Lorsque vous ajoutez un nouveau hachage pour une interface qui a déjà une entrée dans current.txt , assurez-vous d'ajouter uniquement les hachages qui représentent les interfaces qui maintiennent la stabilité ABI. Examinez les types de modifications suivants :