PALLOCATE_CONTIGUOUS_DMA_BUFFER回呼函式（hdaudio.h）

發行項
02/07/2025

AllocateContiguousDmaBuffer 例程會配置由單一連續實體記憶體區塊組成的 DMA 緩衝區。

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

語法

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

參數

[in] _context

指定來自 HDAUDIO_BUS_INTERFACE_BDL 結構之 Context 成員的內容值。

[in] Handle

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

RequestedBufferSize

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

[out] DataBuffer

擷取數據緩衝區。此參數指向呼叫端配置的 PVOID 變數，例程會將數據緩衝區的系統虛擬位址寫入其中。

[out] BdlBuffer

擷取緩衝區描述元清單（BDL）。此參數指向呼叫端配置的 PVOID 變數，例程會將 BDL 的系統虛擬位址寫入其中。 BDL 配置大小正好是一個記憶體頁面，而 BDL 會從頁面界限開始。

傳回值

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

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

言論

AllocateContiguousDmaBuffer 例程會與 SetupDmaEngineWithBdl 和 FreeContiguousDmaBuffer 例程搭配使用。這三個例程僅適用於 HD 音訊 DDI HDAUDIO_BUS_INTERFACE_BDL 版本。此 DDI 不包含 AllocateDmaBuffer 和 FreeDmaBuffer 例程，這些例程永遠不會與 AllocateContiguousDmaBuffer搭配使用、SetupDmaEngineWithBdl和 FreeContiguousDmaBuffer。不同於 SetupDmaEngineWithBdl，它會將 DMA 引擎設定為使用先前配置的 DMA 緩衝區，AllocateDmaBuffer 兩者都會配置 DMA 緩衝區，並將 DMA 引擎設定為使用緩衝區。如需詳細資訊，請參閱兩個 DDI 版本之間的差異。

AllocateContiguousDmaBuffer 為指定的 DMA 引擎配置數據緩衝區。它也會為 BDL 配置記憶體分頁。根據主機處理器架構，一般頁面大小可能是 4,096 或 8,192 個字節。數據緩衝區是由物理記憶體的單一連續區塊所組成。

handle 參數會指定要使用數據緩衝區和 BDL 的 DMA 引擎。例程會配置符合 DMA 引擎大小、對齊和位置需求的記憶體。

例程配置給數據緩衝區和 BDL 的記憶體未初始化。函式驅動程式負責填入 BDL，再將其提交至 SetupDmaEngineWithBdl 例程。函式驅動程式也負責程式設計編解碼器來管理數據傳輸，以及辨識數據流標識符。

若要以精確的間隔產生IOC中斷，函式驅動程式可能需要將數據緩衝區配置分割成特定大小的數個片段。每個片段都會由 BDL 專案描述。片段大小可以調整以調整中斷速率。根據 Intel 高階音訊規格（請參閱 Intel HD 音訊網站），每個片段必須以 128 位元組的界限開始，不過沒有這種對齊需求適用於片段的長度。因此，一個片段結尾與下一個片段的開頭之間可能會有一個間距。呼叫 SetupDmaEngineWithBdl時，函式驅動程序必須指定 bufferSize 參數的值，這個參數代表 BDL 專案描述的個別片段大小總和。這個大小將小於或等於 AllocateContiguousDmaBuffer 例程的 requestedBufferSize 參數中指定的位元元組數目。

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

在呼叫 AllocateContiguousDmaBuffer、SetupDmaEngineWithBdl和 FreeContiguousDmaBuffer時，DMA 引擎必須處於重設數據流狀態。 DMA 引擎在呼叫 AllocateXxxDmaEngine 之後，立即處於重設狀態。若要將 DMA 引擎變更為執行狀態，請呼叫 SetDmaEngineState。

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