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

[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 Audio DDI 的 HDAUDIO_BUS_INTERFACE_BDL 版本中可用。 此 DDI 不包括 AllocateDmaBufferFreeDmaBuffer 例程,这些例程永远不会与 AllocateContiguousDmaBuffer一起使用、SetupDmaEngineWithBdlFreeContiguousDmaBuffer。 与 SetupDmaEngineWithBdl不同,它将 DMA 引擎配置为使用以前分配的 DMA 缓冲区,AllocateDmaBuffer 同时分配 DMA 缓冲区并将 DMA 引擎配置为使用缓冲区。 有关详细信息,请参阅 两个 DDI 版本之间的差异

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

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

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

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

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

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

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

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

要求

要求 价值
目标平台 桌面
标头 hdaudio.h (包括 Hdaudio.h)
IRQL PASSIVE_LEVEL

另请参阅

AllocateCaptureDmaEngine

AllocateDmaBuffer

AllocateRenderDmaEngine

FreeContiguousDmaBuffer

FreeDmaBuffer

HDAUDIO_BUS_INTERFACE_BDL

SetDmaEngineState

SetupDmaEngineWithBdl