PALLOCATE_RENDER_DMA_ENGINE回呼函式（hdaudio.h）

發行項
02/07/2025

AllocateRenderDmaEngine 例程會為轉譯數據流配置 DMA 引擎。

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

語法

PALLOCATE_RENDER_DMA_ENGINE PallocateRenderDmaEngine;

NTSTATUS PallocateRenderDmaEngine(
  [in]  PVOID _context,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [in]  BOOLEAN Stripe,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

參數

[in] _context

從 HDAUDIO_BUS_INTERFACE、HDAUDIO_BUS_INTERFACE_V2或 HDAUDIO_BUS_INTERFACE_BDL 結構的成員，指定 Context 成員的內容值。

[in] StreamFormat

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

[in] Stripe

指定是否啟用等量分割。如果 TRUE，則例程會啟用 DMA 傳輸中的等量分割。如果 FALSE，則會停用等量分割。

[out] Handle

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

[out] ConverterFormat

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

傳回值

如果呼叫成功保留 DMA 引擎，AllocateRenderDmaEngine 會傳回STATUS_SUCCESS。否則，例程會傳回適當的錯誤碼。下表顯示一些可能的傳回錯誤碼。

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

言論

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

AllocateRenderDmaEngine 例程會保留硬體資源（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 參數會指定擷取數據流的數據格式。在呼叫 AllocateRenderDmaEngine之後，您可以呼叫 changeBandwidthAllocation 來變更數據流的格式。

等量參數會指定 DMA 引擎是否要使用等量分割來加速數據傳輸。如需詳細資訊，請參閱等量。

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

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

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

WDM 音訊驅動程式會在釘選建立時間呼叫 AllocateRenderDmaEngine 執行其 NewStream 方法（例如，請參閱 IMiniportWavePci：：NewStream）。