PALLOCATE_CONTIGUOUS_DMA_BUFFER回呼函式 (hdaudio.h)

發行項
02/26/2024

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

傳回碼	Description
STATUS_UNSUCCESSFUL	表示呼叫端正在中斷要求層級執行， (IRQL) 太高。
STATUS_INSUFFICIENT_RESOURCES	表示緩衝區配置失敗。
STATUS_INVALID_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 例程，這些例程永遠不會與、SetupDmaEngineWithBdl 和 FreeContiguousDmaBuffer 搭配AllocateContiguousDmaBuffer使用。不同於 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 專案所描述之個別片段的大小總和。這個大小會小於或等於例程的 requestedBufferSize 參數中指定的AllocateContiguousDmaBuffer位元元組數目。

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

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

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