PALLOCATE_ADAPTER_CHANNEL_EX回调函数 (wdm.h)

项目
08/08/2023

AllocateAdapterChannelEx 例程分配执行 DMA 传输所需的资源，然后调用驱动程序提供的 AdapterControl 例程来启动 DMA 传输。

语法

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

参数

[in] DmaAdapter

指向 DMA_ADAPTER 结构的指针。此结构是适配器对象，表示驱动程序的总线主 DMA 设备或系统 DMA 通道。调用方从对 IoGetDmaAdapter 例程的上一次调用中获取了此指针。

[in] DeviceObject

指向 DEVICE_OBJECT 结构的指针。此结构是物理设备对象 (PDO) ，表示所请求的 DMA 操作的目标设备。

[in] DmaTransferContext

指向已初始化的 DMA 传输上下文的指针。此上下文是通过对 InitializeDmaTransferContext 例程的先前调用初始化的。此上下文在所有适配器分配请求中必须是唯一的。若要取消挂起的分配请求，调用方必须将请求的 DMA 传输上下文提供给 CancelAdapterChannel 例程。

[in] NumberOfMapRegisters

要用于 DMA 传输的映射寄存器数。调用驱动程序应将此值设置为满足当前传输请求所需的映射寄存器数和可用映射寄存器数的较小值。驱动程序之前调用 GetDmaTransferInfo 例程以获取传输所需的映射寄存器数，并调用 IoGetDmaAdapter 例程来获取可用映射寄存器的数量。

[in] Flags

适配器通道分配标志。支持以下标志。

标志	含义
DMA_SYNCHRONOUS_CALLBACK	AllocateAdapterChannelEx 例程是同步调用的。如果设置了此标志，并且所需的 DMA 资源不能立即可用，则调用将失败并返回STATUS_INSUFFICIENT_RESOURCES。

如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志， 则 ExecutionRoutine 参数是可选的，可以为 NULL。有关此标志的详细信息，请参阅备注部分。

[in, optional] ExecutionRoutine

指向驱动程序提供的 AdapterControl 例程的指针，该例程启动驱动程序的 DMA 传输。 I/O 管理器在为适配器对象分配所需的资源后调用 AdapterControl 例程。 AdapterControl 例程返回后，I/O 管理器会自动释放适配器对象。 I/O 管理器可能会额外释放为此对象分配的资源，具体取决于此例程返回的值。

如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志， 则 ExecutionRoutine 是可选的，可以为 NULL。在这种情况下，调用方可以使用 AllocateAdapterChannelEx 分配的资源，稍后通过调用 FreeAdapterObject 例程释放这些资源。有关详细信息，请参见“备注”部分。

[in, optional] ExecutionContext

驱动程序确定的适配器控制上下文。此上下文作为 Context 参数传递到 AdapterControl 例程。

[out, optional] MapRegisterBase

指向变量的指针，例程将句柄写入分配的映射寄存器。调用方可以将此句柄作为参数提供给 FlushAdapterBuffersEx、 FlushAdapterBuffers、 FreeMapRegisters 或 MapTransferEx 例程。

如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志， 则 MapRegisterBase 必须是有效的非 NULL 指针。如果 ExecutionRoutine 参数为非 NULL， 则 MapRegisterBase 必须为 NULL。如果 MapRegisterBase 为非 NULL 且未设置 DMA_SYNCHRONOUS_CALLBACK 标志，或者 MapRegisterBase 和 ExecutionRoutine 均为 NULL，则调用将失败。

返回值

如果调用成功，AllocateAdapterChannelEx 将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	说明
STATUS_INVALID_PARAMETERS	由于调用方传递的参数值无效，例程失败。
STATUS_INSUFFICIENT_RESOURCES	例程未能分配 DMA 传输所需的资源。

注解

AllocateAdapterChannelEx 不是可直接按名称调用的系统例程。此例程只能由DMA_OPERATIONS结构中返回的地址中的指针调用 。驱动程序通过调用 IoGetDmaAdapter（DeviceDescription 参数的 Version 成员设置为 DEVICE_DESCRIPTION_VERSION3）来获取此例程的地址。如果 IoGetDmaAdapter 返回 NULL，则例程在平台上不可用。

AllocateAdapterChannelEx 分配执行 DMA 操作所需的资源。这些资源包括 DMA 通道和映射寄存器。分配所有必需的资源供 DMA 适配器使用后， AllocateAdapterChannelEx 调用调用方提供的 AdapterControl 例程来启动 DMA 操作。

默认情况下， AllocateAdapterChannelEx 以异步方式返回，而无需等待请求的资源分配完成。此返回后，调用方可以在必要时通过调用 CancelAdapterChannel 例程来取消挂起的分配请求。

如果调用驱动程序设置 DMA_SYNCHRONOUS_CALLBACK 标志， 则 AllocateAdapterChannelEx 例程的行为如下所示：

如果请求的 DMA 资源不能立即可用， 则 AllocateAdapterChannelEx 不会等待资源，也不会调用 AdapterControl 例程。相反， AllocateAdapterChannelEx 会失败并返回STATUS_INSUFFICIENT_RESOURCES。
如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志，则驱动程序不需要提供 AdapterControl 例程。
如果驱动程序提供 AdapterControl 例程， 则DMA_SYNCHRONOUS_CALLBACK 标志指示在 AllocateAdapterChannelEx 返回之前，将在调用线程的上下文中调用此例程。
如果驱动程序不提供 AdapterControl 例程，驱动程序可以在 AllocateAdapterChannelEx 返回 后使用分配的资源。在这种情况下，驱动程序必须在使用分配的资源完成后调用 FreeAdapterObject 。