PCALCULATE_SCATTER_GATHER_LIST_SIZE回调函数 (wdm.h)

项目
02/27/2024

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 参数的 Version 成员设置为 DEVICE_DESCRIPTION_VERSION2。如果 IoGetDmaAdapter 返回 NULL，则例程在平台上不可用。

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

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