Schnittstellen und Pakete

HIDL basiert auf Schnittstellen, einem abstrakten Typ, der bei objektorientierten Sprachen definieren, um Verhaltensweisen zu definieren. Jede Schnittstelle ist Teil eines Pakets.

Pakete

Paketnamen können Unterebenen wie package.subpackage haben. Die Stammverzeichnis für veröffentlichte HIDL-Pakete ist hardware/interfaces oder vendor/vendorName (z. B. vendor/google für Pixel) Geräte). Der Paketname bildet ein oder mehrere Unterverzeichnisse unter dem Stamm. Verzeichnis; Alle Dateien, die ein Paket definieren, befinden sich im selben Verzeichnis. Beispiel: package android.hardware.example.extension.light@2.0 wurde gefunden weniger als hardware/interfaces/example/extension/light/2.0.

In der folgenden Tabelle sind Paketpräfixe und -speicherorte aufgeführt:

Paketpräfix Standort Schnittstellentypen
android.hardware.* hardware/interfaces/* HAL
android.frameworks.* frameworks/hardware/interfaces/* Frameworks/ bezogene
android.system.* system/hardware/interfaces/* System
android.hidl.* system/libhidl/transport/* Kern

Das Paketverzeichnis enthält Dateien mit der Erweiterung .hal. Jeden die Datei eine package-Anweisung mit dem Namen des Pakets und Version der Datei. Die Datei types.hal, falls vorhanden, definieren keine Schnittstelle, sondern definiert Datentypen, die für alle im Paket.

Schnittstellendefinition

Abgesehen von types.hal definiert jede andere .hal-Datei eine Schnittstelle. Eine Schnittstelle wird in der Regel so definiert:

interface IBar extends IFoo { // IFoo is another interface
    // embedded types
    struct MyStruct {/*...*/};

    // interface methods
    create(int32_t id) generates (MyStruct s);
    close();
};

Eine Schnittstelle ohne explizite extends-Deklaration implizit geht von android.hidl.base@1.0::IBase aus (ähnlich java.lang.Object in Java.) Die IBase-Schnittstelle, implizit importiert, deklariert mehrere reservierte Methoden, die nicht in benutzerdefinierten Benutzeroberflächen deklariert oder anderweitig verwendet werden. Diese Methoden umfassen:

  • ping
  • interfaceChain
  • interfaceDescriptor
  • notifySyspropsChanged
  • linkToDeath
  • unlinkToDeath
  • setHALInstrumentation
  • getDebugInfo
  • debug
  • getHashChain

Importvorgang

Die import-Anweisung ist ein HIDL-Mechanismus für den Zugriff auf das Paket Benutzeroberflächen und Typen in einem anderen Paket. Eine import-Anweisung bezieht sich auf zwei Entitäten:

  • Die importing-Entität, die entweder ein Paket oder ein Benutzeroberfläche
  • Die importierte ed Entität, die entweder ein Paket oder ein Benutzeroberfläche

Die importierende Entität wird durch den Standort des import-Anweisung. Wenn sich die Anweisung im types.hal, was importiert wird, ist für das gesamte Paket sichtbar. Dies ist ein Import auf Paketebene. Wenn sich die Anweisung in einem Schnittstellendatei ist die importierende Entität die Schnittstelle selbst. dies ist ein interface-level importieren.

Die importierte Entität wird durch den Wert nach import bestimmt. Keyword. Der Wert muss kein vollständig qualifizierter Name sein. wenn eine Komponente wird es automatisch mit Informationen aus dem aktuellen Paket gefüllt. Für voll qualifizierte Werte werden die folgenden Importfälle unterstützt:

  • Gesamtpaketimporte: Wenn der Wert ein Paketname und ein (siehe unten beschriebene Syntax), dann wird das gesamte Paket in das Entität importieren.
  • Teilimporte: Lautet der Wert: <ph type="x-smartling-placeholder">
      </ph>
    • Eine Schnittstelle, die types.hal des Pakets und diese Schnittstelle sind in die importierende Entität importiert.
    • einer in types.hal definierten UDT, dann wird nur diese UDT in Die importierende Entität (andere Typen in types.hal werden nicht importiert).
  • Nur Typen von Importen: Wenn der Wert die Syntax eines dem oben beschriebenen teilweisen Import, aber mit dem Keyword types eines Schnittstellennamens, nur die UDTs in types.hal der Paket importiert.

Die importierende Entität erhält Zugriff auf eine Kombination aus:

  • Die in types.hal definierten allgemeinen UDTs des importierten Pakets.
  • Die Schnittstellen des importierten Pakets (für einen Import des gesamten Pakets) oder angegebene (für einen teilweisen Import) zum Aufrufen der Daten, wobei Aliasse hinzufügen und/oder von ihnen übernehmen.

Die Importanweisung verwendet die vollständig qualifizierte Syntax für Typnamen zur Bereitstellung des Name und Version des zu importierenden Pakets oder der Schnittstelle:

import android.hardware.nfc@1.0;            // import a whole package
import android.hardware.example@1.0::IQuux; // import an interface and types.hal
import android.hardware.example@1.0::types; // import just types.hal

Schnittstelle übernehmen

Eine Schnittstelle kann eine Erweiterung einer zuvor definierten Schnittstelle sein. Es gibt drei Arten von Erweiterungen:

  • Durch die Schnittstelle können einer anderen Funktionalität unter Einbindung ihrer API Funktionen hinzugefügt werden. unverändert lassen.
  • Ein Paket kann einem anderen Paket Funktionen hinzufügen, indem es seine API enthält unverändert lassen.
  • Interface kann Typen aus einem Paket oder aus einer bestimmten Schnittstelle importieren.

Eine Schnittstelle kann nur eine andere Schnittstelle erweitern (keine mehrfache Übernahme). Jede Schnittstelle in einem Paket mit einer Nebenversionsnummer ungleich null muss eine in der vorherigen Version des Pakets. Wenn z. B. eine Schnittstelle IBar in Version 4.0 des Pakets derivative basiert auf (erweitert) eine Schnittstelle IFoo in Version 1.2 des Pakets original und eine Version 1.3 des Pakets original ist erstellt, IBar Version 4.1 kann Version 1.3 von nicht erweitern IFoo Stattdessen muss IBar-Version 4.1 IBar Version 4.0, die an IFoo Version 1.2 gebunden ist. IBar Version 5.0 könnte die IFoo Version 1.3 erweitern, wenn erwünscht ist.

Schnittstellenerweiterungen implizieren keine Bibliotheksabhängigkeit oder HAL-übergreifende Einbeziehung in den generierten Code ein – sie importieren einfach die Datenstruktur und -methode auf HIDL-Ebene. Jede Methode in einem HAL muss so implementiert werden, HAL.

Anbietererweiterungen

In einigen Fällen werden Anbietererweiterungen als Unterklasse der Basisobjekt, das die Kernschnittstelle darstellt, die sie erweitert. Das gleiche Objekt ist unter dem Basisnamen und der HAL-Version sowie unter der (Anbieter) HAL-Name und -Version.

Versionsverwaltung

Pakete sind versioniert und Schnittstellen haben die Version ihres Pakets. Versionen werden in zwei Ganzzahlen ausgedrückt: Hauptversion.Nebenversion.

  • Hauptversionen sind nicht abwärtskompatibel. Wird erhöht Die Hauptversionsnummer setzt die Nebenversionsnummer auf 0 zurück.
  • Nebenversionen sind abwärtskompatibel. Das Erhöhen der Minor-Nummer bedeutet, dass die neuere Version vollständig abwärtskompatibel mit dem vorherigen Version. Es können neue Datenstrukturen und Methoden hinzugefügt werden, vorhandene oder Methodensignaturen geändert werden.

Auf einem Gerät können mehrere Haupt- oder Nebenversionen einer HAL vorhanden sein gleichzeitig. Eine Nebenversion sollte jedoch einer Hauptversion vorgezogen werden. da Clientcode, der mit einer früheren Nebenversionsoberfläche funktioniert, funktioniert auch mit späteren Nebenversionen dieser Schnittstelle. Weitere Informationen Weitere Informationen zur Versionsverwaltung und Anbietererweiterungen finden Sie unter HIDL-Versionsverwaltung:

Übersicht über das Layout der Benutzeroberfläche

In diesem Abschnitt wird zusammengefasst, wie Sie ein HIDL-Schnittstellenpaket (z. B. hardware/interfaces) und fasst die angegebenen Informationen zusammen. im gesamten HIDL-Abschnitt. Machen Sie sich vor dem Lesen mit den HIDL-Versionsverwaltung Hashing mit Hidl-gen-Konzepte, die Details der Arbeit mit HIDL im Allgemeinen und die folgenden Definitionen:

Begriff Definition
Binary Interface (ABI) der Anwendung Application Programming Interface und erforderliche binäre Verknüpfungen.
voll qualifizierter Name (fqName) Name zur Unterscheidung eines Hidl-Typs. Beispiel: android.hardware.foo@1.0::IFoo
Paket Paket mit einer HIDL-Schnittstelle und -Typen. Beispiel: android.hardware.foo@1.0
Paketstamm Stammpaket, das die HIDL-Schnittstellen enthält. Beispiel: die HIDL-Schnittstelle android.hardware befindet sich im Paketstamm android.hardware.foo@1.0.
Root-Pfad des Pakets Speicherort in der Android-Quellstruktur, dem das Paketstammverzeichnis zugeordnet ist.

Weitere Definitionen findest du unter HIDL Terminologie.

Jede Datei ist über die Paketstammzuordnung und voll qualifizierter Name

Paketstammdateien werden für hidl-gen als Argument angegeben -r android.hardware:hardware/interfaces. Wenn zum Beispiel der Parameter Paket ist vendor.awesome.foo@1.0::IFoo und hidl-gen am -r vendor.awesome:some/device/independent/path/interfaces gesendet, dann sollte sich die Datei $ANDROID_BUILD_TOP/some/device/independent/path/interfaces/foo/1.0/IFoo.hal.

In der Praxis wird sie für einen Anbieter oder OEM mit dem Namen awesome empfohlen. ihre Standardschnittstellen in vendor.awesome einzurichten. Nach einem Paket ausgewählt wurde, darf er nicht geändert werden, da dies in das ABI von der Benutzeroberfläche.

Die Paketpfadzuordnung muss eindeutig sein

Beispiel: Sie haben -rsome.package:$PATH_A und -rsome.package:$PATH_B, $PATH_A muss gleich $PATH_B für ein einheitliches Schnittstellenverzeichnis (dadurch ist auch Schnittstellen zur Versionsverwaltung einfacher).

Das Stammverzeichnis des Pakets muss eine Versionsverwaltungsdatei haben

Wenn Sie einen Paketpfad wie -r vendor.awesome:vendor/awesome/interfaces sollten Sie auch die Datei erstellen $ANDROID_BUILD_TOP/vendor/awesome/interfaces/current.txt, die muss Hashes von Schnittstellen enthalten, die mit der Option -Lhash in hidl-gen (wird ausführlich in Hash-Technologie mit „hidl-gen“).

Schnittstellen sind geräteunabhängig Standorte

In der Praxis empfehlen wir die Freigabe von Schnittstellen zwischen Zweigen. Dieses ermöglicht eine maximale Wiederverwendbarkeit des Codes und das maximale Testen von Code über verschiedene Geräte und Anwendungsfälle.