PALLOCATE_ADAPTER_CHANNEL回调函数 (wdm.h)

AllocateAdapterChannel 例程代表目标设备对象为 DMA 操作准备系统,然后调用驱动程序提供的 AdapterControl 例程来执行 DMA 操作。

语法

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

参数

[in] DmaAdapter

指向 IoGetDmaAdapter 返回的DMA_ADAPTER结构的指针,该结构表示总线主适配器或 DMA 控制器。

[in] DeviceObject

指向表示所请求 DMA 操作的目标设备的设备对象的指针。

[in] NumberOfMapRegisters

指定要在传输中使用的地图寄存器数。 此值是满足当前传输请求所需的映射寄存器数,以及 IoGetDmaAdapter 返回的可用映射寄存器数。

[in] ExecutionRoutine

指向驱动程序提供的 AdapterControl 例程的指针。 当系统 DMA 控制器或总线主适配器可用时,将调用例程。

[in] Context

指向要传递给 AdapterControl 例程的驱动程序确定上下文的指针。

返回值

此例程可以返回以下 NTSTATUS 值之一。

返回代码 说明
STATUS_SUCCESS
已分配适配器通道。 系统将在 DMA 操作开始后调用 AdapterControl 例程。
STATUS_INSUFFICIENT_RESOURCES
NumberOfMapRegisters 大于 IoGetDmaAdapter 返回的值。 不会调用 AdapterControl 例程。

注解

AllocateAdapterChannel 不是可以直接按名称调用的系统例程。 此例程只能通过 DMA_OPERATIONS结构中 返回的地址的指针调用。 驱动程序通过调用 IoGetDmaAdapter 获取此例程的地址。

驱动程序调用 AllocateAdapterControl 例程来注册用于为驱动程序执行 DMA 操作的 AdapterControl 例程。 AdapterControl 例程使用系统 DMA 控制器或总线主适配器执行 DMA 操作。

如果可以立即执行 DMA 操作,系统将立即调用 AdapterControl。 如果系统 DMA 控制器或总线主适配器当前正在使用, 则 AllocateAdapterChannel 会将 AdapterControl 排队,直到适配器可用。 在这两种情况下, AllocateAdapterChannel 返回STATUS_SUCCESS。

如果系统缺少执行 DMA 操作的资源, 则 AllocateAdapterChannel 将返回STATUS_INSUFFICIENT_RESOURCES。 在这种情况下, AdapterControl 未排队,驱动程序应使用相应的错误代码完成当前 IRP (,例如STATUS_INSUFFICIENT_RESOURCES) 。

此例程保留对 DMA 控制器通道的独占访问权限,并映射满足当前 IRP 针对指定设备的传输请求所需的一个或多个 DMA 操作的寄存器。

每次只能为设备对象排队一个 DMA 请求。 因此,在 AdapterControl 例程完成执行之前,驱动程序不应在同一设备对象上再次调用 AllocateAdapterChannel 执行另一个 DMA 操作。 此外,驱动程序不得在其 AdapterControl 例程中调用 AllocateAdapterChannel

系统将 DeviceObjectCurrentIrp 成员的值作为 AdapterControlIrp 参数传递。 如果从驱动程序的 StartIo 例程调用 AllocateAdapterChannel,则这可以保证指向调用 StartIo 来处理的 IRP。 否则,若要使用 AdapterControlIrp 参数,驱动程序必须在调用 AllocateAdapterChannel 之前将 CurrentIrp 设置为指向当前 IRP。

要求

   
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 桌面
标头 wdm.h(包括 Wdm.h、Ntddk.h、Ntifs.h)
IRQL DISPATCH_LEVEL
DDI 符合性规则 IrqlDispatch (storport) 、IrqlDispatch (storport ) 、 IrqlDispatch (wdm)

另请参阅

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

FlushAdapterBuffers

FreeAdapterChannel

FreeMapRegisters

IoGetDmaAdapter

MapTransfer

ReadDmaCounter