PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION回调函数 (hdaudio.h)

项目
08/07/2023

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

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

语法

PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION PallocateDmaBufferWithNotification;

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

参数

[in] _context

指定 HDAUDIO_BUS_INTERFACE_V2 结构的 Context 成员中的上下文值。

[in] Handle

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

[in] NotificationCount

根据通过音频缓冲区的 DMA 进度指定所需的通知数。目前支持值 1 或 2。如果值为 1，则每次完成循环音频缓冲区并且 DMA 回退到开头时，都会发出任何已注册的通知事件信号。当值为 2 时，当 DMA 通过音频缓冲区的中点以及 (末尾或环绕点) 时，任何已注册的通知事件都会收到通知。

[in] RequestedBufferSize

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

[out] BufferMdl

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

[out] AllocatedBufferSize

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

OffsetFromFirstPage

[out] StreamId

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

[out] FifoSize

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

返回值

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

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

注解

例 AllocateDmaBufferWithNotification 程与 FreeDmaBufferWithNotification 例程一起使用。这两个例程仅在 hd Audio DDI 的 HDAUDIO_BUS_INTERFACE_V2 版本中可用。与将 DMA 引擎配置为使用以前分配的 DMA 缓冲区的 SetupDmaEngineWithBdl 不同， AllocateDmaBufferWithNotification 它分配 DMA 缓冲区，并将 DMA 引擎配置为使用该缓冲区。

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

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

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

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

在调用 AllocateDmaBufferWithNotification 和 FreeDmaBufferWithNotification 期间，DMA 引擎必须处于重置流状态。调用 AllocateCaptureDmaEngine 或 AllocateRenderDmaEngine 后， DMA 引擎立即处于重置流状态。若要将 DMA 引擎更改为运行状态，请调用 SetDmaEngineState。

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

在 Windows Vista 及更高版本的 Windows 中，WaveRT 微型端口驱动程序在收到 KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION 属性请求时调用此例程。

要求

要求	值
最低受支持的客户端	在 Windows Vista 和更高版本的 Windows 中可用。
目标平台	桌面
标头	hdaudio.h (包括 Hdaudio.h)
IRQL	PASSIVE_LEVEL。