PGET_SCATTER_GATHER_LIST_EX回调函数 (wdm.h)

项目
02/27/2024

GetScatterGatherListEx 例程分配 DMA 传输所需的资源，生成散点/收集列表，并调用驱动程序提供的 AdapterListControl 例程来启动 DMA 传输。

注意

不要为系统 DMA 设备调用此例程。

语法

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

参数

[in] DmaAdapter

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

[in] DeviceObject

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

[in] DmaTransferContext

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

[in] Mdl

指向 MDL 链的指针，该链描述虚拟内存中锁定缓冲区集合的物理页面布局。 DMA 传输的散点/收集列表将使用此内存的区域，该区域由 Offset 和 Length 参数指定。有关 MDL 链的详细信息，请参阅使用 MDL。

[in] Offset

散点/收集 DMA 传输的起始偏移量。此参数是 MDL 链中第一个 MDL 中缓冲区开头的字节偏移量。如果 MDL 链中的 MDL 指定总共 N 个字节的缓冲区空间， 则 Offset 的有效值在 0 到 N–1 的范围内。

[in] Length

DMA 传输的长度（以字节为单位）。如果 MDL 链指定缓冲区空间的总 N 个字节， 则 Length 的有效值在 1 到 N–Offset 的范围内。

[in] Flags

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

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

如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志， 则 ExecutionRoutine 参数是可选的，可以为 NULL。如果未设置此标志， 则 ExecutionRoutine 必须是有效的非 NULL 指针。有关此标志的详细信息，请参阅“备注”部分。

[in, optional] ExecutionRoutine

指向驱动程序提供的 AdapterListControl 例程的指针，该例程启动驱动程序的 DMA 传输。 I/O 管理器在为适配器对象分配所需的资源后调用 AdapterListControl 例程。 AdapterListControl 例程返回后，I/O 管理器会自动释放适配器对象以及为此对象分配的资源。

如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志， 则 ExecutionRoutine 参数是可选的，可以为 NULL。如果此参数为 NULL，则调用方可以使用 GetScatterGatherListEx 分配的资源在 GetScatterGatherListEx 返回后执行 DMA 传输。有关详细信息，请参见“备注”部分。

[in, optional] Context

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

[in] WriteToDevice

DMA 传输的方向。对于将数据从内存传输到设备的写入操作，请将此参数设置为 TRUE。对于将数据从设备传输到内存的读取操作，请将此参数设置为 FALSE。

[in, optional] DmaCompletionRoutine

未使用。设置为 NULL。

[in, optional] CompletionContext

未使用。设置为 NULL。

[out, optional] ScatterGatherList

指向变量的指针，例程将指针写入到分配的散点/收集列表。此参数指向 SCATTER_GATHER_LIST 结构。例程分配此结构和它指向 的SCATTER_GATHER_ELEMENT 数组。

ScatterGatherList 参数是可选的，如果 ExecutionRoutine 参数为非 NULL，则可以为 NULL。

如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志并且 ExecutionRoutine 参数为 NULL， 则 ScatterGatherList 必须是有效的非 NULL 指针。如果 ExecutionRoutine 为非 NULL， 则 ScatterGatherList 是可选的，如果调用驱动程序不需要散点/收集列表，则可以为 NULL 。如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志且 ScatterGatherList 和 ExecutionRoutine 均为 NULL，或者未设置 DMA_SYNCHRONOUS_CALLBACK 标志且 ExecutionRoutine 为 NULL，则 GetScatterGatherListEx 调用将失败。

返回值

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

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

注解

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

仅对总线主适配器使用 GetScatterGatherListEx 。请勿将此例程用于系统 DMA 适配器。

总线主设备的驱动程序可以使用 GetScatterGatherListEx 将 AllocateAdapterChannelEx 和 MapTransferEx 例程执行的操作合并到一个调用中。 GetScatterGatherListEx 执行以下操作：

分配 DMA 传输所需的资源。
基于 Mdl、 Offset 和 Length 参数的值生成散点/收集列表。
调用驱动程序提供的 AdapterListControl 例程，并将散点/收集列表作为参数提供给此例程。

分配的资源在 AdapterListControl 例程返回后自动释放。如果 同步调用 GetScatterGatherListEx (也就是说，如果 ) 设置DMA_SYNCHRONOUS_CALLBACK 标志，则可以省略 AdapterListControl 例程。在这种情况下，调用方使用分配的资源在 GetScatterGatherListEx 返回后启动 DMA 传输。调用方必须显式释放这些资源。

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

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

如果请求的资源不立即可用， 则 GetScatterGatherListEx 不会等待资源，不会生成散点/收集列表，也不会调用 AdapterListControl 例程。相反， GetScatterGatherListEx 会失败并返回STATUS_INSUFFICIENT_RESOURCES。
如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志，则驱动程序不需要提供 AdapterListControl 例程。
如果驱动程序提供 AdapterListControl 例程， 则DMA_SYNCHRONOUS_CALLBACK 标志指示在 GetScatterGatherListEx 返回之前，将在调用线程的上下文中调用此例程。
如果驱动程序不提供 AdapterListControl 例程，则驱动程序可以在 GetScatterGatherListEx 返回后使用分配的资源和散点/收集列表。在这种情况下，驱动程序必须提供有效的非 NULL ScatterGatherList 指针。此外，在驱动程序启动 DMA 传输后，驱动程序必须调用 FreeAdapterObject 例程来释放 GetScatterGatherListEx 为适配器对象分配的资源。

GetScatterGatherListEx 是 GetScatterGatherList 例程的扩展版本。以下功能仅在扩展版本中可用：

GetScatterGatherListEx 类似于 BuildScatterGatherListEx 例程，不同之处在于 GetScatterGatherListEx 自动分配散点/收集列表的缓冲区。

要求

要求	值
最低受支持的客户端	从Windows 8开始可用。
目标平台	桌面
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
IRQL	<= DISPATCH_LEVEL