PALLOCATE_CAPTURE_DMA_ENGINE回呼函式 (hdaudio.h)

發行項
02/29/2024

例 AllocateCaptureDmaEngine 程會為擷取數據流配置 DMA 引擎。

例程的 AllocateCaptureDmaEngine 函式指標類型定義如下。

語法

PALLOCATE_CAPTURE_DMA_ENGINE PallocateCaptureDmaEngine;

NTSTATUS PallocateCaptureDmaEngine(
  [in]  PVOID _context,
  [in]  UCHAR CodecAddress,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

參數

[in] _context

指定來自HDAUDIO_BUS_INTERFACE、HDAUDIO_BUS_INTERFACE_V2或HDAUDIO_BUS_INTERFACE_BDL結構之Context成員的內容值。

[in] CodecAddress

指定編解碼器位址。此參數會識別 (SDI) 行中的序列數據，而編解碼器會將擷取數據提供給 HD 音訊總線控制器。具有 n SDI 針腳的總線控制器最多可以支援最多 n 個編解碼器，其位址範圍從 0 到 n-1。

[in] StreamFormat

指定要求的數據流格式。這個參數指向指定數據流數據格式之類型HDAUDIO_STREAM_FORMAT 呼叫端配置的結構。

[out] Handle

擷取 DMA 引擎的句柄。這個參數指向呼叫端配置的 HANDLE 變數，而例程會將識別 DMA 引擎的句柄寫入其中。

[out] ConverterFormat

擷取轉換器格式。這個參數指向呼叫端配置的型別結構，HDAUDIO_CONVERTER_FORMAT 例程會將編碼格式寫入其中。

傳回值

AllocateCaptureDmaEngine 如果呼叫成功保留 DMA 引擎，則會傳回STATUS_SUCCESS。否則，可能的傳回值會包含下表中的錯誤碼。

傳回碼	Description
STATUS_BUFFER_TOO_SMALL	表示 DMA 引擎無法設定足夠的內部 FIFO 記憶體，以支援要求的數據流格式。
STATUS_INSUFFICIENT_RESOURCES	表示沒有可用的 DMA 引擎，或要求超過可用的頻寬資源。
STATUS_INVALID_PARAMETER	表示其中一個參數值不正確， (無效的參數值或錯誤的指標) 。

備註

此例程會配置擷取 DMA 引擎，並指定資料流的數據格式。如果成功，例程會輸出呼叫端後續用來識別 DMA 引擎的句柄。

AllocateCaptureDmaEngine例程會 (DMA 引擎) 保留硬體資源，但不會設定 DMA 硬體。呼叫此例程來保留 DMA 引擎之後，函式驅動程式必須將 DMA 緩衝區指派給 DMA 引擎，並將引擎設定為使用緩衝區：

如果使用 HD 音訊 DDI HDAUDIO_BUS_INTERFACE版本，函式驅動程式會呼叫 AllocateDmaBuffer 例程，讓 HD 音訊總線驅動程式配置 DMA 傳輸的數據緩衝區，並設定 DMA 引擎以使用緩衝區。
如果使用 DDI HDAUDIO_BUS_INTERFACE_BDL版本，函數驅動程式會呼叫 AllocateContiguousDmaBuffer 來配置 DMA 緩衝區，並呼叫 SetupDmaEngineWithBdl 例程來設定 DMA 引擎以使用緩衝區。

streamFormat 參數會指定擷取數據流的數據格式。在呼叫 AllocateCaptureDmaEngine之後，您可以呼叫 ChangeBandwidthAllocation 來變更數據流的格式。

透過 handle 參數，例程會輸出呼叫端用來識別配置 DMA 引擎的句柄，後續呼叫 AllocateDmaBuffer、 ChangeBandwidthAllocation、 FreeDmaBuffer、 SetupDmaEngineWithBdl 和 SetDmaEngineState。函式驅動程式會呼叫 FreeDmaEngine釋放句柄。

透過 converterFormat 參數，例程會輸出數據流描述項值，讓呼叫端可用來對輸入轉換器進行程序設計。例程會將 streamFormat 參數中的資訊編碼為 16 位整數。如需詳細資訊，請參閱 HDAUDIO_CONVERTER_FORMAT。

緊接在成功呼叫 AllocateCaptureDmaEngine之後，DMA 引擎會處於重設數據流狀態。呼叫 SetDmaEngineState 將 DMA 引擎變更為執行中、暫停或停止狀態之前，客戶端必須先為引擎配置 DMA 緩衝區。

例如，Windows 驅動程式模型 (WDM) 音訊驅動程式在執行 NewStream 方法 (期間呼叫AllocateCaptureDmaEngine音訊驅動程式，請參閱 IMiniportWavePci：：NewStream) 。