PSETUP_DMA_ENGINE_WITH_BDL回呼函式 (hdaudio.h)

發行項
02/29/2024

SetupDmaEngineWithBdl 例程會設定 DMA 引擎，以使用呼叫端配置的 DMA 緩衝區。

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

語法

PSETUP_DMA_ENGINE_WITH_BDL PsetupDmaEngineWithBdl;

NTSTATUS PsetupDmaEngineWithBdl(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
  [in]  PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

參數

[in] _context

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

[in] Handle

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

[in] BufferLength

緩衝區的長度。

[in] Lvi

指定 LVI) 的最後一個有效索引 (。此參數包含 BDL 中最後一個有效緩衝區描述元的索引。在 DMA 引擎處理此描述項之後，它會換回清單中的第一個描述元，並繼續處理。如果 BDL 包含 n 描述元，則編號為 0 到 n-1。 lvi 值必須至少為 1;換句話說，BDL 至少必須包含兩個有效的專案，DMA 引擎才能開始作業。

[in] Isr

呼叫端ISR的函式指標。如果呼叫端在 BDL 的一或多個緩衝區描述項中設定插斷 (IOC) 位，則 HD 音訊總線驅動程式會在每次在數據流上發生 IOC 中斷時呼叫 ISR。此參數是類型為 HDAUDIO_BDL_ISR 的函式指標，定義於下列一節中。

[in] Context

內容。

[out] StreamId

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

[out] FifoSize

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

傳回值

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

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

備註

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

呼叫端必須呼叫 AllocateContiguousDmaBuffer ，為 DMA 緩衝區和描述緩衝區中物理記憶體分頁的 BDL 配置系統記憶體中的記憶體中的記憶體。 BDL 項目必須位於實際連續的記憶體中。 BDL 和緩衝區內存必須符合 Intel 高畫質音訊規格 中所述的對齊需求， (請參閱 Intel HD 音訊網站) 。

BDL 和其描述的緩衝區內存都必須在 DMA 作業期間保持有效。在呼叫 SetupDmaEngineWithBdl 之後，只要 DMA 引擎繼續使用緩衝區，BDL 和緩衝區內存就必須保持有效。 DMA 引擎會使用緩衝區，直到函式驅動程式再次呼叫 SetupDmaEngineWithBdl 來取代緩衝區，或藉由呼叫 FreeDmaEngine 釋放 DMA 引擎。函式驅動程式負責呼叫 FreeContiguousDmaBuffer ，以便在不再需要緩衝區和 BDL 時釋放緩衝區。

配置緩衝區的記憶體時，呼叫端必須滿足 BDL 所指定之實體連續記憶體區塊位址、長度和對齊方式的所有硬體條件約束。因此，只有對總線控制器和系統硬體有顯著知識的客戶端應該使用 SetupDmaEngineWithBdl 例程。

呼叫 SetupDmaEngineWithBdl 以設定 DMA 引擎之前，客戶端必須呼叫 AllocateCaptureDmaEngine 或 AllocateRenderDmaEngine 來配置 DMA 引擎。 handle 參數是從先前呼叫 Allocate XxxDmaEngine 取得的值。

呼叫端負責程式設計編解碼器來管理數據傳輸，以及辨識數據流標識碼。

WDM 音訊驅動程式會在釘選建立期間呼叫此例程，例如在其 NewStream 方法執行期間 (，請參閱 IMiniportWavePci：：NewStream) 。

在呼叫 SetupDmaEngineWithBdl 之後，DMA 引擎會處於 Reset 狀態。若要啟動 DMA 引擎，請呼叫 SetDmaEngineState。

參數 isr 會指定每次串流發生 IOC 中斷時，HD 音訊總線驅動程式呼叫的 ISR。此參數是類型為 HDAUDIO_BDL_ISR 的函式指標，定義為：

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

HD 音訊總線驅動程式會呼叫 ISR，其內容值與先前 SetupDmaEngineWithBdl 呼叫的內容參數中指定的用戶端相同。 interruptBitMask 參數包含來自 HD 音訊控制器裝置數據流狀態緩存器的位，指出中斷的原因。下表顯示 interruptBitMask 中個別位的意義。

位數位	意義
31:5	未使用的。
4	描述項錯誤 (DESE) 。如果在擷取緩衝區描述元期間發生錯誤，HD 音訊控制器會將 DESE 位設定為 1。
3	FIFO 錯誤 (FIFOE) 。如果 FIFO 錯誤發生 (輸出數據流上的滿溢或輸入數據流) 不足，則 HD 音訊控制器會將 FIFOE 位設定為 1。
2	緩衝區完成中斷狀態 (BCIS) 。如果在緩衝區描述元的命令位元組中將IOC位設定為1，則HD Audio控制器會在處理緩衝區的最後一個樣本之後，將BCIS位設定為1。
1:0	未使用的。