PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION回呼函式 (hdaudio.h)

發行項
02/26/2024

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

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

語法

PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION PallocateDmaBufferWithNotification;

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

參數

[in] _context

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

[in] Handle

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

[in] NotificationCount

根據音訊緩衝區的 DMA 進展，指定所需的通知數目。目前支援 1 或 2 的值。當值為 1 時，每次迴圈音訊緩衝區完成且 DMA 回傳回開頭時，都會發出任何已註冊的通知事件訊號。當值為 2 時，任何已註冊的通知事件都會收到通知，因為 DMA 會傳遞音訊緩衝區的中間點，以及在結尾 (或包裝點) 。

[in] RequestedBufferSize

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

[out] BufferMdl

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

[out] AllocatedBufferSize

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

OffsetFromFirstPage

[out] StreamId

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

[out] FifoSize

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

傳回值

AllocateDmaBufferWithNotification如果呼叫成功，例程會傳回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 引擎配置緩衝區且尚未釋放。

備註

例 AllocateDmaBufferWithNotification 程會與 FreeDmaBufferWithNotification 例程搭配使用。這兩個例程僅適用於 HD 音訊 DDI 的 HDAUDIO_BUS_INTERFACE_V2 版本。不同於 SetupDmaEngineWithBdl，它會將 DMA 引擎設定為使用先前配置的 DMA 緩衝區、 AllocateDmaBufferWithNotification 配置 DMA 緩衝區，也會設定 DMA 引擎以使用緩衝區。

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

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

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

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

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

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

在 Windows Vista 和更新版本的 Windows 中，WaveRT 迷你埠驅動程式會在收到 KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION 屬性要求時呼叫此例程。

規格需求

需求	值
最低支援的用戶端	可在 Windows Vista 和更新版本的 Windows 中使用。
目標平台	桌面
標頭	hdaudio.h (包含 Hdaudio.h)
IRQL	PASSIVE_LEVEL。