Dieses Dokument beschreibt HIDL-Schnittstellen-Hashing, einen Mechanismus, der versehentliche Schnittstellenänderungen verhindert und sicherstellt, dass Schnittstellenänderungen gründlich überprüft werden. Dieser Mechanismus ist erforderlich, da HIDL-Schnittstellen versioniert sind. Dies bedeutet, dass eine Schnittstelle nach der Veröffentlichung nicht mehr geändert werden darf, außer in einer ABI-erhaltenden Weise (z. B. durch eine Kommentarkorrektur).
Layout
Jedes Paketstammverzeichnis (z. B. android.hardware Zuordnung zu hardware/interfaces oder vendor.foo Zuordnung zu vendor/foo/hardware/interfaces ) muss eine current.txt Datei enthalten, die alle veröffentlichten HIDL-Schnittstellendateien auflistet.
# 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: Um den Überblick darüber zu behalten, welche Hashes von wo stammen, unterteilt Google die HIDL-Dateien current.txt in verschiedene Abschnitte: Der erste Abschnitt ist „Released in Android O“ ; Der nächste Abschnitt wird in Android O MR1 veröffentlicht . Wir empfehlen dringend, in Ihrer current.txt Datei ein ähnliches Layout zu verwenden.
Hashing mit Hidl-Gen
Sie können einer current.txt Datei manuell oder mithilfe hidl-gen einen Hash hinzufügen. Der folgende Codeausschnitt 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::types9626fd18...f9d298a6 vendor.awesome.nfc@1.0::typeshidl-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::INfc07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfchidl-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.09626fd18...f9d298a6 vendor.awesome.nfc@1.0::types 07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallbackhidl-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 Schnittstelle. Wenn Sie eine solche Schnittstelle ändern, fügen Sie am Ende der current.txt Datei einen neuen Hash hinzu. Einzelheiten finden Sie unter ABI-Stabilität .
Jede von hidl-gen generierte Schnittstellendefinitionsbibliothek enthält Hashes, die durch Aufrufen von IBase::getHashChain abgerufen werden können. Wenn hidl-gen eine Schnittstelle kompiliert, überprüft es die Datei current.txt im Stammverzeichnis des HAL-Pakets, um festzustellen, ob die HAL geändert wurde:
- Wenn kein Hash für die HAL gefunden wird, gilt die Schnittstelle als unveröffentlicht (in Entwicklung) und die Kompilierung wird fortgesetzt.
- Wenn Hashes gefunden werden, werden sie mit der aktuellen Schnittstelle verglichen:
- Wenn die Schnittstelle mit dem Hash übereinstimmt, wird die Kompilierung fortgesetzt.
- Wenn die Schnittstelle nicht mit einem Hash übereinstimmt, wird die Kompilierung angehalten, da dies bedeutet, dass eine zuvor veröffentlichte Schnittstelle geändert wird.
- Für eine ABI-erhaltende Änderung (siehe ABI-Stabilität ) muss die Datei
current.txtgeändert werden, bevor die Kompilierung fortgesetzt werden kann. - Alle anderen Änderungen sollten in einem Neben- oder Hauptversions-Upgrade der Schnittstelle vorgenommen werden.
- Für eine ABI-erhaltende Änderung (siehe ABI-Stabilität ) muss die Datei
ABI-Stabilität
Eine Application Binary Interface (ABI) umfasst die binären Verknüpfungen/Aufrufkonventionen usw. Wenn sich die ABI/API ändert, funktioniert die Schnittstelle nicht mehr mit einer generischen system.img , die mit offiziellen Schnittstellen kompiliert wurde.
Es ist aus mehreren Gründen von entscheidender Bedeutung , sicherzustellen, dass die Schnittstellen versioniert und ABI stabil sind:
- Es stellt sicher, dass Ihre Implementierung die Vendor Test Suite (VTS) bestehen kann, was Sie auf den richtigen Weg bringt, reine Framework-OTAs durchzuführen.
- Als OEM können Sie damit ein Board Support Package (BSP) bereitstellen, das einfach zu verwenden und konform ist.
- Es hilft Ihnen, den Überblick darüber zu behalten, welche Schnittstellen freigegeben werden können. Betrachten Sie
current.txtals eine Karte eines Schnittstellenverzeichnisses, die es Ihnen ermöglicht, den Verlauf und den Status aller Schnittstellen anzuzeigen, die in einem Paketstamm bereitgestellt werden.
Wenn Sie einen neuen Hash für eine Schnittstelle hinzufügen, die bereits über einen Eintrag in current.txt verfügt, stellen Sie sicher, dass Sie nur die Hashes hinzufügen, die Schnittstellen darstellen, die die ABI-Stabilität gewährleisten. Überprüfen Sie die folgenden Arten von Änderungen:
| Änderungen erlaubt |
|
|---|---|
| Änderungen nicht zulässig |
|