HIDL 音訊 HAL

在 Android 13 以下版本中，Audio HAL 介面會使用 HIDL HAL 檔案中的 HIDL (擴充功能為 .hal) 和設定檔的 XSD 架構定義。

圖 1. 音訊 HAL 介面。

注意： 如需更多詳細資訊，請參閱 Audio HAL 介面定義，以及對應 HAL 版本目錄中 *.hal 檔案中的註解。如要瞭解 HIDL 的 Audio HAL 目錄結構，請參閱 Audio HAL README 檔案。

設定檔

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

實作音訊 HIDL HAL 時，您必須建立描述音訊拓樸的音訊政策設定檔。音訊 HAL 功能必須在 audio_policy_configuration.xml 檔案中宣告，才能供架構使用。

Audio HIDL HAL API

本節將說明 HIDL 的核心、效果和通用 HAL API。

注意： 對於 Android 13，所有包含 7.0 的程式碼路徑都會替換為 7.1。在 Android 12 中，所有包含 6.0 的程式碼路徑都已替換為 7.0。

核心 HAL

使用 HIDL 的核心 HAL 的部分重要介面如下：

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

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

核心 HAL 元件	位置
API 最新版本	/hardware/interfaces/audio/6.0
最新 Core HAL API 專屬類型	/hardware/interfaces/audio/6.0/types.hal
音訊政策設定檔 XSD 結構定義	/hardware/interfaces/audio/6.0/config/audio_policy_configuration.xsd

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

特效 HAL

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

效果 HAL 元件	位置
API 最新版本	/hardware/interfaces/audio/effect/6.0/
效果設定檔 XSD 結構定義	/hardware/interfaces/audio/effect/6.0/xml/audio_effects_conf.xsd

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

通用 HAL

使用 HIDL 的通用 HAL API 包含以下內容：

• Core API 和 Effect API 共用的定義 (/hardware/interfaces/audio/common/6.0/types.hal)。
• 實用工具 (/hardware/interfaces/audio/common/all-versions)，可協助針對實作、用戶端和測試，根據 HIDL API 進行程式設計。

Audio HAL V7 更新

如本節所述，Android 12 中的 Audio HAL 7 版有重大變更。Audio HAL V7 會執行以下操作：

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

具體來說，Audio HAL V7 的以下部分會進行變更：

• 列舉類型
• 資料類型
• 供應商代碼
• 供應商額外資訊命名空間

這些變更的詳細說明請見各自的章節。

列舉

自 Audio HAL 第 7 版起，在 Audio Policy 設定檔中使用的列舉類型只會在 XSD 結構定義中定義，不會在 HIDL 中定義。

在 Audio HAL V6 中，音訊政策設定檔 XSD 結構定義中也定義了 types.hal 中的列舉類型值 (例如 AudioFormat)，因此會產生重複。為避免在 V7 中發生這種情況，我們將列舉類型變更為 string，並改在 XSD 結構定義中列出所有可能的列舉值。

圖 2 比較 V7 中 AudioFormat 列舉類型的部分變更：

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

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

• AudioChannelMask
• AudioContentType
• AudioDevice：供應商可延伸
• AudioFormat：供應商可延伸
• AudioGainMode
• AudioSource
• AudioStreamType
• AudioUsage

傳遞字串列舉值

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

圖 3. 傳遞字串列舉值。

注意： 我們的 API 在這裡使用字串可能會不尋常或效率不彰。我們選擇使用字串，以免 HIDL 和 XSD 檔案之間的列舉常數重複，並簡化供應商擴充功能的新增程序。建議您只在透過 HAL 介面傳輸列舉時，將列舉表示為字串。由於實作布林邏輯運算和產生的比較對應作業會產生相關的額外負擔，因此不建議在商業邏輯中使用以字串表示的列舉。

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

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

注意： 供應商可以修改 system/audio.h，以便使用自己的列舉值。

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 的自動轉換指令碼。請參閱下列指令，將 V6 音訊政策設定檔轉換為 Pixel 5 (Redfin) 裝置的 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。

注意： 供應商代碼類似於音訊格式和音訊裝置類型的供應商擴充功能。差異在於供應商標記在 AOSP 中沒有定義任何值，因此只包含供應商擴充的值。

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

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 版本號碼：

Android 版本	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