VHAL interface

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

Method
VehiclePropConfigs getAllPropConfigs()
Returns a list of all Property Configurations supported by this vehicle HAL.
VehiclePropConfigs getPropConfigs(in int[] props)
Returns a list of Property Configurations for given property IDs.
void getValues(IVehicleCallback callback, in GetValueRequests requests)
Get vehicle property values asynchronously. Handles a batch of GetValueRequest asynchronously. The result is delivered through the onGetValues method of callback.
void setValues(IVehicleCallback callback, in SetValueRequests requests)
Set vehicle property values asynchronously. Handles a batch of SetValueRequest asynchronously. The result is delivered through the onSetValues method of callback.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)
Subscribes to property events with specified options. The subscribe options include property ID, property area ID, and sample rate in Hz (for a continuous property). maxSharedMemoryFileCount isn't used.
void unsubscribe(in IVehicleCallback callback, in int[] propIds)
Unsubscribes previously subscribed property events for specified properties.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)
Not used and can be implemented as no-op.

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

Method
oneway void onGetValues(in GetValueResults responses)
Callback for the getValues function to deliver get value results. Called when some of the values to fetch are ready.
oneway void onSetValues(in SetValueResults responses)
Callback for setValues function to deliver set value results. Called when VHAL has finished handling some of the property set requests.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)
Callback for reporting property update events.
CONTINUOUS property, a property event happens based on subscribe sample rate in Hz or vehicle bus message frequency. A property event might also happen if a property's status changes. For example, from unavailable to available.
For the ON_CHANGE property, a property event happens when a property's value or a property's status changes.
SharedMemoryFileCount is always 0.
oneway void onPropertySetError(in VehiclePropErrors errors)
Callback for reporting asynchronous property set errors that have no corresponding set request. If we know which set request the error is for, onSetValues with an error result must be used instead of this.

For more information, see IVehicle.aidl and IVehicleCallback.aidl.

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.

Vehicle property value

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

Field Description
timestamp The timestamp representing the time the event happened and synchronized with the SystemClock.elapsedRealtimeNano() clock.
prop The property ID for this value.
areaid The area ID for this value. The area must be one of the supported areas listed in the area ID configuration, or 0 for global properties.
value A data structure containing the actual property value. Based on the property type, one or more fields within this field are used to store the actual value. For example, the first element in value.int32Values is used for Int32 type properties. For details, see Property Configurations.

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.

Guidance Description
payloads List of values when value size fits within a binder memory limitation, or an empty list.
sharedMemoryFd Nullable file descriptor pointing to a shared memory file that stores the serialized payloads if the list of values are too large.

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