PALLOCATE_RENDER_DMA_ENGINE回呼函式 (hdaudio.h)

發行項
02/26/2024

例 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 結構的內容成員指定內容值。

[in] StreamFormat

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

[in] Stripe

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

[out] Handle

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

[out] ConverterFormat

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

傳回值

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

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

備註

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

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

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

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

stripe 參數會指定 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) 。