PALLOCATE_DMA_BUFFER回调函数（hdaudio.h）

项目
02/07/2025

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

[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 上运行，该 IRQL 太高。
STATUS_INSUFFICIENT_RESOURCES	指示缓冲区分配失败。
STATUS_INVALID_HANDLE	指示句柄参数值无效。
STATUS_INVALID_PARAMETER	指示其中一个参数值不正确（指针错误）。
STATUS_DEVICE_NOT_READY	指示硬件编程超时。如果发生这种情况，则硬件可能处于泄露状态。
STATUS_INVALID_DEVICE_REQUEST	指示流未处于重置状态，或者已为 DMA 引擎分配缓冲区。

言论

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

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

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

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

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

在调用 AllocateDmaBuffer 和 FreeDmaBuffer期间，DMA 引擎必须处于重置流状态。 DMA 引擎在调用“分配XxxDmaEngine”后立即处于重置状态。若要将 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 音频驱动程序在执行其 NewStream 方法（在 pin 创建时间）或 SetFormat 方法（在 HD Audio DDI 中调用分配XxxDmaEngine 例程之一后）调用此例程。有关详细信息，请参阅 IMiniportWavePci：：NewStream 和 IMiniportWavePciStream：：SetFormat。