Interface-Hashing

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

In diesem Dokument wird das HIDL-Interface-Hashing beschrieben, ein Mechanismus, der versehentliche Änderungen an der Benutzeroberfläche verhindert und dafür sorgt, dass Änderungen an der Benutzeroberfläche gründlich geprüft werden. Dieser Mechanismus ist erforderlich, da HIDL-Schnittstellen versioniert sind. Das bedeutet, dass eine Schnittstelle nach der Veröffentlichung nur dann geändert werden darf, wenn die Anwendung Binary Interface (ABI) erhalten bleibt (z. B. Korrektur eines Kommentars).

Layout

Jedes Paketstammverzeichnis (d.h. android.hardware, das auf hardware/interfaces oder vendor.foo, das auf vendor/foo/hardware/interfaces verweist) muss eine current.txt-Datei enthalten, in der alle veröffentlichten HIDL-Interface-Dateien aufgeführt sind.

# 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

Hinweis:Damit Sie besser nachvollziehen können, woher die Hashes stammen, teilt Google HIDL-current.txt-Dateien in verschiedene Abschnitte auf: Der erste Abschnitt ist In Android 8 veröffentlicht, der nächste Abschnitt In Android 8 MR1 veröffentlicht. Wir empfehlen dringend, ein ähnliches Layout in Ihrer current.txt-Datei zu verwenden.

Hash mit hidl-gen

Sie können einer current.txt-Datei manuell oder mit hidl-gen einen Hash hinzufügen. Das folgende Code-Snippet enthält Beispiele für Befehle, die Sie mit hidl-gen zum Verwalten einer current.txt-Datei verwenden können (Hashes wurden gekürzt):

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

Warnung:Ersetzen Sie keinen Hash für eine zuvor veröffentlichte Benutzeroberfläche. Wenn Sie eine solche Benutzeroberfläche ändern, fügen Sie am Ende der Datei current.txt einen neuen Hash hinzu. Weitere Informationen finden Sie unter ABI-Stabilität.

Jede von hidl-gen generierte Bibliothek mit Interfacedefinitionen enthält Hash-Werte, die durch Aufrufen von IBase::getHashChain abgerufen werden können. Wenn hidl-gen eine Benutzeroberfläche kompiliert, wird die Datei current.txt im Stammverzeichnis des HAL-Pakets geprüft, um festzustellen, ob die HAL geändert wurde:

• Wenn kein Hash für die HAL gefunden wird, wird die Benutzeroberfläche als nicht veröffentlicht (in der Entwicklung) betrachtet und die Kompilierung wird fortgesetzt.
• Wenn Hashes gefunden werden, werden sie mit der aktuellen Benutzeroberfläche verglichen:
  • Wenn die Schnittstelle mit dem Hash übereinstimmt, wird die Kompilierung fortgesetzt.
  • Wenn die Benutzeroberfläche nicht mit einem Hash übereinstimmt, wird die Kompilierung angehalten, da eine zuvor veröffentlichte Benutzeroberfläche geändert wird.
    • Bei einer ABI-konformen Änderung (siehe ABI-Stabilität) muss die Datei current.txt geändert werden, bevor die Kompilierung fortgesetzt werden kann.
    • Alle anderen Änderungen sollten bei einem Upgrade auf eine Neben- oder Hauptversion der Benutzeroberfläche vorgenommen werden.

ABI-Stabilität

Ein ABI umfasst die Binärverknüpfungen/Aufrufkonventionen usw. Wenn sich das ABI oder die API ändert, funktioniert die Schnittstelle nicht mehr mit einer generischen system.img, die mit offiziellen Schnittstellen kompiliert wurde.

Es ist aus mehreren Gründen wichtig, dafür zu sorgen, dass Schnittstellen versioniert und das ABI stabil ist:

• So wird sichergestellt, dass Ihre Implementierung die Vendor Test Suite (VTS) bestehen kann. So sind Sie auf dem Weg zu Over-the-air-Aktualisierungen nur über das Framework.
• Als OEM können Sie ein Board-Support-Paket (BSP) bereitstellen, das einfach zu verwenden und konform ist.
• So behalten Sie den Überblick darüber, welche Schnittstellen veröffentlicht werden können. Betrachten Sie current.txt als eine Zuordnung eines Schnittstellenverzeichnisses, mit der Sie den Verlauf und den Status aller Schnittstellen sehen können, die im Paketstamm bereitgestellt werden.

Wenn Sie einen neuen Hash für eine Schnittstelle hinzufügen, für die bereits ein Eintrag in current.txt vorhanden ist, fügen Sie nur die Hashes hinzu, die Schnittstellen darstellen, die die ABI-Stabilität beibehalten. Prüfen Sie die folgenden Arten von Änderungen: