Hachage d'interface

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Ce document décrit le hachage d'interface HIDL, un mécanisme permettant d'éviter les modifications accidentelles d'interface et de s'assurer qu'elles sont minutieusement examiné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, application binary interface) (par exemple, en corrigeant un 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 liste 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 suivre les hachages, Google sépare les fichiers current.txt HIDL en différentes sections: la première section est Publiée dans Android 8, la suivante est Publiée dans Android 8 MR1. Nous vous recommandons vivement d'utiliser une mise en page similaire dans votre fichier current.txt.

Hachage avec hidl-gen

Vous pouvez ajouter un hachage à un fichier current.txt manuellement ou à l'aide de 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 un hachage pour une interface publiée précédemment. Lorsque vous modifiez une telle interface, ajoutez un nouveau hachage à la fin du fichier current.txt. Pour en savoir plus, consultez la section Stabilité de l'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 non publiée (en cours de développement) et la compilation se poursuit.
• Si des hachages sont détectés, ils sont comparés à 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 modifiée.
    • Pour une modification préservant l'ABI (voir la section Stabilité de l'ABI), le fichier current.txt doit être modifié avant que la compilation puisse commencer.
    • Toutes les autres modifications doivent être apportées lors d'une mise à niveau mineure ou majeure de l'interface.

Stabilité des ABI

Une ABI inclut les liaisons binaires/les conventions d'appel/etc. Si l'ABI ou l'API change, l'interface ne fonctionne plus avec un system.img générique compilé avec des interfaces officielles.

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

• Il garantit que votre implémentation peut passer la suite de tests du fournisseur (VTS), ce qui vous permet de pouvoir effectuer des OTA uniquement pour le framework.
• En tant qu'OEM, vous pouvez fournir un package de support de carte (BSP) simple à utiliser et conforme.
• Il vous permet de suivre les interfaces pouvant ê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 hachage pour une interface qui comporte déjà une entrée dans current.txt, veillez à n'ajouter que les hachages qui représentent les interfaces qui maintiennent la stabilité de l'ABI. Examinez les types de modifications suivants: