PALLOCATE_CAPTURE_DMA_ENGINE回调函数 (hdaudio.h)

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

[in] CodecAddress

指定编解码器地址。 此参数标识 (SDI) 行中的串行数据,编解码器将捕获数据提供给 HD 音频总线控制器。 具有 n 个 SDI 引脚的总线控制器最多可以支持 0 到 n-1 的地址的 n 个编解码器。

[in] StreamFormat

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

[out] Handle

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

[out] ConverterFormat

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

返回值

AllocateCaptureDmaEngine 如果调用成功保留 DMA 引擎,则返回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 更改流的格式。

通过 句柄 参数,例程输出调用方用来在对 AllocateDmaBufferChangeBandwidthAllocationFreeDmaBufferSetupDmaEngineWithBdlSetDmaEngineState 的后续调用中标识分配的 DMA 引擎的句柄。 函数驱动程序通过调用 FreeDmaEngine 释放句柄。

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

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

例如,在执行 NewStream 方法 (期间,Windows 驱动程序模型 (WDM) 音频驱动程序调用AllocateCaptureDmaEngine,请参阅 IMiniportWavePci::NewStream) 。

要求

   
目标平台 桌面
Header hdaudio.h (包括 Hdaudio.h)
IRQL PASSIVE_LEVEL

另请参阅

AllocateContiguousDmaBuffer

AllocateDmaBuffer

ChangeBandwidthAllocation

FreeDmaEngine

HDAUDIO_BUS_INTERFACE

HDAUDIO_BUS_INTERFACE_BDL

HDAUDIO_BUS_INTERFACE_V2

HDAUDIO_CONVERTER_FORMAT

HDAUDIO_STREAM_FORMAT

SetDmaEngineState

SetupDmaEngineWithBdl