PALLOCATE_CONTIGUOUS_DMA_BUFFER回调函数 (hdaudio.h)

项目
08/07/2023

例 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。否则，例程将返回相应的错误代码。下表显示了一些可能的返回状态代码。

返回代码	说明
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 Audio DDI 的 HDAUDIO_BUS_INTERFACE_BDL 版本中可用。此 DDI 不包括 AllocateDmaBuffer 和 FreeDmaBuffer 例程，这些例程永远不会与 AllocateContiguousDmaBuffer、 SetupDmaEngineWithBdl 和 FreeContiguousDmaBuffer 结合使用。与将 DMA 引擎配置为使用以前分配的 DMA 缓冲区的 SetupDmaEngineWithBdl 不同， AllocateDmaBuffer 两者都分配 DMA 缓冲区，并将 DMA 引擎配置为使用该缓冲区。有关详细信息，请参阅两个 DDI 版本之间的差异。

AllocateContiguousDmaBuffer 为指定的 DMA 引擎分配数据缓冲区。它还为 BDL 分配内存页。根据主机处理器体系结构，典型的页面大小可能是 4,096 或 8,192 字节。数据缓冲区由单个连续的物理内存块组成。

handle 参数指定使用数据缓冲区和 BDL 的 DMA 引擎。例程分配满足 DMA 引擎的大小、对齐方式和位置要求的存储。

例程为数据缓冲区和 BDL 分配的存储未初始化。函数驱动程序负责先填充 BDL，然后再将其提交到 SetupDmaEngineWithBdl 例程。函数驱动程序还负责对编解码器进行编程，以管理数据传输和识别流标识符。

若要以精确的间隔生成 IOC 中断，函数驱动程序可能需要将数据缓冲区分配划分为特定大小的多个片段。每个片段由 BDL 条目描述。可以调整片段大小以优化中断率。根据 Intel 高清晰度音频规范 (请参阅 Intel HD Audio 网站) ，每个片段必须从 128 字节边界开始，尽管没有此类对齐要求适用于片段的长度。因此，一个片段的末尾和下一个片段的开头之间可能存在间隙。调用 SetupDmaEngineWithBdl 时，函数驱动程序必须为 bufferSize 参数指定一个值，该值表示 BDL 条目所描述的各个片段的大小之和。此大小将小于或等于例程的 requestedBufferSize 参数中指定的AllocateContiguousDmaBuffer字节数。

在 DMA 引擎句柄的生存期内， AllocateContiguousDmaBuffer 可以连续调用以分配新的 DMA 缓冲区。但是，在调用 AllocateContiguousDmaBuffer之前，必须首先通过调用 FreeContiguousDmaBuffer 来释放以前分配的任何 DMA 缓冲区。

在调用 AllocateContiguousDmaBuffer、 SetupDmaEngineWithBdl 和 FreeContiguousDmaBuffer 期间，DMA 引擎必须处于重置流状态。调用 AllocateXxxDmaEngine 后，DMA 引擎立即处于重置状态。若要将 DMA 引擎更改为运行状态，请调用 SetDmaEngineState。

此例程在以下任一情况下失败并返回错误代码STATUS_INVALID_DEVICE_REQUEST：