PALLOCATE_CAPTURE_DMA_ENGINE回调函数（hdaudio.h）

项目
02/07/2025

AllocateCaptureDmaEngine 例程为捕获流分配 DMA 引擎。

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

语法

PALLOCATE_CAPTURE_DMA_ENGINE PallocateCaptureDmaEngine;

NTSTATUS PallocateCaptureDmaEngine(
  [in]  PVOID _context,
  [in]  UCHAR CodecAddress,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

参数

[in] _context

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

[in] CodecAddress

指定编解码器地址。此参数标识编解码器向 HD 音频总线控制器提供捕获数据的（SDI）行中的串行数据。 n SDI 引脚的总线控制器最多可以支持 n 编解码器，地址范围为 0 到 n-1。

[in] StreamFormat

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

[out] Handle

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

[out] ConverterFormat

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

返回值

如果调用成功保留 DMA 引擎，则 AllocateCaptureDmaEngine 返回STATUS_SUCCESS。否则，可能的返回值包括下表中的错误代码。

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

言论

此例程分配捕获 DMA 引擎并指定流的数据格式。如果成功，则例程输出调用方随后用于标识 DMA 引擎的句柄。

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

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

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

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

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

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

Windows 驱动程序模型（WDM）音频驱动程序在 NewStream 方法的执行期间在引脚创建时调用 AllocateCaptureDmaEngine（例如，请参阅 IMiniportWavePci：：NewStream）。