PALLOCATE_CAPTURE_DMA_ENGINE回呼函式（hdaudio.h）

發行項
02/07/2025

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

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

[in] StreamFormat

指定要求的數據流格式。此參數會指向呼叫端配置的型別結構，HDAUDIO_STREAM_FORMAT 指定數據流的數據格式。

[out] Handle

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

[out] ConverterFormat

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

傳回值

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

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

言論

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

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

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

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

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

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

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

Windows 驅動程式模型（WDM）音訊驅動程式在執行其 NewStream 方法期間，於針腳建立時間呼叫 AllocateCaptureDmaEngine （例如，請參閱 IMiniportWavePci：：NewStream）。