PALLOCATE_DMA_BUFFER回调函数 (hdaudio.h)

项目
08/07/2023

例 AllocateDmaBuffer 程在系统内存中为 DMA 引擎分配数据缓冲区。

例程的 AllocateDmaBuffer 函数指针类型定义如下。

语法

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

NTSTATUS PallocateDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

参数

[in] _context

指定来自HDAUDIO_BUS_INTERFACE和HDAUDIO_BUS_INTERFACE_V2结构的 Context 成员的上下文值。

[in] Handle

标识 DMA 引擎的句柄。此句柄值是从上一次调用 AllocateCaptureDmaEngine 或 AllocateRenderDmaEngine 获取的。

[in] RequestedBufferSize

指定请求的缓冲区大小（以字节为单位）。

[out] BufferMdl

检索包含已分配缓冲区的物理内存页。此参数指向调用方分配的 PMDL 变量，例程将指向内存描述符列表的指针写入 (描述缓冲区的 MDL) 。

[out] AllocatedBufferSize

检索分配的缓冲区大小（以字节为单位）。此参数指向调用方分配SIZE_T变量，例程将分配的缓冲区的大小写入其中。

[out] StreamId

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

[out] FifoSize

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

返回值

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

返回代码	说明
STATUS_UNSUCCESSFUL	指示调用方运行的 IRQL 过高。
STATUS_INSUFFICIENT_RESOURCES	指示缓冲区分配失败。
STATUS_INVALID_HANDLE	指示句柄参数值无效。
STATUS_INVALID_PARAMETER	指示其中一个参数值不正确 (错误的指针) 。
STATUS_DEVICE_NOT_READY	指示硬件编程超时。如果发生这种情况，则硬件可能处于已泄露状态。
STATUS_INVALID_DEVICE_REQUEST	指示流未处于重置状态，或者已为 DMA 引擎分配缓冲区。

注解

例 AllocateDmaBuffer 程与 FreeDmaBuffer 例程结合使用。这两个例程仅在 hd Audio DDI 的 HDAUDIO_BUS_INTERFACE 和 HDAUDIO_BUS_INTERFACE_V2 版本中可用。此 DDI 不包括 AllocateContiguousDmaBuffer、 SetupDmaEngineWithBdl 和 FreeContiguousDmaBuffer 例程，这些例程从未与 AllocateDmaBuffer 和 FreeDmaBuffer 一起使用。与将 DMA 引擎配置为使用以前分配的 DMA 缓冲区的 SetupDmaEngineWithBdl 不同， AllocateDmaBuffer 两者都分配 DMA 缓冲区，并将 DMA 引擎配置为使用该缓冲区。

如果 DMA 引擎无法使用参数 requestedBufferSize 中请求的大小的缓冲区，则例程将分配尽可能接近所请求大小的缓冲区。

音频或调制解调器编解码器的函数驱动程序负责对编解码器进行编程，以管理数据传输和识别流标识符。

例程输出一个列出包含缓冲区的物理内存页的 MDL。缓冲区基址与列表中第一个物理页的开头一致。

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

在调用 AllocateDmaBuffer 和 FreeDmaBuffer 期间，DMA 引擎必须处于重置流状态。调用Allocate XxxDmaEngine 后，DMA 引擎立即处于重置状态。若要将 DMA 引擎更改为运行状态，请调用 SetDmaEngineState。

FIFO 大小是 DMA 引擎在其内部缓冲区中可以容纳的最大字节数。根据硬件实现，DMA 引擎的 FIFO 大小可以是静态的，也可以随流格式的变化而动态变化。有关 FIFO 大小的详细信息，请参阅 Intel HD Audio 网站上的 Intel 高清晰度音频规范。

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

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

在 Windows Server 2003、Windows XP、Windows 2000 和 Windows Me/98 中，WDM 音频驱动程序在调用 HD Audio DDI) 中的一个 AllocateXxxDmaEngine 例程后，在执行其 NewStream 方法时 () 或 SetFormat 方法 (调用此例程。有关详细信息，请参阅 IMiniportWavePci：：NewStream 和 IMiniportWavePciStream：：SetFormat。