PCALCULATE_SCATTER_GATHER_LIST_SIZE Rückruffunktion (wdm.h)

Artikel
02/29/2024

Die CalculateScatterGatherList-Routine berechnet die Größe der Scatter-/Gather-Liste, die erforderlich ist, um einen bestimmten Puffer zu speichern.

Syntax

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

Parameter

[in] DmaAdapter

Zeiger auf die DMA_ADAPTER Struktur, die von IoGetDmaAdapter zurückgegeben wird und den Bus-master-Adapter oder DMA-Controller darstellt.

[in, optional] Mdl

Entweder NULL oder ein Zeiger auf die MDL, die den Puffer enthält.

[in] CurrentVa

Zeiger auf die virtuelle Adresse des Pufferanfangs.

[in] Length

Gibt die Länge des Puffers in Bytes an.

[out] ScatterGatherListSize

Zeiger auf die Variable, die die Routine verwendet, um die Größe der Scatter/Gather-Liste in Bytes zurückzugeben.

[out, optional] pNumberOfMapRegisters

Entweder NULL oder zeiger auf die Variable, die die Routine verwendet, um die Anzahl der Kartenregister zurückzugeben, die für DMA-Vorgänge auf dem Puffer erforderlich sind.

Rückgabewert

CalculateScatterGatherList gibt einen der folgenden status-Codes zurück.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die in ScatterGatherListSize und NumberOfMapRegisters zurückgegebenen Werte sind gültig.
STATUS_INSUFFICIENT_RESOURCES	Die Anzahl der erforderlichen Kartenregister übersteigt die Anzahl der verfügbaren Kartenregister.
STATUS_BUFFER_TOO_SMALL	Die angegebene Länge ist zu groß, um in den Puffer zu passen.

Hinweise

CalculateScatterGatherList ist keine Systemroutine, die direkt nach Name aufgerufen werden kann. Diese Routine kann nur durch zeiger von der Adresse aufgerufen werden, die in einer DMA_OPERATIONS-Struktur zurückgegeben wird. Treiber erhalten die Adresse dieser Routine, indem Sie IoGetDmaAdapter aufrufen, wobei das Versionselement des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION2 festgelegt ist. Wenn IoGetDmaAdapterNULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

Wenn der Aufrufer NULL für den Mdl-Parameter übergibt, berechnet die Routine die maximal mögliche Größe, die erforderlich ist, um eine Scatter/Gather-Liste für den angegebenen Puffer zu enthalten. Wenn der Aufrufer die MDL angibt, die den Puffer im Mdl-Parameter enthält, berechnet die Routine die tatsächliche Größe, die zum Aufnehmen der Scatter/Gather-Liste erforderlich ist.

Ein Treiber verwendet CalculateScatterGatherList , um einen Scatter/Gather-Listenpuffer zuzuweisen, der an BuildScatterGatherList übergeben werden soll.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows XP und höheren Versionen von Windows.
Zielplattform	Desktop
Kopfzeile	wdm.h (einschließen von Wdm.h)
IRQL	Beliebige Ebene