PALLOCATE_DMA_BUFFER回呼函式（hdaudio.h）

發行項
02/07/2025

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。否則，例程會傳回適當的錯誤碼。下表顯示一些可能的傳回狀態代碼。

傳回碼	描述
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 音頻驅動程式會在執行其 NewStream 方法（在針腳建立時間）或 SetFormat 方法執行期間呼叫此例程（在 HD Audio DDI 中呼叫其中一個 AllocateXxxDmaEngine 例程）。如需詳細資訊，請參閱 IMiniportWavePci：：NewStream 和 IMiniportWavePciStream：：SetFormat。