From f16c42333aa6b2de30a344dd68246d4a33d93e7d Mon Sep 17 00:00:00 2001 From: Android Partner Docs Date: Tue, 22 Aug 2017 10:41:24 -0700 Subject: Docs: Changes to source.android.com - 166080694 Devsite localized content from translation request a3d5a7... by Android Partner Docs - 166079245 Remove duplicate TOC entry to oob-users.html. by mheco - 166002955 Update builds for Oreo by Android Partner Docs - 165977566 Fixing bad conversion by hvm - 165977199 Edit links to point to public source files in AOSP. by cqn - 165962883 Add codename to CTS downloads page. by gdimino - 165955117 Integration of O branch into mainline. by gdimino - 165638251 Update July public Android security bulletin to remove QC... by Android Partner Docs - 165638198 Update June public Android security bulletin to remove QC... by Android Partner Docs - 165638174 Update May public Android security bulletin to remove QC ... by Android Partner Docs - 165638096 Update April public Android security bulletin to remove Q... by Android Partner Docs - 165528993 Update to Keymaster 2 and remove requirements language by daroberts - 165511119 Add Bluetooth verification / debug information by cqn - 165491345 Fixed link broken by file rename. by cqn - 165381648 Fixed broken image paths and renamed HCI Requirements file. by cqn - 165365185 Created high-level Bluetooth directory and added HTML ver... by cqn - 165335694 Devsite localized content from translation request 66a39c... by Android Partner Docs - 165246927 Update August 2017 bulletin with CVE-2017-0687 by daroberts PiperOrigin-RevId: 166080694 Change-Id: I2d3a8d77fa6a66c2099f13ba2e864545328fd17a --- en/devices/architecture/hidl/interfaces.html | 228 +++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 en/devices/architecture/hidl/interfaces.html (limited to 'en/devices/architecture/hidl/interfaces.html') diff --git a/en/devices/architecture/hidl/interfaces.html b/en/devices/architecture/hidl/interfaces.html new file mode 100644 index 00000000..a044abde --- /dev/null +++ b/en/devices/architecture/hidl/interfaces.html @@ -0,0 +1,228 @@ + + + Interfaces & Packages + + + + + + + +

HIDL is built around interfaces, an abstract type used in object-oriented +languages to define behaviors. Each interface is part of a package.

+ +

Packages

+ +

Package names can have sublevels such as package.subpackage. The +root directory for published HIDL packages is hardware/interfaces +or vendor/vendorName (e.g. vendor/google for Pixel +devices). The package name forms one or more subdirectories under the root +directory; all files defining a package are in the same directory. For example, +package android.hardware.example.extension.light@2.0 could be found +under hardware/interfaces/example/extension/light/2.0.

+ +

The following table lists package prefixes and locations:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Package PrefixLocation
android.hardware.*hardware/interfaces/*
android.frameworks.*frameworks/hardware/interfaces/*
android.system.*system/hardware/interfaces/*
android.hidl.*system/libhidl/transport/*
+ +

The package directory contains files with extension .hal. Every +file must contain a package statement naming the package and +version the file is part of. The file types.hal, if present, does +not define an interface but instead defines data types accessible to every +interface in the package.

+ +

Interface definition

+

Aside from types.hal, every other .hal file defines +an interface. For example, an interface is typically defined as follows:

+ +
+interface IBar extends IFoo { // IFoo is another interface
+    // embedded types
+    struct MyStruct {/*...*/};
+
+    // interface methods
+    create(int32_t id) generates (MyStruct s);
+    close();
+};
+
+ +

An interface without an explicit extends declaration implicitly +extends from android.hidl.base@1.0::IBase (similar to +java.lang.Object in Java.) The IBase interface, implicitly +imported, declares several reserved methods that should not and cannot be +redeclared in user-defined interfaces or used otherwise. These methods +include:

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

Importing

+

The import statement is HIDL mechanism to access package +interfaces and types in another package. An import statement +concerns itself with two entities:

+ +
    +
  • The importing entity, which can be either a package or an +interface; and
    • +
  • The imported entity, which too can be either a package or an +interface.
    • +
+ +

The importing entity is determined by the location of the +import statement. When the statement is inside a package's +types.hal, what is being imported is visible by the entire package; +this is a package-level import. When the statement is inside an +interface file, the importing entity is the interface itself; this is an +interface-level import.

+ +

The imported entity is determined by the value after the import +keyword. The value need not be a fully-qualified name; if a component is +omitted, it is automatically filled with information from the current package. +For fully-qualified values, the following import cases are supported:

+ +
    +
  • Whole-package imports. If the value is a package name and a +version (syntax described below), then the entire package is imported into the +importing entity.
    • +
  • Partial imports. +
      +
    • If the value is an interface, the package's types.hal and that +interface are imported into the importing entity.
      • +
    • If the value is an UDT defined in types.hal, then only that UDT +is imported into the importing entity (other types in types.hal are +not imported).
      • +
    +
  • Types-only imports. If the value uses the syntax of a +partial import described above, but with the keyword types instead +of an Interface name, only the UDTs in types.hal of the designated +package are imported.
    • +
+ +

The importing entity gets access to a combination of:

+
    +
  • The imported package's common UDTs defined in types.hal;
    • +
  • The imported package's interfaces (for a whole-package import) or specified +interface (for a partial import) for the purposes of invoking them, passing +handles to them and/or inheriting from them.
    • +
+ +

The import statement uses the fully-qualified-type-name syntax to provide the +name and version of the package or interface being imported:

+ +
+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
+
+ +

Interface inheritance

+ +

An interface can be an extension of a previously-defined interface. +Extensions can be one of the following three types:

+
    +
  • Interface can add functionality to another one, incorporating its API +unchanged.
    • +
  • Package can add functionality to another one, incorporating its API +unchanged.
    • +
  • Interface can import types from a package or from a specific interface.
    • +
+ +

An interface can extend only one other interface (no multiple inheritance). +Each interface in a package with a non-zero minor version number must extend an +interface in the previous version of the package. For example, if an interface +IBar in version 4.0 of package derivative is based on +(extends) an interface IFoo in version 1.2 of package +original, and a version 1.3 of package original is +created, IBar version 4.1 cannot extend version 1.3 of +IFoo. Instead, IBar version 4.1 must extend +IBar version 4.0, which is tied to IFoo version 1.2. +IBar version 5.0 could extend IFoo version 1.3, if +desired.

+ +

Interface extensions do not imply library dependence or cross-HAL inclusion +in the generated code—they simply import the data structure and method +definitions at the HIDL level. Every method in a HAL must be implemented in that +HAL.

+ +

Vendor extensions

+

In some cases, vendor extensions will be implemented as a subclass of the +base object that represents the core interface they extend. The same object will +be registered under the base HAL name and version, and under the extension's +(vendor) HAL name and version.

+ + +

Versioning

+

Packages are versioned, and interfaces have the version of their package. +Versions are expressed in two integers, major.minor.

+
    +
  • Major versions are not backwards compatible. Incrementing +the major version number resets the minor version to 0.
    • +
  • Minor versions are backwards compatible. Incrementing the +minor number indicates the newer version is fully backward compatible with the +previous version. New data structures and methods can be added, but no existing +data structures or method signatures may be changed.
    • +
+ +

For broader compatibility with frameworks, multiple major versions of a HAL +can be present on a device simultaneously. While multiple minor versions can +also be present on a device, as minor versions are backwards compatible no +reason exists to support more than the latest minor version for each major +version.

+ +

For more details on versioning and vendor extensions, see +HIDL Versioning.

+ + + -- cgit v1.2.3