PCALCULATE_SCATTER_GATHER_LIST_SIZE回调函数（wdm.h）

项目
02/07/2025

CalculateScatterGatherList 例程计算保存给定缓冲区所需的散点/收集列表的大小（以字节为单位）。

语法

PCALCULATE_SCATTER_GATHER_LIST_SIZE PcalculateScatterGatherListSize;

NTSTATUS PcalculateScatterGatherListSize(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in, optional]  PMDL Mdl,
  [in]            PVOID CurrentVa,
  [in]            ULONG Length,
  [out]           PULONG ScatterGatherListSize,
  [out, optional] PULONG pNumberOfMapRegisters
)
{...}

参数

[in] DmaAdapter

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

[in, optional] Mdl

NULL 或指向包含缓冲区的 MDL 的指针。

[in] CurrentVa

指向缓冲区开头的虚拟地址的指针。

[in] Length

指定缓冲区的长度（以字节为单位）。

[out] ScatterGatherListSize

指向例程用来返回散点/收集列表大小的变量的指针，以字节为单位。

[out, optional] pNumberOfMapRegisters

NULL 或指向例程用来返回缓冲区上 DMA作所需的映射寄存器数的变量的指针。

返回值

CalculateScatterGatherList 返回以下状态代码之一。

返回代码	描述
STATUS_SUCCESS	ScatterGatherListSize 中返回的值有效，NumberOfMapRegisters 有效。
STATUS_INSUFFICIENT_RESOURCES	所需的地图寄存器数超过了可用的地图寄存器数。
STATUS_BUFFER_TOO_SMALL	指定的长度太大，无法容纳在缓冲区中。

言论

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

如果调用方为 Mdl 参数传递 NULL，则例程将计算为指定缓冲区保存散点/收集列表所需的最大可能大小。如果调用方指定包含 Mdl 参数中的缓冲区的 MDL，则例程将计算保存散点/收集列表所需的实际大小。

驱动程序使用 CalculateScatterGatherList 分配散点/收集列表缓冲区，以传递给 buildScatterGatherList 。

要求

要求	价值
最低支持的客户端	在 Windows XP 和更高版本的 Windows 中可用。
目标平台	桌面
标头	wdm.h （包括 Wdm.h）
IRQL	任何级别