PBUILD_SCATTER_GATHER_LIST回调函数 (wdm.h)

BuildScatterGatherList 例程使用驱动程序提供的缓冲区生成散点/收集列表,为系统准备 DMA 操作。

语法

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [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] PVOID ScatterGatherBuffer,
  [in] ULONG ScatterGatherLength
)
{...}

参数

[in] DmaAdapter

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

[in] DeviceObject

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

[in] Mdl

指向 MDL 的指针,该指针描述由当前 IRP 的 MdlAddress 成员指定的缓冲区。

[in] CurrentVa

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

[in] Length

指定要映射的缓冲区的长度(以字节为单位)。

[in] ExecutionRoutine

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

[in] Context

指向调用时传递给 ExecutionRoutine 的驱动程序确定上下文的指针。

[in] WriteToDevice

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

[in] ScatterGatherBuffer

指向调用方提供的缓冲区的指针,该缓冲区由例程填充 SCATTER_GATHER_LIST 结构。

[in] ScatterGatherLength

指定 在 ScatterGatherBuffer 参数中传递的缓冲区的大小(以字节为单位)。

返回值

BuildScatterGatherList 返回以下值之一:

返回代码 说明
STATUS_SUCCESS 操作已成功完成。
STATUS_INSUFFICIENT_RESOURCES 系统没有足够的地图寄存器可用于传输。
STATUS_BUFFER_TOO_SMALL 指定的 Length 太大,无法容纳在缓冲区内。

注解

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

BuildScatterGatherList 执行与 GetScatterGatherList 相同的操作,只不过它使用 ScatterGatherBuffer 参数中提供的缓冲区来保存它创建的散点/收集列表。 相比之下, GetScatterGatherList 动态分配一个缓冲区来保存散点/收集列表。 如果内存不足,无法分配缓冲区, GetScatterGatherList 可能会失败并出现STATUS_INSUFFICIENT_RESOURCES错误。 必须避免这种情况的驱动程序可以预先分配缓冲区来保存散点/收集列表,并改用 BuildScatterGatherList

驱动程序可以使用 CalculateScatterGatherList 例程来确定要分配用于保存散点/收集列表的缓冲区的大小。

驱动程序应保留指向 ScatterGatherBuffer 中散点/收集列表的指针,以便在驱动程序调用 PutScatterGatherList 时使用。 驱动程序必须调用 PutScatterGatherList (这会刷新列表) ,然后才能访问列表中的数据。

要求

要求
最低受支持的客户端 在 Windows XP 和更高版本的 Windows 中可用。
目标平台 桌面
标头 wdm.h (包括 Wdm.h)
IRQL DISPATCH_LEVEL
DDI 符合性规则 IrqlDispatch (wdm)

另请参阅

BuildMdlFromScatterGatherList

CalculateScatterGatherList

DEVICE_DESCRIPTION

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

GetScatterGatherList

IoGetDmaAdapter

PutScatterGatherList

SCATTER_GATHER_LIST