PALLOCATE_CONTIGUOUS_DMA_BUFFER回调函数 (hdaudio.h)

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 引擎的句柄。 此句柄值是从上一次调用 AllocateCaptureDmaEngineAllocateRenderDmaEngine 中获取的。

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 例程与 SetupDmaEngineWithBdlFreeContiguousDmaBuffer 例程结合使用。 这三个例程仅在 HD 音频 DDI 的 HDAUDIO_BUS_INTERFACE_BDL 版本中可用。 此 DDI 不包括 AllocateDmaBufferFreeDmaBuffer 例程,这些例程从未与 AllocateContiguousDmaBufferSetupDmaEngineWithBdlFreeContiguousDmaBuffer 结合使用。 与 SetupDmaEngineWithBdl(将 DMA 引擎配置为使用以前分配的 DMA 缓冲区)不同, AllocateDmaBuffer 它们都分配 DMA 缓冲区,并将 DMA 引擎配置为使用缓冲区。 有关详细信息,请参阅 两个 DDI 版本之间的差异

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

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

例程为数据缓冲区和 BDL 分配的存储未初始化。 函数驱动程序负责在将 BDL 提交到 SetupDmaEngineWithBdl 例程之前填写 BDL。 函数驱动程序还负责编程编解码器来管理数据传输和识别流标识符。

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

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

在调用 AllocateContiguousDmaBuffer、SetupDmaEngineWithBdlFreeContiguousDmaBuffer 期间,DMA 引擎必须处于重置流状态。 DMA 引擎在调用“分配XxxDmaEngine”后立即处于重置状态。 若要将 DMA 引擎更改为运行状态,请调用 SetDmaEngineState

此例程失败,并返回以下任一情况下STATUS_INVALID_DEVICE_REQUEST的错误代码:

  • 任何以前分配的 DMA 缓冲区都没有通过调用 FreeContiguousDmaBuffer) 来释放 (。
  • 流处于重置状态。

要求

   
目标平台 桌面
Header hdaudio.h (包括 Hdaudio.h)
IRQL PASSIVE_LEVEL

另请参阅

AllocateCaptureDmaEngine

AllocateDmaBuffer

AllocateRenderDmaEngine

FreeContiguousDmaBuffer

FreeDmaBuffer

HDAUDIO_BUS_INTERFACE_BDL

SetDmaEngineState

SetupDmaEngineWithBdl