Android Automotive »

HAL Interface Definition Language

HIDL specifies the interface between a HAL and its users. HIDL is intended to be used for inter-process communication (IPC). Communication between processes is referred to as Binderized. As of Android 10, HIDL is deprecated and Android is migrating to use AIDL everywhere.

#android #hidl

Last update: 2022-07-14

Table of Content

HIDL#

HIDL specifies data structures and method signatures, organized in interfaces (similar to a class) that are collected into packages. HIDL is intended to be used for inter-process communication (IPC), between the HAL and its users. As of Android 10, HIDL is deprecated and Android is migrating to use AIDL everywhere.

HIDL supports two ways to transfer data without using an RPC call: shared memory and a Fast Message Queue (FMQ).

To update devices running earlier versions of Android to Android O, you can wrap both Conventional and Legacy HALs in a new HIDL interface that serves the HAL in Passthrough and Binderized modes. This wrapping is transparent to both the HAL and the Android framework.

You can refer to Conventional HAL or Binderized HAL to see the changes in actual framework stack, such as:

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

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.invcase.passthrough@1.0 could be found under hardware/interfaces/invase/passthrough/1.0.

The following table lists package prefixes and locations:

Package Prefix	Location Interface	Types
`android.hardware.*`	`hardware/interfaces/*`	HAL
`android.frameworks.*`	`frameworks/hardware/interfaces/*`	frameworks related
`android.system.*`	`system/hardware/interfaces/*`	system related
`android.hidl.*`	`system/libhidl/transport/*`	core

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.

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 number 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.

Multiple major or minor versions of a HAL can be present on a device simultaneously. However, a minor version should be preferred over a major version because client code that works with a previous minor version interface will also work with later minor versions of that same interface.

Interface#

Aside from types.hal, every other .hal file defines an interface. 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 will implicitly extend from the class android.hidl.base@1.0::IBase (similar to the java.lang.Object in Java).

The IBase interface, implicitly imported, declares several reserved methods that should not and cannot be re-declared in user-defined interfaces or used otherwise. These methods include:

ping
interfaceChain
interfaceDescriptor
notifySyspropsChanged
linkToDeath
unlinkToDeath
setHALInstrumentation
getDebugInfo
debug
getHashChain

Import#

The import statement is HIDL mechanism to access package interfaces and types in another 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.
- A 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.

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

Inheritance#

An interface can be an extension of a previously-defined interface. An interface can extend only one other interface (no multiple inheritance).

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.

Each interface in a package with a non-zero minor version number must extend an interface in the previous version of the package.

derivative.IBar@4.0 extends original.IFoo@1.2.
derivative.IBar@4.1 CANNOT extend original.IFoo@1.3.
derivative.IBar@4.1 MUST extend derivative.IBar@4.0.
derivative.IBar@5.0 CAN extend original.IFoo@1.3.