PALLOCATE_ADAPTER_CHANNEL回调函数 (wdm.h)

项目
02/27/2024

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 不会排队，驱动程序应使用相应的错误代码 (（例如STATUS_INSUFFICIENT_RESOURCES) ）完成当前 IRP。

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

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

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

要求

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