TinyHAL is an audio HAL for Android systems aimed at providing an improved basis for doing audio system integration in the Android application layer.
Traditionally the use-case logic has been hardcoded into HALs, which means that to edit use-cases or add new ones the code has to be changed and rebuilt. Typically any configuration files have been restricted to listing the ALSA control settings to be applied for a use-case but have no control over the actual use-case decisions.
A major aim of TinyHAL is for the configuration file to also control the logic of decision making about which use-cases to apply.
Key features include:
Based on top of tinyalsa and tinycompress
Configuration via an XML file
As much configuration as possible done via a text configuration file, minimizing the need for source code modifications
Custom streams can be defined to represent extra hardware audio routes outside of the standard Android playback and record - for example specific route handling for baseband, FM radio, HDMI, etc.
One-off boot-time configuration of mixer controls
Per-device mixer control settings for enabling and disabling that audio device
Connecting or disconnecting an audio device (speaker, headset, mic) on a stream can execute a different set of mixer settings for every connected {stream, device} combination.
Custom use-cases allow creation of mixer control setups that will be executed on events unique to the product, without having to hardcode knowledge of that use-case into TinyHAL.
Support for various types of ALSA control
Support for writing values into binary ALSA controls
Configuration file description is abstracted from Android’s audio definitions to avoid being constrained by what Android knows about. This allows greater flexibility in handling custom cases than would be possible if limited to Android’s built-in view of the audio.
Support for compressed offloaded streams (introduced in KitKat)
Use-case manager (configuration file and ALSA control handling) is a separate library so can be re-used with different HAL implementations
Support for auto-selecting which configuration file to use, based on reading an ID file or pseudo-file
Requires:
TinyHAL can build against the upstream (mainline) versions of tinyalsa and tinycompress, or the versions shipped with Android. When building against the Android versions, see section below "BUILDING AGAINST OLD LIBRARY VERSIONS".
The upstream versions are available from: tinyalsa: https://github.com/tinyalsa tinycompress: http://git.alsa-project.org/?p=tinycompress.git;a=summary
The version of tinyalsa and tinycompress shipped with Android source is not usually the latest mainline so some functionality might be missing or different. By default TinyHAL builds against the upstream versions.
There are build flags that you can define to disable or modify features if you are building against an older version of a library:
TINYALSA_NO_ADD_NEW_CTRLS define if your version of tinyalsa does not have mixer_add_new_ctls()
TINYALSA_NO_CTL_GET_ID define if your version of tinyalsa does not have mixer_ctl_get_id()
TINYCOMPRESS_TSTAMP_IS_LONG define if your version of tinycompress takes an unsigned long* argument to compress_get_tstamp()
TinyHAL is based on the idea of audio streams connected to one or more "devices" (in Android terminology, that is speakers, microphones, or other transducers)
A "stream" is a logical representation of one audio path.
A device is a logical representation of some form of audio source or sink
streams correspond closely to Android's Audio HAL audio_stream_out and audio_stream in, but can also be used more generically for hardware audio paths that are not seen by AudioFlinger, for example baseband modem-to-codec
Groups of ALSA settings will be invoked when: a stream is opened a stream is closed a device is enabled by connecting it to a stream a device is disabled by disconnecting it from all streams a device is connected to a stream a device is disconnected from a stream a custom use-case is executed on a stream
Each device can have multiple sets of ALSA control settings, each set identified by a user-defined label. Every stream defines which label to invoke on connected devices when they are connected to that stream.
For example if the PCM playback stream defines that the label for enable is "pcm_out_enable", when any device is connected to this stream if that device has a "pcm_out_enable" ALSA control list those settings will be invoked.
Each device also has two (optional) pre-defined labels "on" and "off" for a list of ALSA settings to be invoked when the device is activated or deactivated. The "on" case will be invoked when a device is first connected to a stream (that is, its state changed from unused to in-use). The "off" is invoked when the device is disconnected from the last stream (its state changes from in-use to unused.)
This is explained in more detail, with example configuration lines, in the file audio.example.xml.
In general the control logic that TinyHAL uses to invoke ALSA settings works like this:
Stream opened=> if (stream defines "enable path" label) if ("global" device defines this label) invoke ALSA settings from "global" stream label
Stream connected to device=> if (device currently not in use) if (device defines "on" label) invoke ALSA settings from device "on" label
if (stream defines "enable path" label)
if (device defines this label)
invoke ALSA settings from device labelStream custom use-case issued=> if (stream defines this use-case) if (use-case list includes the given value) invoke ALSA controls listed for this use-case value
Stream disconnected from device=> if (stream defines "disable path" label) if (device defines this label) invoke ALSA settings from device label
if (device not connected to any other streams)
if (device defines "off" label)
invoke ALSA settings from device "off" labelStream closed=> if (deviced currently connected) disconnect each device
if (disable path label defined)
if ("global" stream defines this label)
invoke ALSA settings from "global" stream labelThe simplest mode of auto-detection is to specify the ALSA card by name instead of by number. Tinyhal will search all /proc/asound/card*/id files for one that matches the given name. This abstracts from the actual card number, which isn't guaranteed to be the same between boots or across different devices using the same ALSA sound card.
A more sophisticated mechanism is to auto-select which configuration file to load. This is based on having a file or pseudo-file that contains as its first line a string identifying the hardware. TinyHAL doesn't care how this file is generated. A typical use is to point it at the pseudo-file /sys/class/sound/card0/id, which contains a single line giving the name of the audio card (as defined by the kernel audio card driver or codec driver.) But it could just as well be any readable pseudo-file, or a real file created on startup by the init script.
The first line from the given file is stripped of leading and trailing whitespace and then compared against a list of strings provided in the initial XML file that TinyHAL loads on startup. For each string an alternate XML filename is given.
If one of these strings matches, TinyHAL will abandon processing of the current XML file and instead start processing the alternate XML file. If none of the strings match, TinyHAL will continue to process the current XML file.
The syntax for this is shown in audio.example.xml (see the codec_probe block)