PSETUP_DMA_ENGINE_WITH_BDL回调函数 (hdaudio.h)

项目
07/28/2023

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

[in] Context

上下文。

[out] StreamId

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

[out] FifoSize

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

返回值

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

返回代码	说明
STATUS_UNSUCCESSFUL	指示调用方运行的 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 结合使用。与将 DMA 引擎配置为使用以前分配的 DMA 缓冲区的 SetupDmaEngineWithBdl 不同， AllocateDmaBuffer 既分配 DMA 缓冲区，又将 DMA 引擎配置为使用该缓冲区。

调用方必须调用 AllocateContiguousDmaBuffer ，以便为 DMA 缓冲区和描述缓冲区中物理内存页的 BDL 分配系统内存中的存储。 BDL 条目必须驻留在物理上连续的内存中。 BDL 和缓冲区内存必须满足 Intel 高清晰度音频规范 中所述的对齐要求 (请参阅 Intel HD Audio 网站) 。

BDL 及其描述的缓冲区内存在 DMA 操作期间必须保持有效。调用 SetupDmaEngineWithBdl 后，只要 DMA 引擎继续使用缓冲区，BDL 和缓冲区内存必须保持有效。 DMA 引擎使用缓冲区，直到函数驱动程序再次调用 SetupDmaEngineWithBdl 替换缓冲区，或通过调用 FreeDmaEngine 释放 DMA 引擎。函数驱动程序负责调用 FreeContiguousDmaBuffer ，以便在不再需要缓冲区和 BDL 时释放它们。

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

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

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

例如，WDM 音频驱动程序在执行 NewStream 方法期间，在 pin 创建时调用此例程 (，请参阅 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	FIFOE) (FIFO 错误。如果 FIFO 错误 (输出流上的溢出或输入流) 上的不足，则 HD Audio 控制器将 FIFOE 位设置为 1。
2	BCIS) (缓冲区完成中断状态。如果在缓冲区描述符的命令字节中将 IOC 位设置为 1，则 HD 音频控制器在处理缓冲区的最后一个样本后将 BCIS 位设置为 1。
1:0	未使用。