PCALCULATE_SCATTER_GATHER_LIST_SIZE funzione di callback (wdm.h)

Articolo
02/07/2025

La routine CalculateScatterGatherList calcola le dimensioni, in byte, dell'elenco di dispersione/raccolta necessario per contenere un determinato buffer.

Sintassi

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
)
{...}

Parametri

[in] DmaAdapter

Puntatore alla struttura DMA_ADAPTER restituita da IoGetDmaAdapter che rappresenta l'adattatore bus-master o il controller DMA.

[in, optional] Mdl

NULL o un puntatore al file MDL che contiene il buffer.

[in] CurrentVa

Puntatore all'indirizzo virtuale dell'inizio del buffer.

[in] Length

Specifica la lunghezza del buffer, espressa in byte.

[out] ScatterGatherListSize

Puntatore alla variabile utilizzata dalla routine per restituire le dimensioni dell'elenco a dispersione/raccolta, in byte.

[out, optional] pNumberOfMapRegisters

NULL o puntatore alla variabile utilizzata dalla routine per restituire il numero di registri mappa necessari per le operazioni DMA nel buffer.

Valore restituito

CalculateScatterGatherList restituisce uno dei codici di stato seguenti.

Codice restituito	Descrizione
STATUS_SUCCESS	I valori restituiti in ScatterGatherListSize e NumberOfMapRegisters sono validi.
STATUS_INSUFFICIENT_RESOURCES	Il numero di registri mappa necessari supera il numero di registri mappa disponibili.
STATUS_BUFFER_TOO_SMALL	La lunghezza specificata è troppo grande per rientrare nel buffer.

Osservazioni

CalculateScatterGatherList non è una routine di sistema che può essere chiamata direttamente per nome. Questa routine può essere chiamata solo dal puntatore dall'indirizzo restituito in una struttura DMA_OPERATIONS. I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter con il membro Version del parametro DeviceDescription impostato su DEVICE_DESCRIPTION_VERSION2. Se IoGetDmaAdapter restituisce NULL, la routine non è disponibile nella piattaforma.

Se il chiamante passa NULL per il parametro Mdl, la routine calcola le dimensioni massime possibili necessarie per contenere un elenco a dispersione/raccolta per il buffer specificato. Se il chiamante specifica il MDL che contiene il buffer nel parametro Mdl, la routine calcola le dimensioni effettive necessarie per contenere l'elenco a dispersione/raccolta.

Un driver usa CalculateScatterGatherList per allocare un buffer di elenco a dispersione/raccolta da passare a BuildScatterGatherList.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile in Windows XP e versioni successive di Windows.
piattaforma di destinazione	Desktop
intestazione	wdm.h (include Wdm.h)
IRQL	Qualsiasi livello