Android 11 introduces the ability to use AIDL for HALs in Android. This makes it possible to implement parts of Android without HIDL. Transition HALs to use AIDL exclusively where possible (when upstream HALs use HIDL, HIDL must be used).
HALs using AIDL to communicate between framework components, such as those in
system.img
, and hardware components, such as those in vendor.img
, must use
Stable AIDL. However, to communicate within a partition, for instance from one
HAL to another, there's no restriction on the IPC mechanism to use.
Motivation
AIDL has been around longer than HIDL, and is used in many other places, such as between Android framework components or in apps. Now that AIDL has stability support, it's possible to implement an entire stack with a single IPC runtime. AIDL also has a better versioning system than HIDL.
- Using a single IPC language means having only one thing to learn, debug, optimize, and secure.
- AIDL supports in-place versioning for the owners of an interface:
- Owners can add methods to the end of interfaces, or fields to parcelables. This means it's easier to version code over the years, and also the year over year cost is smaller (types can be amended in-place and there is no need for extra libraries for each interface version).
- Extension interfaces can be attached at runtime rather than in the type system, so there is no need to rebase downstream extensions onto newer versions of interfaces.
- An existing AIDL interface can be used directly when its owner chooses to stabilize it. Before, an entire copy of the interface would have to be created in HIDL.
Writing an AIDL HAL interface
For an AIDL interface to be used between system and vendor, the interface needs two changes:
- Every type definition must be annotated with
@VintfStability
. - The
aidl_interface
declaration needs to includestability: "vintf",
.
Only the owner of an interface can make these changes.
Additionally, for maximum code portability and to avoid potential problems such as unnecessary additional libraries, disable the CPP backend.
Note that the use of backends
in the code example below is correct, as there
are three backends (Java, NDK, and CPP). The code below tells how to select the
CPP backend specifically, to disable it.
aidl_interface: {
...
backends: {
cpp: {
enabled: false,
},
},
}
Finding AIDL HAL interfaces
AOSP Stable AIDL interfaces for HALs are in the same base directories as
HIDL interfaces, in aidl
folders.
- hardware/interfaces
- frameworks/hardware/interfaces
- system/hardware/interfaces
You should put extension interfaces into other hardware/interfaces
subdirectories in vendor
or hardware
.
Extension Interfaces
Android has a set of official AOSP interfaces with every release. When Android partners want to add functionality to these interfaces, they shouldn't change these directly because this would mean that their Android runtime is incompatible with the AOSP Android runtime. For GMS devices, avoiding changing these interfaces is also what ensures the GSI image can continue to work.
Extensions can register in two different ways:
- at runtime, see attached extensions.
- standalone, registered globally and in VINTF.
However an extension is registered, when vendor-specific (meaning not a part of upstream AOSP) components use the interface, there is no possibility of merge conflict. However, when downstream modifications to upstream AOSP components are made, merge conflicts can result, and the following strategies are recommended:
- the interface additions can be upstreamed to AOSP in the next release
- interface additions which allow further flexibility, without merge conflicts, can be upstreamed in the next release
Building against the AIDL runtime
AIDL has three different backends: Java, NDK, CPP. To use Stable AIDL, you must
always use the system copy of libbinder at system/lib*/libbinder.so
and talk
on /dev/binder
. For code on the vendor image, this means that libbinder
(from the VNDK) cannot be used: this library has an unstable C++ API and
unstable internals. Instead, native vendor code must use the NDK backend of
AIDL, link against libbinder_ndk
(which is backed by system libbinder.so
),
and link against the -ndk_platform
libraries created by aidl_interface
entries.
AIDL HAL server instance names
By convention, AIDL HAL services have an instance name of the format
$package.$type/$instance
. For example, an instance of the vibrator HAL is
registered as android.hardware.vibrator.IVibrator/default
.
Writing an AIDL HAL server
AIDL servers must be declared in the VINTF manifest, for example like this:
<hal format="aidl">
<name>android.hardware.vibrator</name>
<version>1</version>
<fqname>IVibrator/default</fqname>
</hal>
Otherwise, they should register an AIDL service normally. When running VTS tests, it's expected that all declared AIDL HALs are available.
Writing an AIDL client
AIDL clients must declare themselves in the compatibility matrix, for example like this:
<hal format="aidl" optional="true">
<name>android.hardware.vibrator</name>
<version>1-2</version>
<interface>
<name>IVibrator</name>
<instance>default</instance>
</interface>
</hal>
Converting an existing HAL from HIDL to AIDL
Use the hidl2aidl
tool to convert a HIDL interface to AIDL.
hidl2aidl
features:
- Create
.aidl
files based on the.hal
files for the given package - Create build rules for the newly created AIDL package with all backends enabled
- Create translate methods in the Java, CPP, and NDK backends for translating from the HIDL types to the AIDL types
- Create build rules for translate libraries with required dependencies
- Create static asserts to ensure that HIDL and AIDL enumerators have the same values in the CPP and NDK backends
Follow these steps to convert a package of .hal files to .aidl files:
Build the tool located in
system/tools/hidl/hidl2aidl
.Building this tool from the latest source provides the most complete experience. You can use the latest version to convert interfaces on older branches from previous releases.
m hidl2aidl
Execute the tool with an output directory followed by the package to be converted.
hidl2aidl -o <output directory> <package>
For example:
hidl2aidl -o . android.hardware.nfc@1.2
Read through the generated files and fix any issues with the conversion.
conversion.log
contains any unhandled issues to fix first.- The generated
.aidl
files might have warnings and suggestions that might need action. These comments begin with//
. - Take the opportunity to clean up and make improvements to the package.
Build only the targets you need.
- Disable backends that won't be used. Prefer the NDK backend over the CPP backend, see choosing runtime.
- Remove translate libraries or any of their generated code that won't be used.
Sepolicy for AIDL HALs
An AIDL service type which is visible to vendor code must have the
vendor_service
attribute. Otherwise, the sepolicy configuration is the same
as any other AIDL service.
type hal_power_service, service_manager_type, vendor_service;
For most services defined by the platform, a service context with the correct
type is added already (for example, android.hardware.power.IPower/default
is
already marked as hal_power_service
). However, if a framework client supports
multiple instance names, additional instance names must be added in
device-specific service_contexts
files.
android.hardware.power.IPower/custom_instance u:object_r:hal_power_service:s0
Attached extension interfaces
An extension can be attached to any binder interface, whether it is a top-level interface registered directly with service manager or it is a sub-interface. When getting an extension, you must confirm the type of the extension is as expected. Extensions can only be set from the process serving a binder.
Attached extensions should be used whenever an extension modifies the functionality of an existing HAL. When entirely new functionality is needed, this mechanism doesn't need to be used, and an extension interface can be registered with the service manager directly. Attached extension interfaces make the most sense when they are attached to sub-interfaces, because these hierarchies may be deep or multi-instanced. Using a global extension to mirror the binder interface hierarchy of another service would require extensive bookkeeping to provide equivalent functionality to directly attached extensions.
To set an extension on binder, use the following APIs:
- In the NDK backend:
AIBinder_setExtension
- In the Java backend:
android.os.Binder.setExtension
- In the CPP backend:
android::Binder::setExtension
To get an extension on a binder, use the following APIs:
- In the NDK backend:
AIBinder_getExtension
- In the Java backend:
android.os.IBinder.getExtension
- In the CPP backend:
android::IBinder::getExtension
You can find more information for these APIs in the documentation of the
getExtension
function in the corresponding backend. An example of how to use
extensions can be found in hardware/interfaces/tests/extension/vibrator.
Major AIDL/HIDL differences
When using AIDL HALs or using AIDL HAL interfaces, be aware of the differences compared to writing HIDL HALs.
- The AIDL language's syntax is closer to Java. HIDL syntax is similar to C++.
- All AIDL interfaces have built-in error statuses. Instead of creating custom
status types, create constant status ints in interface files and use
EX_SERVICE_SPECIFIC
in the CPP/NDK backends andServiceSpecificException
in the Java backend. - AIDL does not automatically start threadpools when binder objects are sent. They must be started manually (see thread management).
- AIDL does not abort on unchecked transport errors (HIDL
Return
aborts on unchecked errors). - AIDL can only declare one type per file.
- AIDL arguments can be specified as in/out/inout in addition to the output parameter (there are no "synchronous callbacks").
- AIDL uses an fd as the primitive type instead of handle.
- HIDL uses major versions for incompatible changes and minor versions for
compatible changes. In AIDL, backwards-compatible changes are done in place.
AIDL has no explicit concept of major versions; instead, this is
incorporated into package names. For instance, AIDL might use the package name
bluetooth2
.