PALLOCATE_DMA_BUFFER hdaudio.h) (回呼函式

發行項
02/26/2024

例 AllocateDmaBuffer 程會在 DMA 引擎的系統記憶體中配置數據緩衝區。

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

語法

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

NTSTATUS PallocateDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

參數

[in] _context

指定HDAUDIO_BUS_INTERFACE和HDAUDIO_BUS_INTERFACE_V2結構之Context成員的內容值。

[in] Handle

處理識別 DMA 引擎。這個句柄值是從先前呼叫 AllocateCaptureDmaEngine 或 AllocateRenderDmaEngine 取得。

[in] RequestedBufferSize

指定要求的緩衝區大小，以位元組為單位。

[out] BufferMdl

擷取包含已配置緩衝區的實體記憶體頁面。此參數指向呼叫端配置的 PMDL 變數，此變數會將指標寫入記憶體描述元清單， (描述緩衝區的 MDL) 。

[out] AllocatedBufferSize

以位元組為單位擷取配置的緩衝區大小。此參數指向呼叫端配置的SIZE_T變數，而例程會將配置緩衝區的大小寫入其中。

[out] StreamId

擷取數據流標識碼。此參數指向呼叫端配置的UCHAR變數，而例程會將它指派給數據流的數據流標識碼寫入其中。

[out] FifoSize

以位元組為單位擷取 DMA 引擎的 FIFO 大小。此參數指向呼叫端配置的ULONG變數，而例程會將FIFO大小寫入其中。

傳回值

AllocateDmaBuffer 如果呼叫成功，則會傳回STATUS_SUCCESS。否則，例程會傳回適當的錯誤碼。下表顯示一些可能的傳回狀態代碼。

傳回碼	Description
STATUS_UNSUCCESSFUL	表示呼叫端在太高 IRQL 上執行。
STATUS_INSUFFICIENT_RESOURCES	表示緩衝區配置失敗。
STATUS_INVALID_HANDLE	表示 handle 參數值無效。
STATUS_INVALID_PARAMETER	表示其中一個參數值不正確， (不正確的指標) 。
STATUS_DEVICE_NOT_READY	表示硬體程式設計逾時。如果發生這種情況，硬體可能處於遭入侵狀態。
STATUS_INVALID_DEVICE_REQUEST	表示數據流未處於重設狀態，或已為 DMA 引擎配置緩衝區。

備註

例 AllocateDmaBuffer 程會與 FreeDmaBuffer 例程搭配使用。這兩個例程僅適用於HDAUDIO_BUS_INTERFACE和 HD 音訊 DDI 的HDAUDIO_BUS_INTERFACE_V2版本。此 DDI 不包含 AllocateContiguousDmaBuffer、 SetupDmaEngineWithBdl 和 FreeContiguousDmaBuffer 例程，這些例程永遠不會與 AllocateDmaBuffer和 FreeDmaBuffer 搭配使用。不同於 SetupDmaEngineWithBdl，它會將 DMA 引擎設定為使用先前配置的 DMA 緩衝區， AllocateDmaBuffer 兩者都會配置 DMA 緩衝區，並將 DMA 引擎設定為使用緩衝區。

如果 DMA 引擎無法使用 requestedBufferSize 參數中所要求大小的緩衝區，則例程會配置盡可能接近所要求大小的緩衝區。

音訊或數據機編解碼器的函式驅動程式負責程式設計編解碼器來管理資料傳輸，以及辨識數據流識別碼。

例程會輸出 MDL，列出包含緩衝區的實體記憶體頁面。緩衝區基位址會與清單中的第一個實體頁面開頭一致。

在 DMA 引擎句柄的存留期內， AllocateDmaBuffer 可以連續呼叫以配置新的 DMA 緩衝區。不過，在呼叫 AllocateDmaBuffer之前，必須先呼叫 FreeDmaBuffer釋放任何先前配置的 DMA 緩衝區。

在呼叫 AllocateDmaBuffer 和 FreeDmaBuffer期間，DMA引擎必須處於重設數據流狀態。 DMA 引擎在呼叫 AllocateXxxDmaEngine 之後立即處於重設狀態。若要將 DMA 引擎變更為執行狀態，請呼叫 SetDmaEngineState。

FIFO 大小是 DMA 引擎在其內部緩衝區中可以保存的最大位元元組數目。視硬體實作而定，DMA 引擎的 FIFO 大小可以是靜態的，或是隨著數據流格式變更而動態變化。如需 FIFO 大小的詳細資訊，請參閱 Intel HD 音訊網站的 Intel 高定義音訊規格。

此例程失敗，並在下列任一情況下傳回錯誤碼STATUS_INVALID_DEVICE_REQUEST：

任何先前配置的 DMA 緩衝區都尚未透過呼叫 FreeDmaBuffer) 來釋出 (。
數據流處於重設以外的狀態。

在 Windows Server 2003、Windows XP、Windows 2000 和 Windows Me/98 中，WDM 音頻驅動程式會在釘選建立時間) 或 SetFormat 方法 (在 HD Audio DDI) 中呼叫其中一個 AllocateXxxDmaEngine 例程之後，於新的Stream 方法執行期間呼叫此例程 (。如需詳細資訊，請參閱 IMiniportWavePci：：NewStream 和 IMiniportWavePciStream：：SetFormat。