fuchsia.hardware.audio

新增日期:7

通訊協定

編碼器

fuchsia.hardware.audio/codec.fidl 定義

如需總覽資訊,請參閱 [Audio Codec Interface]

淘汰

已不再支援,請改用含有單一 DAI 的音訊複合且沒有環狀緩衝區,請參閱音訊驅動程式架構

已淘汰:20

GetDaiFormats

擷取轉碼器支援的 DAI 格式。如果屆時無法使用,轉碼器回覆錯誤狀態,且控制器稍後可能會重試。當系統支援 DaiSupportedFormats 內的參數專屬組合時,擷取多個 DaiSupportedFormats 會允許擷取。

要求

<EMPTY>

回應

名稱類型
payload Codec_GetDaiFormats_Result

GetHealthState

擷取頂層健康狀態。駕駛人未及時回應,代表驅動程式庫有健康狀態不良的跡象。

要求

<EMPTY>

回應

名稱類型
state HealthState

GetProperties

擷取頂層靜態屬性。

新增日期:20 位

要求

<EMPTY>

回應

名稱類型
properties CodecProperties

IsBridgeable

傳回轉碼器是否可橋接。

淘汰

不再支援,在執行階段無法再變更橋接設定。驅動程式仍可設為在橋接模式下運作,或不在開機時運作。

已淘汰:17

要求

<EMPTY>

回應

名稱類型
supports_bridged_mode bool

重設

重設轉碼器。重設完成時會傳回 Reset。如果驅動程式庫無法成功重設轉碼器,系統將會關閉轉碼器通訊協定通道,在此情況下,用戶端可能會取得新的轉碼器通訊協定管道並重試。

要求

<EMPTY>

回應

<EMPTY>

SetBridgedMode

設定轉碼器的橋接模式。此為必要方法,但只有在轉碼器支援 IsBridgeable 的回覆指定的橋接模式時,才需要採取行動。

淘汰

不再支援,在執行階段無法再變更橋接設定。驅動程式仍可設為在橋接模式下運作,或不在開機時運作。

已淘汰:17

要求

名稱類型
enable_bridged_mode bool

SetDaiFormat

設定控制器與轉碼器之間的介面要使用的 DAI 格式。如果請求時不支援,系統會傳回錯誤 (例如可卸除式硬體)。

要求

名稱類型
format DaiFormat

回應

名稱類型
payload Codec_SetDaiFormat_Result

SignalProcessingConnect

連線至 SignalProcessing 通訊協定。如果系統不支援新的連線要求 (例如已建立的連線數量上限,例如已建立的連線數量上限),protocol 管道 (而非呼叫 SignalProcessingConnect 的管道) 就會以 ZX_ERR_ALREADY_BOUND 隆重關閉。如果完全不支援信號處理,則 protocol 管道 (再次,而不是呼叫 SignalProcessingConnect 的管道) 將會以 ZX_ERR_NOT_SUPPORTED 復原基因關閉。此方法將命名為 SignalProcessingConnect,而不是 Connect,因為這個通訊協定應進行撰寫,因此詳細名稱能夠區分差異,提升清晰度。

要求

名稱類型
protocol server_end<fuchsia.hardware.audio.signalprocessing/SignalProcessing>

開始

啟動/重新啟動轉碼器作業。Start 會在程式碼啟動作業設定完成後傳回。這個方法不會等待硬體實際啟動播放/擷取作業 (也就是說,系統不會將 turn_on_delay 影響納入考量),也不會在傳回的 start_time 中反映任何此類延遲。start_time 表示驅動程式庫已完成編碼器設定的啟動時間,如 CLOCK_MONOTONIC 時間軸所示。如果驅動程式庫無法成功啟動轉碼器,則會關閉轉碼器通訊協定管道,在此情況下,用戶端可能會取得新的轉碼器通訊協定管道並重試。

要求

<EMPTY>

回應

名稱類型
start_time zx/Time

停止

停止轉碼器作業。當轉碼器設為停止時,Stop 會傳回。這個方法不會等待硬體確實停止播放/擷取 (也就是說,不會考量 turn_off_delay 的影響),傳回的 stop_time 也不會反映任何此類延遲。stop_time 表示驅動程式庫設定停止的轉碼器的時間,如 CLOCK_MONOTONIC 時間軸所測量。如果驅動程式庫無法成功將轉碼器設為停止,就會關閉轉碼器通訊協定管道,此時用戶端可能會取得新的轉碼器通訊協定管道並重試。

要求

<EMPTY>

回應

名稱類型
stop_time zx/Time

WatchPlugState

透過掛斷程序取得插座偵測狀態。驅動程式會回覆用戶端傳送的第一個 WatchPlugState。等到外掛程式狀態與最近回報的內容不同時,驅動程式才會回應後續的用戶端 WatchPlugState 呼叫。

要求

<EMPTY>

回應

名稱類型
plug_state PlugState

CodecConnector

定義於 fuchsia.hardware.audio/codec_connector.fidl

如需轉碼器通訊協定總覽,請參閱 Codec 介面

淘汰

已不再支援,請改用含有單一 DAI 的音訊複合且沒有環狀緩衝區,請參閱音訊驅動程式架構

已淘汰:20

連線

連線至轉碼器通訊協定伺服器。這個轉換為 Codec 通訊協定的間接用途,可讓我們支援獨立的轉碼器用戶端連線。

要求

名稱類型
codec_protocol server_end<Codec>

合成物

定義於 fuchsia.hardware.audio/Composite.fidl

Composite 介面是音訊驅動程式提供的 FIDL 通訊協定。Composite 介面為一般介面,可讓您設定各種音訊硬體類型,包括 StreamConfigDaiCodec FIDL 介面支援的設定。Composite 介面較為通用,並在音訊子系統內提供更靈活的轉送功能。另請參閱音訊驅動程式複合材料

新增時間:12 張

CreateRingBuffer

用戶端會傳送 CreateRingBuffer,以便為 processing_element_id 指定的 RING_BUFFER ENDPOINT 類型處理元素選取環形緩衝區格式。格式取決於驅動程式庫在 GetRingBufferFormats 中提供的資訊、用戶端支援的內容,以及任何其他要求。傳回的 ring_buffer 管道可用來存取及控制驅動程式庫提供的音訊緩衝區。如果 processing_element_idGetElements 傳回的 ID 不符,系統會傳回 INVALID_ARGS。如果 ID 所代表元素的 ElementType 不是帶有 EndpointType RING_BUFFERENDPOINT,則傳回 WRONG_TYPE

要求

名稱類型
processing_element_id uint64
format Format
ring_buffer server_end<RingBuffer>

回應

名稱類型
payload Composite_CreateRingBuffer_Result

GetDaiFormats

在由 GetElements 從 fuchsia.hardware.audio.signalprocessing 傳回的拓撲中,擷取此驅動程式庫程式支援的 DAI_INTERCONNECT ENDPOINT 類型處理元素支援的 DAI 格式。如果無法使用 DAI 格式,則傳回 SHOULD_WAIT,用戶端可於日後重試。如果 processing_element_idGetElements 傳回的 ID 不符,系統會傳回 INVALID_ARGS。如果 ID 所代表元素的 ElementType 不是帶有 EndpointType DAI_INTERCONNECTENDPOINT,則傳回 WRONG_TYPE。在系統也支援支援格式中的專屬參數組合時,擷取多個 DaiSupportedFormats

要求

名稱類型
processing_element_id uint64

回應

名稱類型
payload Composite_GetDaiFormats_Result

GetHealthState

擷取頂層健康狀態。駕駛人未及時回應,代表驅動程式庫有健康狀態不良的跡象。

要求

<EMPTY>

回應

名稱類型
state HealthState

GetProperties

擷取頂層靜態屬性。

要求

<EMPTY>

回應

名稱類型
properties CompositeProperties

GetRingBufferFormats

在由 GetElements 從 fuchsia.hardware.audio.signalprocessing 傳回的拓撲中,擷取此驅動程式庫支援的 RING_BUFFER ENDPOINT 類型處理元素支援的環形緩衝區格式。如果日後無法使用環形緩衝區格式,則會傳回 SHOULD_WAIT,用戶端可以稍後重試。如果 processing_element_idGetElements 傳回的 ID 不符,系統會傳回 INVALID_ARGS。如果 ID 所代表元素的 ElementType 不是帶有 EndpointType RING_BUFFERENDPOINT,則傳回 WRONG_TYPE。當系統支援 SupportedFormats 中的參數專屬組合時,擷取多個 SupportedFormats 可支援。

要求

名稱類型
processing_element_id uint64

回應

名稱類型
payload Composite_GetRingBufferFormats_Result

重設

重設硬體,包括所有 DAI 互連網路和信號處理。因此,CreateRingBuffer 取得的所有頻道都將關閉。

硬體完全重設後會傳回 Reset。此時,用戶端必須重新設定任何 DAI 互連網路、選取信號處理拓撲,並重新設定任何處理元素,並重建任何環形緩衝區。

如果驅動程式庫無法成功重設硬體,則會傳回錯誤並關閉通訊協定管道,在此情況下,用戶端可能會取得新的通訊協定管道並重試。

要求

<EMPTY>

回應

名稱類型
payload Composite_Reset_Result

SetDaiFormat

用戶端會傳送 SetDaiFormat,以便為 processing_element_id 指定的 DAI_INTERCONNECT ENDPOINT 類型處理元素選取 DAI 格式。格式取決於驅動程式庫在 GetDaiFormats 中提供的資訊、用戶端支援的內容,以及任何其他要求。如果 processing_element_idGetElements 傳回的 ID 不符,系統會傳回 INVALID_ARGS。如果 ID 所代表元素的 ElementType 不是帶有 EndpointType DAI_INTERCONNECTENDPOINT,則傳回 WRONG_TYPE

要求

名稱類型
processing_element_id uint64
format DaiFormat

回應

名稱類型
payload Composite_SetDaiFormat_Result

SignalProcessingConnect

連線至 SignalProcessing 通訊協定。如果系統不支援新的連線要求 (例如已建立的連線數量上限,例如已建立的連線數量上限),protocol 管道 (而非呼叫 SignalProcessingConnect 的管道) 就會以 ZX_ERR_ALREADY_BOUND 隆重關閉。如果完全不支援信號處理,則 protocol 管道 (再次,而不是呼叫 SignalProcessingConnect 的管道) 將會以 ZX_ERR_NOT_SUPPORTED 復原基因關閉。此方法將命名為 SignalProcessingConnect,而不是 Connect,因為這個通訊協定應進行撰寫,因此詳細名稱能夠區分差異,提升清晰度。

要求

名稱類型
protocol server_end<fuchsia.hardware.audio.signalprocessing/SignalProcessing>

CompositeConnector

定義於 fuchsia.hardware.audio/Composite_connector.fidl

如需總覽資訊,請參閱音訊複合裝置

新增時間:12 張

連線

連線至 Device 通訊協定。這個方法可讓元件在開發主機之外提供 FIDL。

要求

名稱類型
composite_protocol server_end<Composite>

大自然

定義於 fuchsia.hardware.audio/dai.fidl

如需總覽資訊,請參閱「數位音訊介面」。

淘汰

已不再支援,請改用含有一個 DAI 和一個環形緩衝區的音訊複合。請參閱音訊驅動程式架構

已淘汰:20

CreateRingBuffer

用戶端會傳送 CreateRingBuffer,以便根據驅動程式庫在 GetDaiFormatsGetRingBufferFormats 中提供的資訊、用戶端支援的內容以及任何其他要求,選取 DAI 格式和環形緩衝區格式。ring_buffer 管道可用來控制音訊緩衝區,如果先前的環形緩衝區管道已建立完成且仍處於使用中狀態,驅動程式庫必須關閉該 (環狀緩衝區) 管道,並盡可能在每次處理過程中優雅退出。

要求

名稱類型
dai_format DaiFormat
ring_buffer_format Format
ring_buffer server_end<RingBuffer>

GetDaiFormats

擷取 DAI 支援的 DAI 格式。如果屆時 DAI 都不適用,則 DAI 可能會回覆錯誤狀態,且用戶端稍後可能會重試。在系統也支援支援格式中的專屬參數組合時,擷取多個 DaiSupportedFormats

要求

<EMPTY>

回應

名稱類型
payload Dai_GetDaiFormats_Result

GetHealthState

擷取頂層健康狀態。駕駛人未及時回應,代表驅動程式庫有健康狀態不良的跡象。

要求

<EMPTY>

回應

名稱類型
state HealthState

GetProperties

擷取頂層靜態屬性。

要求

<EMPTY>

回應

名稱類型
properties DaiProperties

GetRingBufferFormats

擷取 DAI 支援的環形緩衝區格式。如果屆時無法使用,DAI 可能會回覆錯誤狀態,且用戶端稍後可能會重試。當系統支援 SupportedFormats 中的參數專屬組合時,擷取多個 SupportedFormats 可支援。

要求

<EMPTY>

回應

名稱類型
payload Dai_GetRingBufferFormats_Result

重設

重設 DAI HW。驅動程式庫可能會關閉透過 CreateRingBuffer 取得的 ring_buffer 管道,在這種情況下,用戶端需要取得新的 ring_buffer。重設完成時,Reset 會傳回。如果驅動程式庫無法成功重設 HW,便會關閉 DAI 通訊協定管道。在這種情況下,用戶端可能會取得新的 DAI 通訊協定管道並重試。

要求

<EMPTY>

回應

<EMPTY>

SignalProcessingConnect

連線至 SignalProcessing 通訊協定。如果系統不支援新的連線要求 (例如已建立的連線數量上限,例如已建立的連線數量上限),protocol 管道 (而非呼叫 SignalProcessingConnect 的管道) 就會以 ZX_ERR_ALREADY_BOUND 隆重關閉。如果完全不支援信號處理,則 protocol 管道 (再次,而不是呼叫 SignalProcessingConnect 的管道) 將會以 ZX_ERR_NOT_SUPPORTED 復原基因關閉。此方法將命名為 SignalProcessingConnect,而不是 Connect,因為這個通訊協定應進行撰寫,因此詳細名稱能夠區分差異,提升清晰度。

要求

名稱類型
protocol server_end<fuchsia.hardware.audio.signalprocessing/SignalProcessing>

DaiConnector

定義於 fuchsia.hardware.audio/dai_connector.fidl

如需 DAI 通訊協定的總覽,請參閱數位音訊介面

淘汰

已不再支援,請改用含有一個 DAI 和一個環形緩衝區的音訊複合。請參閱音訊驅動程式架構

已淘汰:20

連線

這會連線至 DAI 通訊協定伺服器。

要求

名稱類型
dai_protocol server_end<Dai>

健康生活

定義於 fuchsia.hardware.audio/health.fidl

GetHealthState

擷取頂層健康狀態。駕駛人未及時回應,代表驅動程式庫有健康狀態不良的跡象。

要求

<EMPTY>

回應

名稱類型
state HealthState

RingBuffer

定義於 fuchsia.hardware.audio/ring_buffer.fidl

GetProperties

頂層靜態屬性的存取子。

要求

<EMPTY>

回應

名稱類型
properties RingBufferProperties

GetVmo

要求共用緩衝區,以便在用戶端和驅動程式庫之間移動大量音訊資料。 用戶端要求 min_frames 做為環形緩衝區所需的部分大小。驅動程式會傳回 num_frames 中分配的環形緩衝區空間的實際大小。

num_frames 必須至少為 min_frames 加上 driver_transfer_bytes (在頁框中),讓環形緩衝區內容可以傳入和傳出,否則呼叫必須因 GetVmoError.INVALID_ARGS 失敗。

驅動程式可能會基於任何內部要求,例如對齊執行個體,將環形緩衝區大小增加超過 min_frames 加上 driver_transfer_bytes (在頁框中)。

用戶端可將整個傳回的環形緩衝區視為可存取的安全,但 driver_transfer_bytes 會緊接在目前位置附近的 driver_transfer_bytes 除外,詳情請參閱 RingBufferProperties 中的 driver_transfer_bytes 參數規格。

如果 clock_recovery_notifications_per_ring 非零,驅動程式庫會以最多 clock_recovery_notifications_per_ring 頻率回應 WatchClockRecoveryPositionInfo 用戶端要求。這類通知旨在用於復原時鐘。

要求

名稱類型
min_frames uint32
clock_recovery_notifications_per_ring uint32

回應

名稱類型
payload RingBuffer_GetVmo_Result

SetActiveChannels

透過位元遮罩設定使用中的管道。最小的位元對應管道索引 0。不在位元遮罩中設定的管道 (位元數為 0) 已停用。停用中的管道會向驅動程式庫表示可能會關閉與非使用中管道相關聯的硬體。後續的 SetActiveChannels 將停用的管道設為有效狀態時,可能會在 turn_on_delay 中實際重新啟動播放/擷取頻道。管道總數為 Format 中的 number_of_channels,特別是在 PcmFormat 中。也就是說,這個位元遮罩最多可以設定 number_of_channels 位元 (上限為 64 個)。停用一個、多個或所有頻道時,系統不會Stop環狀緩衝區。SetActiveChannels 不會變更與 Start/Stop 相關的環形緩衝區行為,特別是位置。呼叫 Start 後,無論活躍管道的數量為何 (包括沒有使用的頻道),環形緩衝區的位置變化 (以及視需要傳送的位置通知)。這表示環形緩衝區中的格式並未變更。根據預設,所有頻道皆為有效。 如果驅動程式庫不支援停用通道,則必須傳回 ZX_ERR_NOT_SUPPORTED。如果遮罩不正確,也就是讓超過位元數量的管道可供特定 number_of_channels 使用,則驅動程式庫必須傳回 ZX_ERR_INVALID_ARGSset_time 值 (在 CLOCK_MONOTONIC 時間軸中) 表示硬體要啟用或停用版本的設定作業已完成。set_time 不包含潛在的 turn_on_delay,驅動程式庫不會延遲等待硬體實際開啟的回覆,而驅動程式庫不會延遲回應,並顯示 set_time 表示硬體設定完成時間。如果要求的管道設定已經啟用,傳回的 set_time 可以在呼叫 SetActiveChannels 之前,但必須在回覆傳送前。如果在使用相同的設定再次呼叫,回覆必須包含先前傳回的 set_time 值。若是輸入管道,則不需要驅動程式庫零停止使用管道。如果系統在第一次呼叫完成前第二次呼叫 SetActiveChannels,則必須關閉管道,並傳回 ZX_ERR_BAD_STATE 錯誤。

要求

名稱類型
active_channels_bitmask uint64

回應

名稱類型
payload RingBuffer_SetActiveChannels_Result

開始

啟動環形緩衝區。start_time 值 (在 CLOCK_MONOTONIC 時間軸中) 表示位置開始移動的時間,從環形緩衝區的起點開始。也就是說,驅動程式庫/HW 已開始讀取或寫入環形緩衝區位置 0,取決於 driver_transfer_bytes 中所述的緩衝區。

如果在 SetActiveChannels 之前呼叫 Start,在預設情況下,所有頻道都會處於有效狀態。如果在 GetVmo 之前呼叫 Start,則必須使用 ZX_ERR_BAD_STATE 關閉管道。如果在這個 RingBuffer 啟動時呼叫 Start,或在第一次呼叫完成前再次呼叫 Start,就必須關閉管道,並傳回 ZX_ERR_BAD_STATE 錯誤。

要求

<EMPTY>

回應

名稱類型
start_time zx/Time

停止

停止環形緩衝區。收到此呼叫的回應後,除非再次呼叫 Start,否則不會再傳送位置通知。如果在 GetVmo 之前呼叫 Stop,或在第一次呼叫完成前第二次呼叫 Stop,則必須使用 ZX_ERR_BAD_STATE 關閉管道。

要求

<EMPTY>

回應

<EMPTY>

WatchClockRecoveryPositionInfo

透過懸掛式取得取得環形緩衝區的目前位置。驅動程式必須回應用戶端的第一次 WatchClockRecoveryPositionInfo 呼叫,但除非位置資訊與最近提供給用戶端的資訊不同,否則不會回應後續的用戶端呼叫。駕駛人必須先回覆 Start 指令,才能回應 WatchClockRecoveryPositionInfo。在 Start 傳回的 start_time 中,位置一律為 0。之後,追蹤速度會按速率、取樣格式 (如果裝置與 CLOCK_MONOTONIC 網域不同,則以指定速率為準)。如果 clock_recovery_notifications_per_ring 不為零,驅動程式庫會回應預估的位置,以在 clock_recovery_notifications_per_ring 頻率內用於時鐘復原。只有在呼叫 GetVmo 後才能呼叫 WatchClockRecoveryPositionInfo,因此必須指定 clock_recovery_notifications_per_ring。提交時的時間戳記必須為單調遞增。如果這個用戶端已有待處理的 WatchClockRecoveryPositionInfo,驅動程式會關閉發生錯誤的 ZX_ERR_BAD_STATE 管道。

要求

<EMPTY>

回應

名稱類型
position_info RingBufferPositionInfo

WatchDelayInfo

取得候車航班的誤點資訊。驅動程式會立即回覆用戶端傳送的第一個 WatchDelayInfo。除非最近一次回報的延遲時間資訊改變,否則駕駛人不會回應後續的用戶端 WatchDelayInfo 呼叫。如果系統在第一次呼叫完成前第二次呼叫 WatchDelayInfo,則必須關閉管道,並傳回 ZX_ERR_BAD_STATE 錯誤。

已新增:HEAD

要求

<EMPTY>

回應

名稱類型
delay_info DelayInfo

StreamConfig

定義於 fuchsia.hardware.audio/stream_config.fidl

如需總覽資訊,請參閱音訊驅動程式串流介面

淘汰

系統不再支援,請改用含有單一環形緩衝區的音訊複合。請參閱音訊驅動程式架構

已淘汰:20

CreateRingBuffer

用戶端會傳送 CreateRingBuffer,根據驅動程式庫在 GetSupportedFormats 中支援、用戶端支援以及任何其他要求的資訊,選取串流格式。ring_buffer 管道可用來控制音訊緩衝區,如果先前的環形緩衝區管道已建立完成且仍在使用中,驅動程式庫必須關閉該 (環形緩衝區) 管道,並盡可能在過程中妥善退出所有進行中的串流作業。

要求

名稱類型
format Format
ring_buffer server_end<RingBuffer>

GetHealthState

擷取頂層健康狀態。駕駛人未及時回應,代表驅動程式庫有健康狀態不良的跡象。

要求

<EMPTY>

回應

名稱類型
state HealthState

GetProperties

擷取頂層靜態屬性。

要求

<EMPTY>

回應

名稱類型
properties StreamProperties

GetSupportedFormats

取得指定驅動程式庫支援的格式。當驅動程式庫支援的所有組合都無法以一個 SupportedFormats 描述時,驅動程式庫會在傳回的向量中傳回多個 SupportedFormats。例如,如果一個 SupportedFormats 允許 48KHz 的 32 位元樣本,以及 96KHz 的 16 位元樣本,而非 96KHz 的 32 位元樣本,則驅動程式庫會使用 2 SupportedFormats、<48KHz>> 和 <<16bit> 回應,將取樣率設為 <96KHz>,並忽略其他樣本。如果驅動程式庫支援 48 或 96KHz 的 16 或 32 位元樣本,驅動程式庫會使用 1 SupportedFormats 回應:<<16bits,32bits>、<48KHz,96KHz>>。

要求

<EMPTY>

回應

名稱類型
supported_formats vector<SupportedFormats>[64]

SetGain

用戶端更新成功狀態。

要求

名稱類型
target_state GainState

SignalProcessingConnect

連線至 SignalProcessing 通訊協定。如果系統不支援新的連線要求 (例如已建立的連線數量上限,例如已建立的連線數量上限),protocol 管道 (而非呼叫 SignalProcessingConnect 的管道) 就會以 ZX_ERR_ALREADY_BOUND 隆重關閉。如果完全不支援信號處理,則 protocol 管道 (再次,而不是呼叫 SignalProcessingConnect 的管道) 將會以 ZX_ERR_NOT_SUPPORTED 復原基因關閉。此方法將命名為 SignalProcessingConnect,而不是 Connect,因為這個通訊協定應進行撰寫,因此詳細名稱能夠區分差異,提升清晰度。

要求

名稱類型
protocol server_end<fuchsia.hardware.audio.signalprocessing/SignalProcessing>

WatchGainState

透過懸掛項目取得狀態。驅動程式會回應用戶端傳送的第一個 WatchGainState,且此回覆必須包含設為 0 dB 以下的 gain_db。除非取得最新回報的狀態變更,否則驅動程式不會回應後續的用戶端 WatchGainState 呼叫。如果系統在第一個呼叫完成前第二次呼叫 WatchGainState,通訊協定管道就必須關閉,並顯示 ZX_ERR_BAD_STATE 錯誤。

要求

<EMPTY>

回應

名稱類型
gain_state GainState

WatchPlugState

透過掛斷程序取得插座偵測狀態。驅動程式會回覆用戶端傳送的第一個 WatchPlugState。等到外掛程式狀態與最近回報的內容不同時,驅動程式才會回應後續的用戶端 WatchPlugState 呼叫。如果系統在第一個呼叫完成前第二次呼叫 WatchPlugState,通訊協定管道就必須關閉,並顯示 ZX_ERR_BAD_STATE 錯誤。

要求

<EMPTY>

回應

名稱類型
plug_state PlugState

StreamConfigConnector

定義於 fuchsia.hardware.audio/stream_config_connector.fidl

如需總覽資訊,請參閱音訊驅動程式串流介面

淘汰

系統不再支援,請改用含有單一環形緩衝區的音訊複合。請參閱音訊驅動程式架構

已淘汰:20

連線

連線至 StreamConfig 通訊協定。這個方法可讓元件在開發主機之外提供 FIDL。

要求

名稱類型
protocol server_end<StreamConfig>

結構化

Codec_GetDaiFormats_Response

定義於 fuchsia.hardware.audio/codec.fidl

廣闊類型說明預設
formats vector<DaiSupportedFormats>[64] 無預設

Codec_SetDaiFormat_Response

定義於 fuchsia.hardware.audio/codec.fidl

廣闊類型說明預設
state CodecFormatInfo 無預設

Composite_CreateRingBuffer_Response

定義於 fuchsia.hardware.audio/Composite.fidl

<EMPTY>

Composite_GetDaiFormats_Response

定義於 fuchsia.hardware.audio/Composite.fidl

廣闊類型說明預設
dai_formats vector<DaiSupportedFormats>[64] 無預設

Composite_GetRingBufferFormats_Response

定義於 fuchsia.hardware.audio/Composite.fidl

廣闊類型說明預設
ring_buffer_formats vector<SupportedFormats>[64] 無預設

Composite_Reset_Response

定義於 fuchsia.hardware.audio/Composite.fidl

<EMPTY>

Composite_SetDaiFormat_Response

定義於 fuchsia.hardware.audio/Composite.fidl

<EMPTY>

DaiFormat

fuchsia.hardware.audio/dai_format.fidl

動態廣告插播格式。影格由 number_of_channels 樣本組成,bits_per_sample位元資料位在 bits_per_slot 內,frame_format。詳情請參閱「數位音訊介面」。

廣闊類型說明預設
number_of_channels uint32

頻道數。

無預設
channels_to_use_bitmask uint64

透過位元遮罩設定使用中的管道。最低顯著的位元對應管道索引 0。

無預設
sample_format DaiSampleFormat

所有樣本的範例格式。

無預設
frame_format DaiFrameFormat

所有樣本的影格格式。

無預設
frame_rate uint32

所有樣本的影格速率。

無預設
bits_per_slot uint8

所有聲道的每個運算單元位元數。

無預設
bits_per_sample uint8

所有樣本的每個樣本位元。必須小於每個管道的位元數,樣本才能符合。

無預設

DaiFrameFormatCustom

fuchsia.hardware.audio/dai_format.fidl

自訂頁框格式。

廣闊類型說明預設
left_justified bool

運算單元中樣本的理由。

無預設
sclk_on_raising bool

調整資料樣本和影格同步輸出內容的時鐘狀態 (分別升起或跌倒)。如果為 true,則螺絲會隨資料和影格同步的上升邊緣升高,也就是說,資料會取樣於 Sclk 週期中間的落邊邊緣。因此,如果設為 False,系統會對增加的滑石邊緣取樣資料。

無預設
frame_sync_sclks_offset int8

影格同步變更開始與音訊樣本之間的螺絲數量。 例如,I2S 設為 1,而左聲道左右對齊設為 0。

無預設
frame_sync_size uint8

影格同步處理作業中高聳入鏡的剪刀數量過高。 舉例來說,如果是將 32 位元運算單元設為 32 的 I2S,TDM 通常會設為 1。

無預設

DaiSupportedFormats

fuchsia.hardware.audio/dai_format.fidl

DAI 支援的格式。影格由 number_of_channels 樣本組成,bits_per_sample位元資料採 bits_per_slot 位元,frame_formats每個向量列出的所有值都受到支援。當驅動程式庫支援的所有組合都無法以一個 DaiSupportedFormats 描述時,GetDaiSupportedFormats 會在傳回的向量中傳回多個 DaiSupportedFormats。詳情請參閱「數位音訊介面」。

廣闊類型說明預設
number_of_channels vector<uint32>[64]

可能支援的頻道數量。

無預設
sample_formats vector<DaiSampleFormat>[4]

支援的範例格式。

無預設
frame_formats vector<DaiFrameFormat>[64]

支援影格格式。

無預設
frame_rates vector<uint32>[64]

支援費率。值必須以遞增方式列出。

無預設
bits_per_slot vector<uint8>[8]

每個版位支援的位元數。值必須以遞增方式列出。

無預設
bits_per_sample vector<uint8>[8]

每個樣本支援位元數。值必須以遞增方式列出。

無預設

Dai_GetDaiFormats_Response

定義於 fuchsia.hardware.audio/dai.fidl

廣闊類型說明預設
dai_formats vector<DaiSupportedFormats>[64] 無預設

Dai_GetRingBufferFormats_Response

定義於 fuchsia.hardware.audio/dai.fidl

廣闊類型說明預設
ring_buffer_formats vector<SupportedFormats>[64] 無預設

PcmFormat

fuchsia.hardware.audio/ring_buffer_format.fidl 定義

此格式支援非壓縮 PCM 音訊。影格由 number_of_channels 樣本組成,樣本的 valid_bits_per_sample 位元是 bytes_per_sample 中最重要的 (靠左對齊) 資料。位元組。詳情請參閱音訊驅動程式串流介面

廣闊類型說明預設
number_of_channels uint8

頻道數。

無預設
sample_format SampleFormat

所有樣本的格式。

無預設
bytes_per_sample uint8

分配用於保留樣本的位元組數,等於或大於 valid_bits_per_sample 中有效樣本大小。

無預設
valid_bits_per_sample uint8

樣本中的有效位元數必須等於或小於 bytes_per_sample 中的位元。如果位元較小,位元經過左右對齊,接收端必須忽略其他位元。

無預設
frame_rate uint32

所有樣本的影格速率。

無預設

RingBufferPositionInfo

定義於 fuchsia.hardware.audio/ring_buffer.fidl

廣闊類型說明預設
timestamp zx/Time

驅動程式的最佳預估時間 (在 CLOCK_MONOTONIC 時間軸中),即播放/擷取指標到達 position 指定位置的時間。turn_on_delay 影響不應納入「時間戳記」。不應整合 DelayInfo 中指出的延遲情形。

無預設
position uint32

驅動程式庫在 timestamp 時,環形緩衝區中的播放/擷取指標位置 (以位元組為單位)。

無預設

RingBuffer_GetVmo_Response 資源

定義於 fuchsia.hardware.audio/ring_buffer.fidl

廣闊類型說明預設
num_frames uint32 無預設
ring_buffer handle<vmo> 無預設

RingBuffer_SetActiveChannels_Response

定義於 fuchsia.hardware.audio/ring_buffer.fidl

廣闊類型說明預設
set_time zx/Time 無預設

ENUMS

DaiFrameFormatStandard 嚴格

類型:uint8

fuchsia.hardware.audio/dai_format.fidl

標準影格格式。

名稱物超所值說明
1

沒有影格格式,如沒有 PDM 等影格同步。

2

按照 I2S 規格指定格式 (左側左右對齊、2 個聲道、每個管道 32 位元、左管道的影格同步一直維持低,在右管道中保持高,但在影格同步在 Sclk 的下降邊緣變更時,資料會開始一個時鐘週期)。

3

靠左對齊,2 個頻道。資料會在影格同步時從低到高的 Sclk 滑出變更。第一個聲道的位元 s_per_channel 位元必須維持高影格同步處理作業,而第二個管道的位元數_per_channel 位元較低。

4

左右對齊,2 個頻道。第一個聲道的位元 s_per_channel 位元必須維持高影格同步處理作業,而第二個管道的位元數_per_channel 位元較低。

5

靠左對齊,管道數量不定,資料在影格同步時開始,會在絲條升降邊緣由低至高顯示。影格同步必須維持在高時間,然後剛好 1 個時鐘週期。

6

靠左對齊的管道數量會變動,資料會在影格從低到高的絲綠色從低到高的時鐘開始同步後開始一個時鐘週期。影格同步必須保持在較高時間,直到 1 個時鐘週期。

新增日期:10 位
7

靠左對齊的通道數量會變,資料會在影格從低到高的 Sclk 上升邊緣從低到高的時鐘開始同步後開始兩個時鐘週期。影格同步必須保持在較高時間,直到 1 個時鐘週期。

新增日期:10 位

DaiSampleFormat 嚴格

類型:uint8

定義於 fuchsia.hardware.audio/dai_format.fidl

名稱物超所值說明
1

Pulse Density Modulation 範例。

2

主機端端的帶正負號整數線性脈動程式碼調解樣本。

3

主機尾端的無帶正負號整數線性 Pulse 程式碼調換樣本。

4

浮點樣本,依據 IEEE-754 標準編碼。

DeviceType 彈性

類型:uint32

fuchsia.hardware.audio/device_type.fidl

新增日期:14 天

名稱物超所值說明
1

裝置支援 fuchsia.hardware.audio/StreamConfig 通訊協定。

2

裝置支援 fuchsia.hardware.audio/Dai 通訊協定。

3

裝置支援 fuchsia.hardware.audio/Codec 通訊協定。

4

裝置支援 fuchsia.hardware.audio/Composite 通訊協定。

DriverError 彈性

類型:uint32

定義於 fuchsia.hardware.audio/common.fidl

新增時間:12 張

名稱物超所值說明
1

驅動程式在執行作業時遇到未指定的錯誤。

2

未實作、支援或啟用作業。

3

有一個引數無效。

4

作業主體不是執行作業的類型錯誤。

5

目前無法執行作業,但如果呼叫端等待滿足必要條件,則可能會成功。

GetVmoError 嚴格

類型:uint32

定義於 fuchsia.hardware.audio/ring_buffer.fidl

名稱物超所值說明
1

引數無效,因此無法設定環形緩衝區,例如 min_frames 太大。

2

發生內部錯誤,因此無法設定環形緩衝區。

PlugDetectCapabilities 嚴格

類型:uint32

定義於 fuchsia.hardware.audio/plug.fidl

名稱物超所值說明
0

驅動程式採用有線連接 (一律連接電源)。

1

驅動程式能以非同步方式通知插座狀態變更。

範例格式嚴格

類型:uint8

定義於 fuchsia.hardware.audio/ring_buffer_format.fidl

名稱物超所值說明
1

主機端端的帶正負號整數線性脈動程式碼調解樣本。

2

主機尾端的無帶正負號整數線性 Pulse 程式碼調換樣本。

3

浮點樣本,依據 IEEE-754 標準編碼。

資料表

ChannelAttributes

fuchsia.hardware.audio/ring_buffer_format.fidl 定義

單一管道在整體管道設定中的規格。

序數廣闊類型說明
min_frequency uint32

以 Hz 為單位保證此管道發出 (或擷取) 的最低頻率。如未納入 min_frequency,系統會假設此管道涵蓋裝置的整個低頻率範圍。

選用。

max_frequency uint32

保證會以此管道發出 (或擷取) 最高頻率,以 Hz 為單位。如未加入 max_frequency,系統會假設此通道涵蓋這部裝置的整個高頻率範圍。

選用。

ChannelSet

fuchsia.hardware.audio/ring_buffer_format.fidl 定義

管道設定的規格。

序數廣闊類型說明
attributes vector<ChannelAttributes>[64]

說明此管道集的屬性。這個向量的大小定義了這個 ChannelSet 支援的通道數。attributes 向量的每個元素都定義了單一管道的屬性。

必填。

CodecFormatInfo

fuchsia.hardware.audio/codec.fidl 定義

轉碼器格式資訊。

序數廣闊類型說明
external_delay zx/Duration

針對所選格式,驅動程式中呈現的外部延遲時間 (以奈秒為單位) 的最佳預測結果。精確地同步處理多個實體 (例如裝置) 的呈現時,應將外部延遲納入考量。如未加入,external_delay 就不會出現。

選用。

turn_on_delay zx/Duration

驅動程式在發出 Start 指令後,實際啟動播放/擷取作業所需的最佳時間 (以奈秒為單位)。硬體可能需要一段時間才能進入完整運作模式,例如電源狀態變更所致。如果系統不接受播放或擷取的初始音訊樣本,則必須將這類延遲納入考量。如未加入,turn_on_delay 就不會出現。

選用。

turn_off_delay zx/Duration

驅動程式在發出 Stop 指令後,實際停止播放/擷取所需的時間 (以奈秒為單位) 最佳預估時間。硬體可能需要一段時間才能進入完全停止模式,例如電源狀態變更的緣故。如果無法在「Stop」指令後播放/擷取樣本,則必須將這類延遲時間納入考量。如果未包含在內,表示關閉延遲時間不明。

選用。

CodecProperties

fuchsia.hardware.audio/codec.fidl 定義

新增日期:20 位

序數廣闊類型說明
is_input bool

如果驅動程式類型為輸入 (true) 或輸出 (false),如未一併指定,則驅動程式庫可以同時用於輸入和輸出。

選用。

manufacturer string[256]

製造商名稱的 UI 字串。如未指定,則未指定製造商。

選用。

product string[256]

產品名稱的 UI 字串。如未加入,則表示未指定產品名稱。

選用。

unique_id uint8[16]

轉碼器的專屬 ID。如未加入,就不會有轉碼器的專屬 ID。

選用。

plug_detect_capabilities PlugDetectCapabilities

插頭偵測功能。

必填。

CompositeProperties

定義於 fuchsia.hardware.audio/Composite.fidl

新增時間:12 張

序數廣闊類型說明
manufacturer string[256]

製造商名稱的 UI 字串。如果未設定,就無法得知製造商。

選用。

product string[256]

產品名稱的 UI 字串。如果未設定,系統就會得知產品名稱。

選用。

unique_id uint8[16]

專屬 ID。如果未指定,裝置就不會有專屬 ID。開頭為 0x42、0x54 ... (或 ASCII 中的 BT) 的 unique_id 陣列,已提供給實作藍牙技術的驅動程式。開頭為 0x55、0x53、0x42... (或 ASCII 中的 USB) 的 unique_id 陣列會保留給實作 USB 技術的驅動程式。請注意,即使上述值對應到可讀取的 ASCII 字元,陣列值仍可橫跨整個 uint8 範圍 (0-255)。

選用。

clock_domain ClockDomain

這個硬體在時鐘網域的 ID。如果兩部硬體裝置的時鐘網域相同,兩者的時鐘速率相同且無縫同步。雖然這兩個時鐘的速率相同,但時鐘位置可能會以任意 (但固定) 量偏移。Clock_domain 通常來自於系統通用的實體,例如平台匯流排或全域時鐘樹狀結構。

有兩個特殊值:

  • CLOCK_DOMAIN_MONOTONIC 表示硬體的運作速率與系統的單聲道時鐘相同。

  • CLOCK_DOMAIN_EXTERNAL 表示硬體以不明速率運作,且不會與任何已知時鐘 (甚至是 CLOCK_DOMAIN_EXTERNAL 網域中的其他時鐘) 同步。

如果網域並非 CLOCK_DOMAIN_MONOTONIC,用戶端必須使用位置通知更新內容來復原硬體時鐘。

必填。

DaiProperties

定義於 fuchsia.hardware.audio/dai.fidl

序數廣闊類型說明
is_input bool

驅動程式類型為 input (true) 或輸出 (false)

必填。

manufacturer string[256]

製造商名稱的 UI 字串。如未指定,則未指定製造商。

選用。

product_name string[256]

產品名稱的 UI 字串。如未加入,則表示未指定產品名稱。

選用。

unique_id uint8[16]

驅動程式庫的專屬 ID。如未提供,就不會有驅動程式庫的專屬 ID。

選用。

新增日期:20 位
clock_domain ClockDomain

這個硬體在時鐘網域的 ID。如果兩部硬體裝置的時鐘網域相同,兩者的時鐘速率相同且無縫同步。雖然這兩個時鐘的速率相同,但時鐘位置可能會以任意 (但固定) 量偏移。Clock_domain 通常來自於系統通用的實體,例如平台匯流排或全域時鐘樹狀結構。

有兩個特殊值:

  • CLOCK_DOMAIN_MONOTONIC 表示硬體的運作速率與系統的單聲道時鐘相同。

  • CLOCK_DOMAIN_EXTERNAL 表示硬體以不明速率運作,且不會與任何已知時鐘 (甚至是 CLOCK_DOMAIN_EXTERNAL 網域中的其他時鐘) 同步。

如果網域並非 CLOCK_DOMAIN_MONOTONIC,用戶端必須使用位置通知更新內容來復原硬體時鐘。

必填。

新增日期:20 位

DelayInfo

定義於 fuchsia.hardware.audio/ring_buffer.fidl

驅動程式庫傳回的延遲資訊。

已新增:HEAD

序數廣闊類型說明
internal_delay zx/Duration

驅動程式內部抽象化延遲時間內的驅動程式最佳預估 (以所選格式)。

「內部」是指硬體互連網路 (DAI) 和環形緩衝區 (例如 SoC 音訊子系統) 之間的硬體,「外部」則是指任何硬體互連網路 (DAI) 最遠端的硬體 (例如硬體轉碼器)。

針對播放期間的特定影格,是指驅動程式庫/HW 從環形緩衝區複製該影格後的任何延遲,然後才會離開任何硬體互連網路。就錄製期間的特定影格而言,是指進入硬體互連後,由驅動程式庫/HW 複製到環形緩衝區之前的任何延遲。

用戶端決定最短前置時間 (播放期間) 和最短擷取延遲時間 (在拍攝期間) 時,必須將 internal_delay 納入考量。

此延遲時間不得包含透過暫時緩衝的方式,將資料複製到及移出環形緩衝區 (包含在 RingBufferProperties 欄位 driver_transfer_bytes 中) 時所產生的先進延遲。

必填。

external_delay zx/Duration

從硬體抽象化以外的延遲時間 (針對所選格式) 的驅動程式最佳預估結果。

「外部」是指任何硬體互連網路 (DAI) 最遠端的硬體 (例如硬體轉碼器),「內部」則是指硬體互連網路 (DAI) 和環形緩衝區 (例如 SoC 音訊子系統) 之間的硬體。

用戶端決定最短前置時間 (播放期間) 和最短擷取延遲時間 (在拍攝期間) 時,必須將 external_delay 納入考量。

如果未納入,則 external_delay 不知道。如果不明,用戶端可能會以自己選擇的方式處理 (認定為零或某個較大的數字,並自動偵測等)。

internal_delay 一樣,此延遲時間不得包括透過暫時緩衝的方式,將資料複製到及傳出環形緩衝區 (包含在 RingBufferProperties 欄位 driver_transfer_bytes 中) 所新增的先進延遲。

選用。

格式

定義於 fuchsia.hardware.audio/ring_buffer_format.fidl

序數廣闊類型說明
pcm_format PcmFormat

支援非壓縮 PCM 範例的格式。

必填。

GainState

定義於 fuchsia.hardware.audio/stream_config.fidl

取得用戶端要求或驅動程式庫傳回的狀態。

序數廣闊類型說明
muted bool

目前靜音狀態。如果未加入,系統就會取消靜音狀態。

選用。

agc_enabled bool

目前的自動增益控制 (AGC) 狀態。如果未納入,AGC 就會停用。

選用。

gain_db float32

目前增加的分貝值。

必填。

HealthState

定義於 fuchsia.hardware.audio/health.fidl

序數廣闊類型說明
healthy bool

駕駛目前健康狀態良好。如未加入這個欄位,系統不會提供健康資訊。如此一來,當功能或資源本身功能或資源不足以自行復原時 (例如無法透過 GPIO 將硬體關機或控制電源子系統),駕駛人就得通知自身健康狀態。

選用。

PcmSupportedFormats

fuchsia.hardware.audio/ring_buffer_format.fidl 定義

此格式支援非壓縮 PCM 音訊。每個影格都是由一或多個 (number_of_channels) 連續儲存的樣本組成。在分配給每個樣本的 bytes_per_sample 中,valid_bits_per_sample 位元的資料會儲存在最重要的 (左方) 部分。每個向量列出的所有值都受到支援。當驅動程式庫支援的所有組合都無法以一個 SupportedFormatsPcmSupportedFormats 描述時,GetSupportedFormats 會在傳回的向量中傳回多個 SupportedFormats。詳情請參閱音訊驅動程式串流介面

序數廣闊類型說明
channel_sets vector<ChannelSet>[64]

可能支援 ChannelSets 的向量。ChannelSet 會指定管道設定 (包括管道計數),以及多個選用屬性。每個不重複管道數量只能有一個 ChannelSet。因此,channel_sets 中的兩個項目不得包含長度相同的 attributes 向量。

必填。

sample_formats vector<SampleFormat>[3]

支援可能 SampleFormat 的向量。

必填。

bytes_per_sample vector<uint8>[8]

為每個樣本分配的可能位元組數向量。值必須以遞增順序列出。valid_bits_per_sample 中列出的所有值至少必須為最大的 bytes_per_sample 值。

必填。

valid_bits_per_sample vector<uint8>[8]

bytes_per_sample 定義的範例容器中,包含有效資料的可能位元數向量。值必須以遞增方式列出。列出的所有值都必須符合最大的 bytes_per_sample 值。有效的資料位元必須是範例容器中的最重要 (由左右側),並忽略任何其他位元。

必填。

frame_rates vector<uint32>[64]

支援可能影格速率的向量。值必須以遞增方式列出。

必填。

PlugState

定義於 fuchsia.hardware.audio/plug.fidl

接上驅動程式庫傳回的狀態。如果驅動程式庫回報為 HARDWIRED 的 plug_detect_capabilities,則驅動程式庫只會在第一次呼叫時回應 WatchPlugState,並將 plugged 設為 true,plug_state_time 則設為時間「0」。

序數廣闊類型說明
plugged bool

驅動程式目前已接上電源。必要

plug_state_time zx/Time

時間戳記,顯示這個結構中其餘欄位提供的資訊。必填。

RingBufferProperties

定義於 fuchsia.hardware.audio/ring_buffer.fidl

環形緩衝區的屬性。建立環形緩衝區後,這些值不會變更。

序數廣闊類型說明
needs_cache_flush_or_invalidate bool

如果設為 true,表示環形緩衝區是在不同的快取一致性網域中執行,因此用戶端必須確保寫入的資料已完全清除至主記憶體 (播放期間);或者,環環緩衝區的檢視畫面必須在擷取期間失效。這是因為 CPU 外部的硬體可能會讀取/寫入主要記憶體,略過 CPU。

設為 false 時,表示環形緩衝區在與 CPU 相同的快取一致性網域中執行,因此驅動程式庫不需要清除/撤銷環形緩衝區。請注意,在此情況下,驅動程式庫和用戶端仍必須同步處理其資料存取權,例如,在寫入後讀取和釋出圍欄前,請插入適當的獲取圍欄。

必填。

turn_on_delay zx/Duration

SetActiveChannels 啟用管道後,驅動程式的最佳預估硬體會發出 (播放期間) 或接受 (拍攝期間) 影格所需的時間。驅動程式預估在 SetActiveChannels(channel)->(set_time) 啟用管道後,資料會在約 set_time + turn_on_delay 繼續流通。硬體可能需要時間才能完全運作 (例如因電源狀態變更,或藍牙驅動程式庫多個硬體實體之間的通訊延遲)。如果用戶端無法接受捨棄實際音訊影格,而是在這個時間間隔內播放/擷取無聲片段,用戶端必須將這類延遲納入考量。如果未納入,則 turn_on_delay 不知道。

選用。

driver_transfer_bytes uint32

驅動程式庫/HW 使用或產生環形緩衝區內容時的暫存緩衝區大小 (以位元組為單位)。

環形緩衝區內容必須以 CreateRingBuffer 指令指定的速率產生和消耗,使用暫存緩衝區和環形緩衝區之間的資料移轉。以播放來說,在傳輸過程中,驅動程式庫會用最大尺寸 driver_transfer_bytes 使用音訊影格。以擷取來說,在傳輸作業中產生的音訊影格大小為 driver_transfer_bytes。在這兩種情況下,大量影格必須先累積,然後才能讀取或提交環形緩衝區。

資料移轉是指環形緩衝區中一直存在一個部分不適合用戶端的寫入/讀取。這個不安全的緩衝區區域是由目前位置「P」的一側,另一側則是「安全指標」的位置「S」。環形緩衝區啟動後,這兩個指標就會開始移動。「P」會從 Start 的位置從 start_time 的位置從 0 開始移動。這些指標之間的區域不得由用戶端讀取或寫入。下圖顯示這些指標為「P」和「S」。

播放期間,用戶端必須在硬體轉移「之前」寫入資料。在擷取期間,用戶端只能在硬體轉移「之後」讀取擷取的資料。因此,在播放期間「S」會一直早於「P」,但在擷取期間「S」則一律落後「P」。

播放

在啟動環形緩衝區之前,用戶端可以安全地寫入任何環形緩衝區位置。建議至少寫入 driver_transfer_bytes 初始音訊,因為這類音訊一律至少保持在驅動程式庫/硬體讀取位置的遠處,而在 Start 時,硬體可能會立即耗用環形緩衝區中的大量資料。否則,用戶端會依賴 VMO 的零轉內容,做為驅動程式庫/HW 讀取的初始音訊。

                                      Ring Buffer
 +-------------------------+-------------------------------------------------------------+
 |<---                                 safe to write                                 --->|
 |             (to pre-populate the ring buffer before starting the hardware)            |
 +-------------------------+-------------------------------------------------------------+
 0=P                       S                                                             0

啟動環形緩衝區後,用戶端就無法在「P」和「S」之間的環形緩衝區寫入資料,因為這代表資料已在使用中 (可能已使用)。用戶端可以安全地寫入環形緩衝區的其餘部分 (介於「S」和「0/P」之間)。

                                      Ring Buffer
 +-------------------------+-------------------------------------------------------------+
 |<--- unsafe to write --->|<---                    safe to write                    --->|
 |< driver_transfer_bytes >|           (empty unless prewritten by the client)           |
 +-------------------------+-------------------------------------------------------------+
 0=P                       S                                                             0

隨著時間的推移,驅動程式庫/HW 會依照 CreateRingBuffer 中指定的速率,以 driver_transfer_bytes 為單位的區塊讀取資料。「位置」/「安全」指標會以相同速率往右移動,但移動時應該相當流暢。因此,「用戶端寫入作業不安全」區域會逐漸在環形緩衝區內移動,而固定大小仍等於 driver_transfer_bytes。因此,一段時間後,我們現在會:

                                      Ring Buffer
 +------------+-------------------------+------------------------------------------------+
 |<-- safe -->|<--- unsafe to write --->|<--               safe to write              -->|
 |  to write  |< driver_transfer_bytes >|       (not yet consumed by the hardware)       |
 +------------+-------------------------+------------------------------------------------+
 0            P                         S                                                0

稍後,「S」會圍繞環形緩衝區,直到「P」為止。請注意,從 0 到「S」的區域加上「P」到環形緩衝區結尾的區域,加總後等於 driver_transfer_bytes

                                      Ring Buffer
 +---------------+------------------------------------------------------------+----------+
 |<--- unsafe -->|<---                   safe to write                    --->|<-unsafe->|
 |< driver_transf|                                                            |er_bytes >|
 +---------------+------------------------------------------------------------+----------+
 0               S                                                            P          0

在穩定狀態下,指標「P」和「S」外的任何區域可以安全寫入:

                                      Ring Buffer
 +--------------------------------+-------------------------+----------------------------+
 [<--       safe to write      -->|<--- unsafe to write --->|<--     safe to write    -->|
 |  (prior data already consumed) |< driver_transfer_bytes >|                            |
 +--------------------------------+-------------------------+----------------------------+
 0                                P                         S                            0

錄製中

在記錄過程中,只有用戶端讀取環形緩衝區該部分不會同時由驅動程式庫/HW 寫入。在擷取開始之前,可能會讀取整個環形緩衝區,但驅動程式庫尚未寫入任何內容可供用戶端讀取。這是用戶端啟動環形緩衝區當下的環形緩衝區:

                                      Ring Buffer
 +---------------------------------------------------------------------------------------+
 [<---                     empty (not yet written by the hardware)                    -->|
 +---------------------------------------------------------------------------------------+
0=S=P                                                                                    0

擷取開始後,驅動程式庫/HW 會取得影格,最終會使第一筆資料轉移至環形緩衝區,從「0」開始。這些轉乘大小不明,但可能很大;driver_transfer_bytes會以 CreateRingBuffer 中指定的速率進行。在驅動程式庫/HW 將至少 driver_transfer_bytes 寫入環形緩衝區之前,用戶端無法安全地讀取任何新擷取的影格:

                                      Ring Buffer
 +--------------+------------------------------------------------------------------------+
 [<-- unsafe -->|<--                           safe to read                           -->|
 |< driver_transfer_bytes >|     (but empty, not yet written by the hardware)            |
 +--------------+------------------------------------------------------------------------+
0=S             P                                                                        0

在驅動程式庫/HW 將至少 driver_transfer_bytes 的資料寫入環形緩衝區後,「S」會開始以與「P」相同的速率流暢前進 (取決於環形緩衝區的速率和取樣格式)。用戶端可以安全地讀取區域內的「0」與「S」之間的影格。用戶端在「S」和「P」之間讀取資料並不安全,因為驅動程式庫/HW 同時寫入此處。這個區域會在環形緩衝區中逐漸增加,保持固定的 driver_transfer_bytes 大小。一段時間後,我們會:

                                      Ring Buffer
 +----------------+-------------------------+--------------------------------------------+
 [< safe to read >|<---  unsafe to read --->|<--             safe to read             -->|
 | captured audio |< driver_transfer_bytes >|      (not yet written by the hardware)     |
 +----------------+-------------------------+--------------------------------------------+
 0                S                         P                                            0

稍後,「P」會圍繞環形緩衝區,直到「S」為止。請注意,從 0 到「P」的區域加上「S」到環形緩衝區結尾的區域,加總起來就是 driver_transfer_bytes

                                      Ring Buffer
 +-----------+------------------------------------------------------------+--------------+
 |<--unsafe->|<---                    safe to read                    --->|<---unsafe--->|
 |< driver_tr|                      (captured audio)                      |ansfer_bytes >|
 +-----------+------------------------------------------------------------+--------------+
 0           P                                                            S              0

穩定狀態是指當程序包裝在環形緩衝區後,指標「S」和「P」以外的任何區域都能安全讀取:

                                      Ring Buffer
 +--------------------------------+-------------------------+----------------------------+
 [<--       safe to read       -->|<---      unsafe     --->|<--     safe to read     -->|
 |                                |< driver_transfer_bytes >|                            |
 +--------------------------------+-------------------------+----------------------------+
 0                                S                         P                            0

硬體與軟體

環形緩衝區資料可能是由硬體直接使用/產生,也就是說 driver_transfer_bytes 可以直接對應至硬體 FIFO 區塊的大小,因為硬體 FIFO 區塊會決定提前讀取或保留的資料數量上限。請注意,如果 FIFO 緩衝區未以傳統的「高水」方式使用 (例如在任何時間只使用一半 FIFO 的「連線偵測 (ping)」設計),即使在 Start 時間首次轉乘期間,driver_transfer_bytes 還是可以設為較小的值,但必須至少等於儲存在 FIFO 緩衝區中儲存的最大資料量。即使傳輸大小從未超過 FIFO 的一半大小,如果使用了 FIFO 的完整大小 (例如在填入初始空白硬體 FIFO 時在 Start 時),則 driver_transfer_bytes 必須設為整個 FIFO 緩衝區的整個大小。

系統可能會改用音訊驅動程式庫程式軟體使用/產生環形緩衝區資料。從概念來說,這類軟體位於環形緩衝區和音訊硬體。在這種情況下,針對播放作業,driver_transfer_bytes 超前讀取的資料量必須夠大,讓驅動程式庫不會因根據 CreateRingBuffer 比率和 Startstart_time 產生資料而未偵測到未偵測到的電量不足。為了擷取,driver_transfer_bytes 必須夠大,讓驅動程式庫在產生 CreateRingBufferStart 指令所決定的資料時不會發生負荷。

driver_transfer_bytes 不得包括由驅動程式庫抽象化的硬體或軟體處理程序造成的延遲影響。這些延遲會透過 DelayInfo 中的 internal_delayexternal_delay 欄位傳達,與這個值無關。

必填。

已新增:HEAD

StreamProperties

定義於 fuchsia.hardware.audio/stream_config.fidl

序數廣闊類型說明
unique_id uint8[16]

專屬 ID。如果未納入,StreamConfig 就不會沒有專屬 ID。開頭為 0x42、0x54 ... (或 ASCII 中的 BT) 的 unique_id 陣列,已提供給實作藍牙技術的驅動程式。開頭為 0x55、0x53、0x42... (或 ASCII 中的 USB) 的 unique_id 陣列會保留給實作 USB 技術的驅動程式。請注意,即使上述值對應到可讀取的 ASCII 字元,陣列值仍可橫跨整個 uint8 範圍 (0-255)。

選用。

is_input bool

驅動程式類型為 input (true) 或輸出 (false)

必填。

can_mute bool

取得靜音能力。如果未納入,StreamConfig 就無法設為靜音。

選用。

can_agc bool

自動增益控制 (AGC) 能力。如果未納入,StreamConfig 無法執行 AGC。

選用。

min_gain_db float32

以分貝為單位的最低增益。

必填。

max_gain_db float32

增減幅度 (分貝)。

必填。

gain_step_db float32

以分貝為單位增加步驟,這個值不得為負數,但這個值可以是零,表示可有效傳送值範圍的連續值。不得超過 max_gain_dbmin_gain_db 個字元。

必填。

plug_detect_capabilities PlugDetectCapabilities

插頭偵測功能。

必填。

manufacturer string[256]

製造商名稱的 UI 字串。如未指定,則未指定製造商。

選用。

product string[256]

產品名稱的 UI 字串。如未加入,則表示未指定產品名稱。

選用。

clock_domain ClockDomain

這個硬體在時鐘網域的 ID。如果兩部硬體裝置的時鐘網域相同,兩者的時鐘速率相同且無縫同步。雖然這兩個時鐘的速率相同,但時鐘位置可能會以任意 (但固定) 量偏移。Clock_domain 通常來自於系統通用的實體,例如平台匯流排或全域時鐘樹狀結構。

有兩個特殊值:

  • CLOCK_DOMAIN_MONOTONIC 表示硬體的運作速率與系統的單聲道時鐘相同。

  • CLOCK_DOMAIN_EXTERNAL 表示硬體以不明速率運作,且不會與任何已知時鐘 (甚至是 CLOCK_DOMAIN_EXTERNAL 網域中的其他時鐘) 同步。

如果網域並非 CLOCK_DOMAIN_MONOTONIC,用戶端必須使用位置通知更新內容來復原硬體時鐘。

必填。

SupportedFormats

fuchsia.hardware.audio/ring_buffer_format.fidl 定義

此裝置支援的所有可能格式。

序數廣闊類型說明
pcm_supported_formats PcmSupportedFormats

非壓縮 PCM 範例支援的格式,以及屬性。

必填。

聯合國

Codec_GetDaiFormats_Result 嚴格

fuchsia.hardware.audio/codec.fidl 定義

序數Variant類型說明
response Codec_GetDaiFormats_Response
err zx/Status

Codec_SetDaiFormat_Result 嚴格

fuchsia.hardware.audio/codec.fidl 定義

序數Variant類型說明
response Codec_SetDaiFormat_Response
err zx/Status

Composite_CreateRingBuffer_Result 嚴格

定義於 fuchsia.hardware.audio/Composite.fidl

序數Variant類型說明
response Composite_CreateRingBuffer_Response
err DriverError

Composite_GetDaiFormats_Result 嚴格

定義於 fuchsia.hardware.audio/Composite.fidl

序數Variant類型說明
response Composite_GetDaiFormats_Response
err DriverError

Composite_GetRingBufferFormats_Result 嚴格

定義於 fuchsia.hardware.audio/Composite.fidl

序數Variant類型說明
response Composite_GetRingBufferFormats_Response
err DriverError

Composite_Reset_Result 嚴格

定義於 fuchsia.hardware.audio/Composite.fidl

序數Variant類型說明
response Composite_Reset_Response
err DriverError

Composite_SetDaiFormat_Result 嚴格

定義於 fuchsia.hardware.audio/Composite.fidl

序數Variant類型說明
response Composite_SetDaiFormat_Response
err DriverError

DaiFrameFormat 嚴格

fuchsia.hardware.audio/dai_format.fidl

標準或自訂頁框格式。

序數Variant類型說明
frame_format_standard DaiFrameFormatStandard

DAI 所有範例的格式類型,如 DaiFrameFormatStandard 中所列。

frame_format_custom DaiFrameFormatCustom

DAI 中所有範例的格式類型,如 DaiFrameFormatCustom 所指定。

Dai_GetDaiFormats_Result 嚴格

定義於 fuchsia.hardware.audio/dai.fidl

序數Variant類型說明
response Dai_GetDaiFormats_Response
err zx/Status

Dai_GetRingBufferFormats_Result 嚴格

定義於 fuchsia.hardware.audio/dai.fidl

序數Variant類型說明
response Dai_GetRingBufferFormats_Response
err zx/Status

RingBuffer_GetVmo_Result 嚴格 資源

定義於 fuchsia.hardware.audio/ring_buffer.fidl

序數Variant類型說明
response RingBuffer_GetVmo_Response
err GetVmoError

RingBuffer_SetActiveChannels_Result 嚴格

定義於 fuchsia.hardware.audio/ring_buffer.fidl

序數Variant類型說明
response RingBuffer_SetActiveChannels_Response
err zx/Status

業者

名稱物超所值類型說明
CLOCK_DOMAIN_EXTERNAL 4294967295 uint32
CLOCK_DOMAIN_MONOTONIC 0 uint32
MAX_COUNT_CHANNELS_IN_RING_BUFFER 64 uint32
MAX_COUNT_CHANNEL_SETS 64 uint32
MAX_COUNT_DAI_FORMATS MAX_COUNT_FORMATS uint32
MAX_COUNT_DAI_SUPPORTED_BITS_PER_SAMPLE 8 uint32
MAX_COUNT_DAI_SUPPORTED_BITS_PER_SLOT 8 uint32
MAX_COUNT_DAI_SUPPORTED_FRAME_FORMATS 64 uint32
MAX_COUNT_DAI_SUPPORTED_NUMBER_OF_CHANNELS 64 uint32
MAX_COUNT_DAI_SUPPORTED_RATES 64 uint32
MAX_COUNT_DAI_SUPPORTED_SAMPLE_FORMATS 4 uint32
MAX_COUNT_FORMATS 64 uint32
MAX_COUNT_SUPPORTED_BYTES_PER_SAMPLE 8 uint32
MAX_COUNT_SUPPORTED_NUMBER_OF_CHANNELS 64 uint32
MAX_COUNT_SUPPORTED_RATES 64 uint32
MAX_COUNT_SUPPORTED_SAMPLE_FORMATS 3 uint32
MAX_COUNT_SUPPORTED_VALID_BITS_PER_SAMPLE 8 uint32
MAX_DAI_UI_STRING_SIZE 256 uint32
MAX_UI_STRING_SIZE 256 uint32
UNIQUE_ID_SIZE 16 uint32

別名

名稱物超所值說明
ClockDomain uint32

服務

CodecConnectorService

定義於 fuchsia.hardware.audio/codec_connector.fidl

名稱類型傳輸
codec_connector fuchsia.hardware.audio/CodecConnector 版本

CodecService

fuchsia.hardware.audio/codec.fidl 定義

名稱類型傳輸
轉碼器 fuchsia.hardware.audio/Codec 版本

CompositeConnectorService

定義於 fuchsia.hardware.audio/Composite_connector.fidl

名稱類型傳輸
composite_connector fuchsia.hardware.audio/CompositeConnector 版本

DaiConnectorService

定義於 fuchsia.hardware.audio/dai_connector.fidl

名稱類型傳輸
dai_connector fuchsia.hardware.audio/DaiConnector 版本

DaiService

定義於 fuchsia.hardware.audio/dai.fidl

名稱類型傳輸
dai fuchsia.hardware.audio/Dai 版本

DeviceService

定義於 fuchsia.hardware.audio/Composite.fidl

名稱類型傳輸
device fuchsia.hardware.audio/Composite 版本

StreamConfigConnectorService

定義於 fuchsia.hardware.audio/stream_config_connector.fidl

名稱類型傳輸
stream_config_connector fuchsia.hardware.audio/StreamConfigConnector 版本

StreamConfigService

定義於 fuchsia.hardware.audio/stream_config.fidl

名稱類型傳輸
stream_config fuchsia.hardware.audio/StreamConfig 版本