HIDL Audio HAL

In Android 13 and lower, the Audio HAL interface is defined using HIDL in HIDL HAL files (with the extension .hal) and XSD schemas for the configuration files, shown as follows.

audio_hal

Figure 1. Audio HAL interface.

Configuration files

Audio policy and audio effects XML configuration files are considered to be part of the Audio HIDL HAL interface. These files must conform to their schemas, and the conformance is verified by VTS tests.

As part of implementing the audio HIDL HAL, you must create an audio policy configuration file that describes the audio topology. Audio HAL capabilities must be declared in the audio_policy_configuration.xml file for the framework to use them.

Audio HIDL HAL API

This section describes the Core, Effects, and Common HAL APIs for HIDL.

Core HAL

Some of the key interfaces of Core HAL, using HIDL, are as follows:

  • IDeviceFactory.hal is the entry point into the API.
  • IDevice.hal and IPrimaryDevice.hal contain methods such as setMasterVolume or openInputStream.
  • Streams are unidirectional and are used by AudioFlinger to send or receive audio to and from the HAL through IStream.hal, IStreamOut.hal, and IStreamIn.hal.

The following table lists the location of useful Core HAL HIDL components:

Core HAL component Location
Latest version of API /hardware/interfaces/audio/6.0
Types specific to the latest Core HAL API /hardware/interfaces/audio/6.0/types.hal
Audio policy configuration file XSD schema /hardware/interfaces/audio/6.0/config/audio_policy_configuration.xsd

The default implementation of the Core HAL API (/hardware/interfaces/audio/core/all-versions/default/) is a wrapper around the pre-Treble HAL implementation using legacy shared libraries. The default implementation can also be considered as a reference when implementing new versions of Audio HALs that interact with kernel drivers directly.

Effects HAL

The following table lists the location of useful Effects HAL components using HIDL:

Effects HAL component Location
Latest version of API /hardware/interfaces/audio/effect/6.0/
Effect configuration file XSD schema /hardware/interfaces/audio/effect/6.0/xml/audio_effects_conf.xsd

For more information, see a sample implementation of the Effects HAL API at /hardware/interfaces/audio/effect/all-versions/default/ and the Audio Effects section.

Common HAL

The Common HAL API using HIDL contains the following:

  • Definitions (/hardware/interfaces/audio/common/6.0/types.hal) shared by the Core and Effect APIs.
  • Utilities (/hardware/interfaces/audio/common/all-versions) used to help coding against HIDL APIs for implementations, clients, and tests.

Updates to the Audio HAL V7

There are significant changes to version 7 of the Audio HAL in Android 12 as outlined in this section. The Audio HAL V7 does the following:

  • Unifies the data models used by the framework and HAL.
  • Minimizes the duplication between HIDL data types (enums) and the XML schema used for audio policy configuration.

Specifically, changes are made in the following areas in Audio HAL V7:

These changes are discussed in more detail in their respective sections.

Enumerations

Starting in Audio HAL V7, enumerated types used in the Audio Policy Configuration file are defined only in the XSD schema and not in the HIDL.

In Audio HAL V6, values of enum types (like AudioFormat) in types.hal are also defined in the audio policy configuration file XSD schema, creating a duplication. To avoid this in V7, the enum types are changed to string and all the possible enumeration values are listed in the XSD schema instead.

Figure 2 compares some of the changes to the AudioFormat enum type in V7:

audioformat-change

Figure 2. Comparison of some of the changes to the AudioFormat enum.

Refer to the following list for the enum types that have been converted to string:

  • AudioChannelMask
  • AudioContentType
  • AudioDevice: Vendor extensible
  • AudioFormat: Vendor extensible
  • AudioGainMode
  • AudioSource
  • AudioStreamType
  • AudioUsage

Pass string enum values

String values are used for transferring information as enumeration values across the HAL interface boundary. Both the framework and the HAL wrapper use integer enum values for implementing business logic and employ the conversion approach depicted in Figure 3:

audio-passing-values

Figure 3. Passing string enum values.

As an example, to pass a value of audio format type from the framework to the vendor:

  1. The enum value of AudioFormat is converted to a string value in libaudiohal and is passed to the HAL.
  2. On the HAL side, the default wrapper converts the string to an enum value, which is passed to the legacy HAL.

XML schema changes

Having complete lists of enum values in the XML schema definition (XSD) allows for better audio policy configuration XML file validation by VTS. We made changes in the audio policy configuration file used with HAL V7 to comply with XSD.

In V7, a standard ␣ (space) character is used to delimit value lists in attributes (like sampling rates, channel masks, and flags), instead of the , (comma) and | (vertical bar) symbols used in V6 and below. As seen in the following example, a space is used to delimit the list of values for channelMasks:

<profile channelMasks="AUDIO_CHANNEL_OUT_STEREO AUDIO_CHANNEL_OUT_MONO" … />

To make the symbol changes, use an automatic conversion script called update_audio_policy_config.sh. See the following command to convert a V6 audio policy config file to a V7 version for the Pixel 5 (Redfin) device:

hardware/interfaces/audio/7.0/config/update_audio_policy_config.sh \
device/google/redfin/audio/audio_policy_configuration.xml 6.0

Data types

We redefined some data structures in V7 to minimize duplicate definitions. Repeated tuples of data items are grouped together into reusable structures. These data structures use the latest HIDL features like safe unions.

For example, in V6 and below, a triple of <format, sampling rate, channel mask> is used often in the HIDL interfaces and types. To remove this redundancy, in V7, the AudioConfigBasedata type and other data types are defined as follows:

  • AudioConfigBase := <format, sampling rate, channel mask>

  • AudioConfigBaseOptional := <[fmt], [sampl. rate], [chan. mask]>

    used by AudioConfig, AudioOffloadInfo, AudioPortConfig

  • AudioProfile := <format, {sampling rates}, {channel masks}>

    replaces loose collections in AudioPort/PortConfig

  • AudioPortExtendedInfo := device | mix | session

    replaces unions in AudioPort/PortConfig

Vendor tags

In addition to device types and formats, vendors can add custom tags for audio track metadata.

For playback and recording track metadata, vendors can pass their own tags, which are used to add attributes to audio I/O streams, from the apps to the HAL.

Vendor tags for playback track metadata are added as seen in the following example:

struct PlaybackTrackMetadata {
…
    /** Tags from AudioTrack audio attributes */
    vec<AudioTag> tags;
};

The RecordTrackMetadata structure is implemented in a similar fashion by adding tags specific for the recording track metadata.

Vendor extensions namespacing

Starting in HAL V7, vendor extensions require an additional {vendor} prefix that isn't required in V6. For the {vendor} prefix to be valid, it must be three or more alphanumeric characters.

Use the following format in V7:

VX_{vendor}_{letters/numbers}

The following are some examples of valid V7 vendor extensions:

  • VX_GOOGLE_VR
  • VX_QCI_AMBIENT_MIC

Version information

The following table lists the HAL version number for each Android release:

Android version HIDL HAL version
Android 13 7.1
Android 12 7.0
Android 11 6.0
Android 10 5.0
Android 9 4.0
Android 8 2.0