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

例程用來傳回緩衝區上 DMA 作業所需的對應緩存器數目的 NULL 或變數指標。

傳回值

CalculateScatterGatherList 會傳回下列其中一個狀態代碼。

傳回碼	Description
STATUS_SUCCESS	ScatterGatherListSize 和 NumberOfMapRegisters 中傳回的值有效。
STATUS_INSUFFICIENT_RESOURCES	所需的地圖緩存器數目超過可用的地圖緩存器數目。
STATUS_BUFFER_TOO_SMALL	指定的 Length 太大，無法容納於緩衝區內。

備註

CalculateScatterGatherList 不是可直接依名稱呼叫的系統例程。這個例程只能由 DMA_OPERATIONS結構中傳回之位址的指標呼叫。驅動程式會呼叫IoGetDmaAdapter，並將DeviceDescription參數的Version成員設定為 DEVICE_DESCRIPTION_VERSION2，以取得此例程的位址。如果 IoGetDmaAdapter 傳回 NULL，則您的平台上無法使用例程。

如果呼叫端為 Mdl 參數傳遞 NULL，則例程會計算保存指定緩衝區散佈/收集清單所需的最大大小。如果呼叫端指定 MDL，其中包含 Mdl 參數中的緩衝區，則例程會計算保存散佈/收集清單所需的實際大小。

驅動程式會使用 CalculateScatterGatherList 來配置散佈/收集清單緩衝區，以傳遞至 BuildScatterGatherList。

規格需求

需求	值
最低支援的用戶端	可在 Windows XP 和更新版本的 Windows 中使用。
目標平台	桌面
標頭	wdm.h (包含 Wdm.h)
IRQL	任何層級