HIDL Audio HAL

在 Android 13 以下版本中，音訊 HAL 介面是使用 HIDL 在 HIDL HAL 檔案 (副檔名為 .hal) 和設定檔的 XSD 結構定義中定義，如下所示。

圖 1. 音訊 HAL 介面。

設定檔

音訊政策和音訊效果 XML 設定檔會視為音訊 HIDL HAL 介面的一部分。這些檔案必須符合結構定義，且一致性會透過 VTS 測試驗證。

實作音訊 HIDL HAL 時，您必須建立音訊政策設定檔，說明音訊拓撲。音訊 HAL 功能必須在 audio_policy_configuration.xml 檔案中宣告，架構才能使用這些功能。

音訊 HIDL HAL API

本節說明 HIDL 的 Core、Effects 和 Common HAL API。

核心 HAL

以下是使用 HIDL 的 Core HAL 主要介面：

• IDeviceFactory.hal 是 API 的進入點。
• IDevice.hal 和 IPrimaryDevice.hal 包含 setMasterVolume 或 openInputStream 等方法。
• 串流是單向的，AudioFlinger 會透過 IStream.hal、IStreamOut.hal 和 IStreamIn.hal，將音訊傳送至 HAL 或從 HAL 接收音訊。

下表列出實用 Core HAL HIDL 元件的位置：

Core HAL API (/hardware/interfaces/audio/core/all-versions/default/) 的預設實作項目是使用舊版共用程式庫，包裝 Treble 前的 HAL 實作項目。實作與核心驅動程式直接互動的新版 Audio HAL 時，也可以將預設實作視為參考資料。

Effects HAL

下表列出使用 HIDL 時，實用 Effects HAL 元件的位置：

詳情請參閱 /hardware/interfaces/audio/effect/all-versions/default/ 的 Effects HAL API 範例實作，以及「音效」一節。

通用 HAL

使用 HIDL 的 Common HAL API 包含下列項目：

• 核心和效果 API 共用的定義 (/hardware/interfaces/audio/common/6.0/types.hal)。
• 公用程式 (/hardware/interfaces/audio/common/all-versions) 用於協助針對實作項目、用戶端和測試的 HIDL API 進行編碼。

音訊 HAL V7 更新

Android 12 的 Audio HAL 第 7 版有重大變更，詳情請參閱本節。音訊 HAL V7 會執行下列作業：

• 統一架構和 HAL 使用的資料模型。
• 盡量減少 HIDL 資料型別 (列舉) 與用於音訊政策設定的 XML 結構定義之間的重複項目。

具體來說，音訊 HAL V7 的變更如下：

• 列舉類型
• 資料類型
• 供應商代碼
• 供應商擴充功能命名空間

各節會詳細說明這些變更。

列舉

從 Audio HAL V7 開始，音訊政策設定檔中使用的列舉型別只會在 XSD 架構中定義，不會在 HIDL 中定義。

在 Audio HAL V6 中，音訊政策設定檔 XSD 結構定義也會定義 types.hal 中的列舉型別值 (例如 AudioFormat)，造成重複定義。為避免 V7 發生這種情況，列舉型別已變更為 string，且所有可能的列舉值都會列在 XSD 結構定義中。

圖 2 比較第 7 版中 AudioFormat 列舉型別的部分變更：

圖 2. 比較 AudioFormat 列舉的部分變更。

如要查看已轉換為 string 的列舉型別，請參閱下列清單：

• AudioChannelMask
• AudioContentType
• AudioDevice：供應商可擴充
• AudioFormat：供應商可擴充
• AudioGainMode
• AudioSource
• AudioStreamType
• AudioUsage

傳遞字串列舉值

字串值用於跨 HAL 介面邊界傳輸資訊做為列舉值。架構和 HAL 包裝函式都會使用整數列舉值，實作業務邏輯，並採用圖 3 所示的轉換方法：

圖 3. 傳遞字串列舉值。

舉例來說，如要將音訊格式類型的值從架構傳遞至供應商，請按照下列步驟操作：

1. AudioFormat 的列舉值會在 libaudiohal 中轉換為字串值，並傳遞至 HAL。
2. 在 HAL 端，預設包裝函式會將字串轉換為列舉值，並傳遞至舊版 HAL。

XML 架構異動

XML 架構定義 (XSD) 中若有完整的列舉值清單，VTS 就能更有效驗證音訊政策設定 XML 檔案。我們變更了搭配 HAL V7 使用的音訊政策設定檔，以符合 XSD 規定。

在 V7 中，屬性 (例如取樣率、聲道遮罩和旗標) 中的值清單會以標準 ␣ (空格) 字元做為分隔符號，而非 V6 和更早版本使用的 , (半形逗號) 和 | (垂直線) 符號。如下例所示，系統會使用空格分隔 channelMasks 的值清單：

<profile channelMasks="AUDIO_CHANNEL_OUT_STEREO AUDIO_CHANNEL_OUT_MONO" … />

如要變更符號，請使用名為 update_audio_policy_config.sh 的自動轉換指令碼。請參閱下列指令，將 Pixel 5 (Redfin) 裝置的 V6 音訊政策設定檔轉換為 V7 版本：

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

資料類型

我們在 V7 中重新定義了部分資料結構，盡量減少重複定義。資料項目的重複元組會分組為可重複使用的結構。這些資料結構會使用最新的 HIDL 功能，例如安全聯集。

舉例來說，在 V6 和更早的版本中，HIDL 介面和型別中經常使用 <format, sampling rate, channel mask>。為移除這項多餘的定義，在 V7 中，AudioConfigBase資料類型和其他資料類型定義如下：

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

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

  AudioConfig、AudioOffloadInfo、AudioPortConfig 使用的付款資料

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

  取代 AudioPort/PortConfig 中的鬆散集合

• AudioPortExtendedInfo := device | mix | session

  取代 AudioPort/PortConfig 中的聯集

供應商代碼

除了裝置類型和格式，供應商還可為音軌中繼資料新增自訂標記。

如要播放及錄製曲目中繼資料，供應商可以從應用程式將自己的標記傳遞至 HAL，這些標記可用於在音訊 I/O 串流中新增屬性。

系統會新增播放軌中繼資料的供應商標記，如下列範例所示：

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

加入錄音軌中繼資料專屬的標記，即可採用類似方式實作 RecordTrackMetadata 結構。

供應商擴充功能命名空間

從 HAL V7 開始，供應商擴充功能需要額外的 {vendor} 前置字元，V6 則不需要。{vendor}前置字串必須包含至少三個英數字元，才算有效。

在 V7 中，請使用下列格式：

VX_{vendor}_{letters/numbers}

以下列舉一些有效的 V7 供應商擴充功能：

• VX_GOOGLE_VR
• VX_QCI_AMBIENT_MIC

版本資訊

下表列出各個 Android 版本的 HAL 版本號碼：