PGET_SCATTER_GATHER_LIST回调函数 (wdm.h)

项目
08/08/2023

GetScatterGatherList 例程通过系统 DMA 控制器或总线主适配器代表目标设备对象为 DMA 散点/收集操作准备系统。

语法

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice
)
{...}

参数

[in] DmaAdapter

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

[in] DeviceObject

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

[in] Mdl

指向 MDL 的指针，该指针描述当前 IRP 中 MdlAddress 处的缓冲区。

[in] CurrentVa

指向 MDL 中要为 DMA 传输操作映射的缓冲区的当前虚拟地址的指针。

[in] Length

指定要映射的长度（以字节为单位）。

[in] ExecutionRoutine

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

[in] Context

指向驱动程序确定的上下文的指针，该上下文在调用时传递给驱动程序的 AdapterListControl 例程。

[in] WriteToDevice

指示 DMA 传输的方向：从缓冲区到设备的传输为 TRUE ，否则为 FALSE 。

返回值

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

返回代码	说明
STATUS_SUCCESS	操作成功。
STATUS_INSUFFICIENT_RESOURCES	例程无法分配足够的内存，或者传输所需的映射寄存器数大于 IoGetDmaAdapter 返回的值。
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法进行请求的传输。

注解

GetScatterGatherList 例程动态分配一个缓冲区来保存散点/收集列表。有关缓冲区分配失败时可能的 NTSTATUS 值，请参阅返回值。

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

当相应的 DMA 通道和任何必要的映射寄存器可用时， GetScatterGatherList 会立即创建散点/收集列表，初始化映射寄存器，然后调用驱动程序提供的 AdapterListControl 例程来执行 I/O 操作。

GetScatterGatherList 合并了执行散点/收集 DMA 的驱动程序的 AllocateAdapterChannel 和 MapTransfer 例程的操作。 GetScatterGatherList 确定传输所需的映射寄存器数、分配映射寄存器、映射 DMA 的缓冲区以及填充散点/收集列表。然后，它调用提供的 AdapterListControl 例程，将指针传递到 ScatterGather 中的散点/收集列表。驱动程序应保留此指针，以便在调用 PutScatterGatherList 时使用。请注意， GetScatterGatherList 没有适用于 AllocateAdapterChannel 的队列限制。

在其 AdapterListControl 例程中，驱动程序应执行 I/O。从驱动程序提供的例程返回时， GetScatterGatherList 会保留映射寄存器，但释放 DMA 适配器结构。驱动程序必须调用 PutScatterGatherList (以刷新缓冲区) ，然后才能访问缓冲区中的数据。

此例程可以处理链接的 MDL，前提是所有链接的 MDL 所需的映射寄存器总数不超过可用的映射寄存器数。

要求

要求	值
最低受支持的客户端	在 Windows 2000 和更高版本的 Windows 中可用。在 Windows 98 或 Windows Me 中不受支持。
目标平台	桌面
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
IRQL	DISPATCH_LEVEL
DDI 符合性规则	IrqlDispatch (storport) 、IrqlDispatch (storport) 、 IrqlDispatch (wdm)