Cette page a été traduite par l'API Cloud Translation.

Hachage d'interface

Ce document décrit le hachage d'interface HIDL, un mécanisme qui empêche les modifications accidentelles de l'interface et s'assurer que celles-ci font l'objet d'un examen approfondi. Ce mécanisme est nécessaire, car les interfaces HIDL ont plusieurs versions, ce qui signifie qu'une fois l'interface publiée, elle ne doit plus être modifiée, sauf dans un de préservation de l'interface binaire d'application (ABI) (comme un commentaire correction).

Mise en page

Chaque répertoire racine du package (c'est-à-dire android.hardware mappé sur Correspondance entre hardware/interfaces ou vendor.foo et vendor/foo/hardware/interfaces) doit contenir un 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 vous aider à identifier les valeurs de hachage Google sépare les fichiers HIDL current.txt en différents La première section s'intitule Disponible sur Android 8. la section suivante sera publiée sur 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 avec hidl-gen. L'extrait de code suivant fournit des exemples que vous pouvez utiliser avec hidl-gen pour gérer 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'un version précédente. Lorsque vous modifiez une interface de ce type, ajoutez un nouveau hachage à la fin du fichier current.txt. Pour en savoir plus, consultez Stabilité de l'ABI.

Chaque bibliothèque de définitions 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 l'interface, elle vérifie le fichier current.txt dans le répertoire racine de le package HAL pour voir si le HAL a été modifié:

Si aucun hachage n'est trouvé pour le HAL, l'interface est considérée comme non publiée (dans développement) et les recettes de la compilation.
Si des hachages sont détectés, ils sont comparés à l'interface actuelle: <ph type="x-smartling-placeholder">
- 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 (consultez Stabilité ABI), le fichier current.txt doivent être modifiées avant que la compilation puisse se poursuivre.
  - Toutes les autres modifications doivent être effectuées dans une mise à niveau mineure ou majeure de la version de commande.

Stabilité de l'ABI

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

S'assurer que les interfaces disposent de versions gérées et que l'ABI est stable crucial pour plusieurs raisons:

Cela garantit que votre mise en œuvre peut passer avec succès la suite de test fournisseur (VTS), ce qui vous met sur la bonne voie pour pouvoir faire des OTA uniquement sur le framework.
En tant qu'OEM, vous pouvez proposer simples à utiliser et conformes.
Elle vous aide à garder une trace des interfaces qui peuvent être publiées. Envisagez d'utiliser current.txt est un mappage d'un répertoire d'interfaces qui vous permet d'afficher l'historique et l'état de toutes les interfaces fournies dans une racine de package.

Lors de l’ajout d’un nouveau hachage pour une interface qui a déjà une entrée dans current.txt, veillez à n'ajouter que les hachages qui représentent qui préservent la stabilité de l'ABI. Examinez les types de modifications suivants:

Modifications autorisées	Modification d'un commentaire (sauf si cela modifie la signification d'une méthode) Modifier le nom d'un paramètre Modification du nom d'un paramètre de retour. Modification des annotations...
Modifications non autorisées	Réorganisation des arguments, des méthodes, etc. Renommer une interface ou la déplacer vers un nouveau package Modification du nom d'un package. Ajouter un champ de méthode/struct, etc. n'importe où dans l'interface. Tout ce qui pourrait perturber un vtable C++. etc.