HAL de audio de HIDL

En Android 13 y versiones anteriores, la interfaz de la HAL de audio se define con HIDL en archivos de HAL de HIDL (con la extensión .hal) y esquemas XSD para los archivos de configuración, como se muestra a continuación.

Figura 1: Interfaz de HAL de audio.

Nota: Para obtener más información, consulta la definición de la interfaz de HAL de audio y los comentarios en los archivos *.hal del directorio version de HAL correspondiente. Consulta el archivo readme de la HAL de audio para obtener la estructura de directorios de la HAL de audio para HIDL.

Archivos de configuración

Se considera que los archivos de configuración XML de la política de audio y los efectos de audio forman parte de la interfaz de la HAL del audio HIDL. Estos archivos deben cumplir con sus esquemas, y la conformidad se verifica mediante pruebas de VTS.

Como parte de la implementación del HAL de audio HIDL, debes crear un archivo de configuración de política de audio que describa la topología de audio. Las capacidades de la HAL de audio deben declararse en el archivo audio_policy_configuration.xml para que el framework las use.

API de HAL de audio HIDL

En esta sección, se describen las APIs principales, de efectos y de HAL comunes para HIDL.

Nota: En Android 13, todas las instrucciones de código que contienen 7.0 se reemplazan por 7.1. En Android 12, todas las instrucciones de código que contenían 6.0 se reemplazaron por 7.0.

HAL principal

Estas son algunas de las interfaces clave de Core HAL, que usan HIDL:

• IDeviceFactory.hal es el punto de entrada a la API.
• IDevice.hal y IPrimaryDevice.hal contienen métodos como setMasterVolume o openInputStream.
• Las transmisiones son unidireccionales, y AudioFlinger las usa para enviar o recibir audio desde y hacia la HAL mediante IStream.hal, IStreamOut.hal y IStreamIn.hal.

En la siguiente tabla, se indica la ubicación de los componentes útiles de HIDL de HAL principal:

Componente principal de HAL	Ubicación
Versión más reciente de la API	/hardware/interfaces/audio/6.0
Tipos específicos de la API de HAL principal más reciente	/hardware/interfaces/audio/6.0/types.hal
Esquema XSD del archivo de configuración de la política de audio	/hardware/interfaces/audio/6.0/config/audio_policy_configuration.xsd

La implementación predeterminada de la API de HAL principal (/hardware/interfaces/audio/core/all-versions/default/) es un wrapper alrededor de la implementación de HAL anterior a Treble que usa bibliotecas compartidas heredadas. La implementación predeterminada también se puede considerar como una referencia cuando se implementan versiones nuevas de HAL de audio que interactúan directamente con los controladores del kernel.

HAL de efectos

En la siguiente tabla, se enumera la ubicación de los componentes útiles de HAL de efectos que usan DIDL:

Componente de HAL de efectos	Ubicación
Versión más reciente de la API	/hardware/interfaces/audio/effect/6.0/
Esquema XSD del archivo de configuración de efectos	/hardware/interfaces/audio/effect/6.0/xml/audio_effects_conf.xsd

Para obtener más información, consulta una implementación de ejemplo de la API de HAL de efectos en /hardware/interfaces/audio/effect/all-versions/default/ y la sección Efectos de audio.

HAL común

La API de HAL común que usa HIDL contiene lo siguiente:

• Son las definiciones (/hardware/interfaces/audio/common/6.0/types.hal) que comparten las APIs de Core y Effect.
• Son utilidades (/hardware/interfaces/audio/common/all-versions) que se usan para ayudar a codificar con las APIs de HIDL para implementaciones, clientes y pruebas.

Actualizaciones de la HAL de audio V7

Hay cambios significativos en la versión 7 de la HAL de audio en Android 12, como se describe en esta sección. La HAL de audio V7 hace lo siguiente:

• Unifica los modelos de datos que usan el framework y HAL.
• Minimiza la duplicación entre los tipos de datos HIDL (enums) y el esquema XML que se usa para la configuración de la política de audio.

Específicamente, se realizan cambios en las siguientes áreas de la HAL de audio V7:

• Tipos de enumeración
• Tipos de datos
• Etiquetas de proveedor
• Espacios de nombres de las extensiones de proveedores

Estos cambios se analizan con más detalle en sus respectivas secciones.

Enumeraciones

A partir de la versión 7 de la HAL de audio, los tipos enumerados que se usan en el archivo de configuración de la política de audio se definen solo en el esquema XSD y no en el HIDL.

En el Audio HAL V6, los valores de los tipos de enum (como AudioFormat) en types.hal también se definen en el esquema XSD del archivo de configuración de la política de audio, lo que genera una duplicación. Para evitar esto en la versión 7, los tipos de enum se cambian a string y todos los valores de enumeración posibles se enumeran en el esquema XSD.

En la Figura 2, se comparan algunos de los cambios en el tipo de enumeración AudioFormat en la versión 7:

Figura 2: Comparación de algunos de los cambios en la enumeración AudioFormat.

Consulta la siguiente lista para ver los tipos de enum que se convirtieron a string:

• AudioChannelMask
• AudioContentType
• AudioDevice: Extensible por el proveedor
• AudioFormat: Extensible por el proveedor
• AudioGainMode
• AudioSource
• AudioStreamType
• AudioUsage

Cómo pasar valores de enumeración de cadenas

Los valores de cadena se usan para transferir información como valores de enumeración a través del límite de la interfaz de HAL. Tanto el framework como el wrapper de HAL usan valores de enumeración de números enteros para implementar la lógica empresarial y emplean el enfoque de conversión que se muestra en la Figura 3:

Figura 3: Pasar valores de enum de cadena

Nota: Puede parecer inusual o ineficiente que nuestra API use cadenas aquí. Decidimos usar cadenas para eliminar la duplicación de constantes de enumeración entre los archivos HIDL y XSD, y para simplificar la adición de extensiones de proveedores. La representación de enums como cadenas solo se recomienda para transportarlas a través de la interfaz HAL. No se recomienda usar enumeraciones representadas como cadenas en la lógica empresarial debido a la sobrecarga asociada en la implementación de operaciones de lógica booleana y las asignaciones de comparación resultantes.

A modo de ejemplo, para pasar un valor de tipo de formato de audio del framework al proveedor, haz lo siguiente:

1. El valor de enum de AudioFormat se convierte en un valor de cadena en libaudiohal y se pasa al HAL.
2. En el lado de HAL, el wrapper predeterminado convierte la cadena en un valor de enumeración, que se pasa al HAL heredado.

Nota: Los proveedores pueden modificar system/audio.h para usar sus propios valores de enum.

Cambios en el esquema XML

Tener listas completas de valores de enum en la definición del esquema XML (XSD) permite que VTS valide mejor los archivos en formato XML de configuración de la política de audio. Realizamos cambios en el archivo de configuración de la política de audio que se usa con HAL V7 para cumplir con XSD.

En V7, se usa un carácter ␣ (espacio) estándar para delimitar las listas de valores en los atributos (como tasas de muestreo, máscaras de canal y marcas), en lugar de los símbolos , (coma) y | (barra vertical) que se usan en V6 y versiones anteriores. Como se ve en el siguiente ejemplo, se usa un espacio para delimitar la lista de valores de channelMasks:

<profile channelMasks="AUDIO_CHANNEL_OUT_STEREO AUDIO_CHANNEL_OUT_MONO" … />

Para realizar los cambios de símbolos, usa una secuencia de comandos de conversión automática llamada update_audio_policy_config.sh. Consulta el siguiente comando para convertir un archivo de configuración de política de audio de la versión 6 a una versión 7 para el dispositivo Pixel 5 (Redfin):

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

Tipos de datos

Redefinimos algunas estructuras de datos en V7 para minimizar las definiciones duplicadas. Las tuplas repetidas de elementos de datos se agrupan en estructuras reutilizables. Estas estructuras de datos usan las funciones HIDL más recientes, como las uniones seguras.

Por ejemplo, en V6 y versiones anteriores, se usa con frecuencia un triple de <format, sampling rate, channel mask> en las interfaces y los tipos HIDL. Para quitar esta redundancia, en la versión 7, el tipo de datos AudioConfigBase y otros tipos de datos se definen de la siguiente manera:

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

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

  usado por AudioConfig, AudioOffloadInfo y AudioPortConfig

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

  reemplaza las colecciones sueltas en AudioPort/PortConfig

• AudioPortExtendedInfo := device | mix | session

  reemplaza las uniones de AudioPort/PortConfig

Etiquetas de proveedores

Además de los tipos y formatos de dispositivo, los proveedores pueden agregar etiquetas personalizadas para los metadatos de las pistas de audio.

Para los metadatos de las pistas de reproducción y grabación, los proveedores pueden pasar sus propias etiquetas, que se usan para agregar atributos a las transmisiones de E/S de audio, de las apps al HAL.

Nota: Las etiquetas de proveedores son similares a las extensiones de proveedores para formatos de audio y tipos de dispositivos de audio. La diferencia es que, para las etiquetas del proveedor, no hay valores definidos en AOSP, por lo que solo contienen valores extendidos por el proveedor.

Las etiquetas de proveedor para los metadatos de la pista de reproducción se agregan como se ve en el siguiente ejemplo:

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

La estructura RecordTrackMetadata se implementa de manera similar agregando etiquetas específicas para los metadatos de la pista de grabación.

Espacio de nombres de las extensiones de proveedores

A partir de la versión 7 de HAL, las extensiones de proveedores requieren un prefijo {vendor} adicional que no es necesario en la versión 6. Para que el prefijo {vendor} sea válido, debe tener tres o más caracteres alfanuméricos.

Usa el siguiente formato en la versión 7:

VX_{vendor}_{letters/numbers}

A continuación, se incluyen algunos ejemplos de extensiones de proveedores de V7 válidas:

• VX_GOOGLE_VR
• VX_QCI_AMBIENT_MIC

Información de la versión

En la siguiente tabla, se muestra el número de versión de HAL para cada versión de Android:

Versión de Android	Versión de HAL de HIDL
Android 13	7.1
Android 12	7.0
Android 11	6.0
Android 10	5.0
Android 9	4.0
Android 8	2.0