funzione di callback PCALCULATE_SCATTER_GATHER_LIST_SIZE (wdm.h)

Articolo
02/29/2024

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 di mapping 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 adattarsi al buffer.

Commenti

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 la dimensione massima possibile necessaria per contenere un elenco di dispersione/raccolta per il buffer specificato. Se il chiamante specifica il file 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 elenco a dispersione/raccolta da passare a BuildScatterGatherList.

Requisiti

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