VHAL interface

The AIDL VHAL is defined in android.hardware.automotive.vehicle namespace. The VHAL interface is defined at IVehicle.aidl. Unless specified, all methods must be implemented for a specific VHAL version.

Versions

It is RECOMMENDED to implement the latest VHAL version for a specific Android version.

Functions and callbacks

The VHAL functions are defined at IVehicle.aidl.

The callbacks are defined at IVehicleCallback.aidl and contain these methods.

The VHAL implementation is validated by the VHAL VTS at VtsHalAutomotiveVehicle_TargetTest.cpp.

The test verifies that basic methods are implemented correctly and the supported property configurations are correct. The test runs against all VHAL instances on the device, however, AAOS uses only the default instance (android.hardware.automotive.vehicle.IVehicle/default)

Vehicle property value

Use the VehiclePropValue structure to describe each property's value, which has these fields:

Asynchronous getValues and setValues

The getValues and setValues operations are performed asynchronously, meaning that the function might return before the actual get or set operation is completed. The operation results (for example, property value for getValues and success or error status for setValues) are delivered through the callbacks passed as arguments.

Implementation must not block on the result in the binder thread that handles the request. Instead, we recommend you store the request in a request queue and use a separate handler thread to handle the requests asynchronously. See the Reference Implementation for details.

Figure 1. Asynchronous process.

Large parcelables

All structures named XXXs, such as VehiclePropConfigs, SetValueRequests, and VehiclePropValues are called LargeParcelable (or, StableLargeParcelable). Each represents a list of values used to pass large data that might exceed binder limitations (4KB in the LargeParcelable library implementation) across binder boundaries. Each has a similar structure definition which contains the following fields.

For example, VehiclePropConfigs is defined as:

parcelable VehiclePropConfigs {
    // The list of vehicle property configs if they fit the binder memory
    // limitation.
    VehiclePropConfig[] payloads;
    // Shared memory file to store configs if they exceed binder memory
    // limitation. Created by VHAL, readable only at client. Client could keep
    // the fd opened or keep the FD mapped to access configs.
    @nullable ParcelFileDescriptor sharedMemoryFd;
}

VehiclePropConfigs contains either non-empty payloads or a non-null sharedMemoryFd.

• If payloads isn't empty, it stores a list of the actual data, which is the property config.
• If sharedMemoryFd isn't null, it contains a shared memory file, which stores the serialized structure of VehiclePropConfigs. The structure uses the writeToParcel function to serialize a Parcel.

As a Java client for VHAL, Car Service handles the serialization and deserialization for LargeParcelable. For VHAL implementations and native clients, a LargeParcelable should be serialized and deserialized with the LargeParcelable library or a useful wrapper class for the library in ParcelableUtils.h.

For example, a native client parsing requests for getValues received from a binder is as follows:

// 'requests' are from the binder.
GetValueRequests requests;
expected<LargeParcelableBase::BorrowedOwnedObject, ScopedAStatus> deserializedResults = fromStableLargeParcelable(requests);
if (deserializedResults.ok()) {
    const std::vector& getValueRequests = deserializedResults.value().getObject()->payloads;
    // Use the getValueRequests.
  } else {
    // handle error.
}

A sample VHAL implementation that sends results for getValues through the binder is shown below:

std::vector results = getResults();
GetValueResults parcelableResults;
ScopedAStatus status = vectorToStableLargeParcelable(std::move(results), &parcelableResults);
if (status.isOk()) {
    // Send parcelableResults through callback.
} else {
    // Handle error.
}