PALLOCATE_RENDER_DMA_ENGINE回调函数 (hdaudio.h)

项目
02/26/2024

例 AllocateRenderDmaEngine 程为呈现流分配 DMA 引擎。

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

语法

PALLOCATE_RENDER_DMA_ENGINE PallocateRenderDmaEngine;

NTSTATUS PallocateRenderDmaEngine(
  [in]  PVOID _context,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [in]  BOOLEAN Stripe,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

参数

[in] _context

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

[in] StreamFormat

指定请求的流格式。此参数指向调用方分配的 HDAUDIO_STREAM_FORMAT 类型的结构，该结构指定流的数据格式。

[in] Stripe

指定是否启用条带化。如果 为 TRUE，则例程在 DMA 传输中启用条带化。如果 为 FALSE，则禁用条带化。

[out] Handle

检索 DMA 引擎的句柄。此参数指向调用方分配的 HANDLE 变量，例程在该变量中写入标识 DMA 引擎的句柄。

[out] ConverterFormat

检索转换器格式。此参数指向调用方分配的 HDAUDIO_CONVERTER_FORMAT 类型的结构，例程将编码格式写入其中。

返回值

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

返回代码	说明
STATUS_BUFFER_TOO_SMALL	指示 DMA 引擎无法分配足够的内部 FIFO 存储来支持请求的流格式。
STATUS_INSUFFICIENT_RESOURCES	指示没有可用的 DMA 引擎或请求超过可用带宽资源。
STATUS_INVALID_PARAMETER	指示其中一个参数值不正确 (无效参数值或指针) 错误。

注解

此例程分配呈现 DMA 引擎并指定流的数据格式。如果成功，例程会输出一个句柄，调用方随后使用该句柄来标识 DMA 引擎。

例 AllocateRenderDmaEngine 程保留硬件资源 (DMA 引擎) 但不配置 DMA 硬件。调用此例程以保留 DMA 引擎后，函数驱动程序必须将 DMA 缓冲区分配给 DMA 引擎，并将该引擎配置为使用该缓冲区：

如果使用 HDAUDIO_BUS_INTERFACE 版本的 HD Audio DDI，则函数驱动程序会调用 AllocateDmaBuffer 例程，让 HD Audio 总线驱动程序为 DMA 传输分配数据缓冲区，并将 DMA 引擎设置为使用该缓冲区。
如果使用 HDAUDIO_BUS_INTERFACE_BDL 版本的 DDI，函数驱动程序会调用 AllocateContiguousDmaBuffer 来分配 DMA 缓冲区，并调用 SetupDmaEngineWithBdl 例程来设置 DMA 引擎以使用缓冲区。

streamFormat 参数指定捕获流的数据格式。调用 AllocateRenderDmaEngine后，可以通过调用 ChangeBandwidthAllocation 更改流的格式。

stripe 参数指定 DMA 引擎是否使用条带化来加快数据传输速度。有关详细信息，请参阅条带化。

通过 handle 参数，例程输出一个句柄，调用方使用该句柄在后续调用 AllocateDmaBuffer、 ChangeBandwidthAllocation、 FreeDmaBuffer、 SetupDmaEngineWithBdl 和 SetDmaEngineState 时标识分配的 DMA 引擎。函数驱动程序通过调用 FreeDmaEngine 释放句柄。

通过 converterFormat 参数，例程输出调用方可用于对输出转换器进行编程的流描述符值。例程将 streamFormat 参数中的信息编码为 16 位整数。有关详细信息，请参阅 HDAUDIO_CONVERTER_FORMAT。

成功调用 AllocateRenderDmaEngine后，DMA 引擎立即处于重置流状态。在调用 SetDmaEngineState 将 DMA 引擎更改为正在运行、暂停或停止状态之前，客户端必须先为引擎分配 DMA 缓冲区。

例如，WDM 音频驱动程序在执行其 NewStream 方法 (的 pin 创建时间调用 AllocateRenderDmaEngine ，请参阅 IMiniportWavePci：：NewStream) 。