PSETUP_DMA_ENGINE_WITH_BDL回调函数（hdaudio.h）

项目
02/07/2025

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 结构的 上下文 成员中的上下文值。

[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）位，则每次流上发生 IOC 中断时，HD 音频总线驱动程序都会调用 ISR。此参数是HDAUDIO_BDL_ISR类型的函数指针，在以下“备注”部分中定义。

[in] Context

上下文。

[out] StreamId

检索流标识符。此参数指向调用方分配的 UCHAR 变量，该变量将例程写入分配给流的流标识符。

[out] FifoSize

检索 DMA 引擎的 FIFO 大小（以字节为单位）。此参数指向调用方分配的 UINT 变量，该变量将例程写入 FIFO 大小。

返回值

如果调用成功，SetupDmaEngineWithBdl 返回STATUS_SUCCESS。否则，例程将返回适当的错误代码。下表显示了一些可能的返回状态代码。

返回代码	描述
STATUS_UNSUCCESSFUL	指示调用方在 IRQL 上运行，该 IRQL 太高。
STATUS_INVALID_HANDLE	指示句柄参数值无效。
STATUS_INVALID_PARAMETER	指示其中一个参数值不正确（指针错误或流格式无效）。
STATUS_DEVICE_NOT_READY	指示硬件编程超时。如果发生这种情况，则硬件可能处于泄露状态。
STATUS_INVALID_DEVICE_REQUEST	指示未分配 DMA 设备或 DMA 缓冲区，或者流未处于重置状态。

言论

SetupDmaEngineWithBdl 例程与 AllocateContiguousDmaBuffer 和 FreeContiguousDmaBuffer 例程结合使用。这三个例程仅在 HD Audio 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 引擎。函数驱动程序负责在不再需要缓冲区和 BDL 时调用 FreeContiguousDmaBuffer。

为缓冲区分配内存时，调用方必须满足 BDL 指定的物理连续内存块的地址、长度和对齐方式的所有硬件约束。因此，只有对总线控制器和系统硬件有显著了解的客户端才应使用 SetupDmaEngineWithBdl 例程。

在调用 SetupDmaEngineWithBdl 以配置 DMA 引擎之前，客户端必须调用 AllocateCaptureDmaEngine 或 AllocateRenderDmaEngine 来分配 DMA 引擎。 handle 参数是从上述调用中获取的值，用于 Allocate XxxDmaEngine。

调用方负责对编解码器进行编程，以管理数据传输和识别流标识符。

WDM 音频驱动程序在 NewStream 方法的执行期间在引脚创建时调用此例程（例如，请参阅 IMiniportWavePci：：NewStream）。

调用 SetupDmaEngineWithBdl后，DMA 引擎处于重置状态。若要启动 DMA 引擎，请调用 SetDmaEngineState。

参数 isr 指定 HD 音频总线驱动程序每次在流上发生 IOC 中断时要调用的 ISR。此参数是HDAUDIO_BDL_ISR类型的函数指针，定义为：

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

HD 音频总线驱动程序使用在上述 SetupDmaEngineWithBdl 调用的上下文参数中指定的客户端使用相同的上下文值调用 ISR。 interruptBitMask 参数包含 HD 音频控制器设备的流状态寄存器中的位，这些位指示中断的原因。下表显示了 interruptBitMask中各个位的含义。

位号	意义
31:5	闲置。
4	描述符错误（DESE）。如果在提取缓冲区描述符期间发生错误，则 HD 音频控制器会将 DESE 位设置为 1。
3	FIFO 错误（FIFOE）。如果发生 FIFO 错误（输出流溢出或输入流的不足），则 HD 音频控制器会将 FIFOE 位设置为 1。
2	缓冲区完成中断状态（BCIS）。如果在缓冲区描述符的命令字节中将 IOC 位设置为 1，则处理缓冲区的最后一个样本后，HD 音频控制器会将 BCIS 位设置为 1。
1:0	闲置。