HAL audio HIDL

In Android 13 e versioni precedenti, l'interfaccia HAL Audio viene definita utilizzando HIDL nei file HAL HIDL (con estensione .hal) e gli schemi XSD per i file di configurazione, come mostrato di seguito.

Figura 1. Interfaccia audio HAL.

Nota: per ulteriori dettagli, consulta la definizione dell'interfaccia HAL audio e i commenti nei file *.hal della directory della versione HAL corrispondente. Consulta il file README dell'HAL audio per la struttura della directory dell'HAL audio per HIDL.

File di configurazione

I file di configurazione XML dei criteri audio e degli effetti audio sono considerati parte dell'interfaccia HAL HIDL audio. Questi file devono essere conformi ai relativi schemi e la conformità viene verificata dai test VTS.

Nell'ambito dell'implementazione dell'HAL HIDL audio, devi creare un file di configurazione dei criteri audio che descriva la topologia audio. Le funzionalità HAL audio devono essere dichiarate nel file audio_policy_configuration.xml affinché il framework le utilizzi.

API Audio HIDL HAL

Questa sezione descrive le API HAL di base, per gli effetti e comuni per HIDL.

Nota: per Android 13, tutti i percorsi di codice contenenti 7.0 vengono sostituiti con 7.1. In Android 12, tutti i percorsi del codice contenenti 6.0 sono stati sostituiti con 7.0.

HAL di base

Di seguito sono riportate alcune delle interfacce principali di Core HAL, che utilizza HIDL:

• IDeviceFactory.hal è il punto di accesso all'API.
• IDevice.hal e IPrimaryDevice.hal contengono metodi come setMasterVolume o openInputStream.
• Gli stream sono unidirezionali e vengono utilizzati da AudioFlinger per inviare o ricevere audio verso e dall'HAL tramite IStream.hal, IStreamOut.hal e IStreamIn.hal.

La tabella seguente elenca la posizione dei componenti HIDL HAL di base utili:

Componente HAL principale	Posizione
Versione più recente dell'API	/hardware/interfaces/audio/6.0
Tipi specifici dell'ultima API Core HAL	/hardware/interfaces/audio/6.0/types.hal
Schema XSD del file di configurazione dei criteri audio	/hardware/interfaces/audio/6.0/config/audio_policy_configuration.xsd

L'implementazione predefinita dell'API HAL di base (/hardware/interfaces/audio/core/all-versions/default/) è un wrapper dell'implementazione HAL precedente a Treble che utilizza librerie condivise precedenti. L'implementazione predefinita può essere considerata anche come riferimento per l'implementazione di nuove versioni di HAL audio che interagiscono direttamente con i driver del kernel.

Effetti HAL

La tabella seguente elenca la posizione dei componenti HAL degli effetti utili utilizzando l'HIDL:

Componente HAL degli effetti	Posizione
Versione più recente dell'API	/hardware/interfaces/audio/effect/6.0/
Schema XSD del file di configurazione dell'effetto	/hardware/interfaces/audio/effect/6.0/xml/audio_effects_conf.xsd

Per ulteriori informazioni, consulta un'implementazione di esempio dell'API HAL Effects all'indirizzo /hardware/interfaces/audio/effect/all-versions/default/ e la sezione Effetti audio.

HAL comune

L'API Common HAL che utilizza l'HIDL contiene quanto segue:

• Definizioni (/hardware/interfaces/audio/common/6.0/types.hal) condivise dalle API Core ed Effect.
• Utilità (/hardware/interfaces/audio/common/all-versions) utilizzate per agevolare la programmazione rispetto alle API HIDL per implementazioni, client e test.

Aggiornamenti all'Audio HAL V7

La versione 7 dell'HAL Audio in Android 12 presenta modifiche significative, come descritto in questa sezione. L'Audio HAL V7 esegue le seguenti operazioni:

• Unifica i modelli di dati utilizzati dal framework e dall'HAL.
• Riduce al minimo la duplicazione tra i tipi di dati HIDL (enum) e lo schema XML utilizzato per la configurazione dei criteri audio.

Nello specifico, le modifiche vengono apportate nelle seguenti aree di Audio HAL V7:

• Tipi di enumerazione
• Tipi di dati
• Tag dei fornitori
• Spazi dei nomi delle estensioni del fornitore

Queste modifiche sono descritte in maggiore dettaglio nelle rispettive sezioni.

Enumerazioni

A partire dalla versione 7 dell'HAL audio, i tipi enumerati utilizzati nel file di configurazione delle norme audio sono definiti solo nello schema XSD e non in HIDL.

In Audio HAL 6, i valori dei tipi di enum (come AudioFormat) in types.hal sono anche definiti nello schema XSD del file di configurazione dei criteri audio, creando una duplicazione. Per evitare questo problema nella versione 7, i tipi di enum vengono modificati in string e tutti i possibili valori di enumerazione sono elencati nello schema XSD.

La figura 2 confronta alcune delle modifiche al tipo di enum AudioFormat nella versione V7:

Figura 2. Confronto di alcune delle modifiche all'enum AudioFormat.

Consulta l'elenco seguente per i tipi di enum che sono stati convertiti in string:

• AudioChannelMask
• AudioContentType
• AudioDevice: estensibile dal fornitore
• AudioFormat: estensibile dal fornitore
• AudioGainMode
• AudioSource
• AudioStreamType
• AudioUsage

Passare i valori enum della stringa

I valori stringa vengono utilizzati per trasferire informazioni come valori di enumerazione attraverso i confini dell'interfaccia HAL. Sia il framework sia il wrapper HAL utilizzano valori enum interi per l'implementazione della logica di business e impiegano l'approccio di conversione illustrato nella Figura 3:

Figura 3. Passare valori enum di stringa.

Nota: potrebbe sembrare insolito o inefficiente che la nostra API utilizzi stringhe qui. Abbiamo scelto di utilizzare le stringhe per eliminare la duplicazione di costanti di enumerazione tra i file HIDL e XSD e per semplificare l'aggiunta delle estensioni di fornitore. La rappresentazione delle enum come stringhe è consigliata solo per trasportarle tramite l'interfaccia dell'HAL. Non è consigliabile utilizzare le enumerazioni rappresentate come stringhe nella logica di business a causa del sovradimensionamento associato all'implementazione delle operazioni di logica booleana e delle mappature di confronto risultanti.

Ad esempio, per passare un valore del tipo di formato audio dal framework al fornitore:

1. Il valore enum di AudioFormat viene convertito in un valore stringa in libaudiohal e trasmesso all'HAL.
2. Sul lato HAL, il wrapper predefinito converte la stringa in un valore di enum, che viene passato all'HAL precedente.

Nota: i fornitori possono modificare system/audio.h per utilizzare i propri valori enumerati.

Modifiche allo schema XML

Avere elenchi completi di valori enum nella definizione dello schema XML (XSD) consente una convalida migliore dei file XML di configurazione dei criteri audio da parte di VTS. Abbiamo apportato modifiche al file di configurazione dei criteri audio utilizzato con HAL V7 per renderlo conforme allo standard XSD.

Nella versione 7, per delimitare gli elenchi di valori negli attributi (come frequenze di campionamento, maschere di canali e flag) viene utilizzato un carattere standard ␣ (spazio), anziché i simboli , (virgola) e | (barra verticale) utilizzati nella versione 6 e precedenti. Come mostrato nell'esempio seguente, viene utilizzato uno spazio per delimitare l'elenco di valori per channelMasks:

<profile channelMasks="AUDIO_CHANNEL_OUT_STEREO AUDIO_CHANNEL_OUT_MONO" … />

Per apportare modifiche al simbolo, utilizza uno script di conversione automatico chiamato update_audio_policy_config.sh. Vedi il comando seguente per convertire un file di configurazione dei criteri audio V6 in una versione V7 per il 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

Tipi di dati

Abbiamo ridefinito alcune strutture di dati nella versione V7 per ridurre al minimo le definizioni duplicate. Le tuple ripetute di elementi di dati vengono raggruppate in strutture riutilizzabili. Queste strutture di dati utilizzano le funzionalità HIDL più recenti, come le unioni sicure.

Ad esempio, nella versione 6 e precedenti, una tripla di <format, sampling rate, channel mask> viene spesso utilizzata nelle interfacce e nei tipi HIDL. Per rimuovere questa ridondanza, nella versione 7 il tipo di dati AudioConfigBase e gli altri tipi di dati sono definiti come segue:

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

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

  utilizzato da AudioConfig, AudioOffloadInfo, AudioPortConfig

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

  sostituisce le raccolte libere in AudioPort/PortConfig

• AudioPortExtendedInfo := device | mix | session

  sostituisce i sindacati in AudioPort/PortConfig

Tag del fornitore

Oltre ai tipi e ai formati di dispositivi, i fornitori possono aggiungere tag personalizzati per i metadati delle tracce audio.

Per i metadati dei canali di riproduzione e registrazione, i fornitori possono trasmettere le proprie etichette, che vengono utilizzate per aggiungere attributi agli stream I/O audio, dalle app all'HAL.

Nota: i tag fornitore sono simili alle estensioni fornitore per i formati audio e i tipi di dispositivi audio. La differenza è che per i tag del fornitore non sono definiti valori in AOSP, pertanto contengono solo valori estesi dal fornitore.

I tag del fornitore per i metadati della traccia di riproduzione vengono aggiunti come mostrato nell'esempio seguente:

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

La struttura RecordTrackMetadata viene implementata in modo simile aggiungendo tag specifici per i metadati della traccia di registrazione.

Spaziatura dei nomi delle estensioni del fornitore

A partire dalla versione 7 di HAL, le estensioni del fornitore richiedono un prefisso {vendor} aggiuntivo che non è necessario nella versione 6. Affinché il prefisso {vendor} sia valido, deve contenere almeno tre caratteri alfanumerici.

Utilizza il seguente formato in V7:

VX_{vendor}_{letters/numbers}

Di seguito sono riportati alcuni esempi di estensioni del fornitore V7 valide:

• VX_GOOGLE_VR
• VX_QCI_AMBIENT_MIC

Informazioni sulla versione

Nella tabella seguente sono elencati i numeri di versione dell'HAL per ogni release di Android:

Versione di Android	Versione HIDL HAL
Android 13	7.1
Android 12	7,0
Android 11	6.0
Android 10	5,0
Android 9	4.0
Android 8	2,0