PCALCULATE_SCATTER_GATHER_LIST_SIZE Rückruffunktion (wdm.h)

Artikel
07.02.2025

Die CalculateScatterGatherList- Routine berechnet die Größe in Bytes der Punkt-/Gather-Liste, die zum Speichern eines bestimmten Puffers erforderlich ist.

Syntax

C++

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, die den Busmasteradapter oder DMA-Controller darstellt.

[in, optional] Mdl

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

[in] CurrentVa

Zeigen Sie auf die virtuelle Adresse des Pufferanfangs.

[in] Length

Gibt die Länge des Puffers in Bytes an.

[out] ScatterGatherListSize

Zeiger auf die Variable, die von der Routine verwendet wird, um die Größe der Punkt/Gather-Liste in Byte 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 im Puffer erforderlich sind.

Rückgabewert

CalculateScatterGatherList gibt einen der folgenden Statuscodes zurück.

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

Bemerkungen

CalculateScatterGatherList ist keine Systemroutine, die direkt nach Namen aufgerufen werden kann. Diese Routine kann nur durch Zeiger von der in einer DMA_OPERATIONS Struktur zurückgegebenen Adresse aufgerufen werden. Treiber rufen die Adresse dieser Routine ab, indem sie IoGetDmaAdapter- mit dem Version Member des DeviceDescription- Parameters auf DEVICE_DESCRIPTION_VERSION2 festgelegt wird. 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 Punkt/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 Punkt/Gather-Liste erforderlich ist.

Ein Treiber verwendet CalculateScatterGatherList, um einen Punkt/Gather-Listenpuffer zuzuweisen, der an BuildScatterGatherListübergeben wird.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Verfügbar in Windows XP und höheren Versionen von Windows.
Zielplattform-	Desktop
Header-	wdm.h (include Wdm.h)
IRQL-	Beliebige Ebene