NdisMAllocateSharedMemoryAsyncEx-Funktion (ndis.h)

Artikel
08/07/2023

Achtung

Für ARM- und ARM64-Prozessoren wird dringend empfohlen, dass NDIS-Treiberautoren WDF DMA oder WDM DMA anstelle von NDIS Scatter/Gather DMA verwenden.

Weitere Informationen zu WDF DMA finden Sie unter Behandeln von DMA-Vorgängen in KMDF-Treibern.

Weitere Informationen zu WDM DMA finden Sie in den DMA-bezogenen untergeordneten Themen unter Verwalten von Eingabe/Ausgabe für Treiber.

Miniport-Treiber rufen die NdisMAllocateSharedMemoryAsyncEx-Funktion auf, um zusätzlichen Arbeitsspeicher zuzuweisen, der zwischen dem Treiber und seiner Bus-master DMA-NIC gemeinsam genutzt wird, in der Regel, wenn der Miniporttreiber auf den verfügbaren NIC-Empfangspuffern nicht mehr verfügbar ist.

Syntax

NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx(
  [in] NDIS_HANDLE MiniportDmaHandle,
  [in] ULONG       Length,
  [in] BOOLEAN     Cached,
  [in] PVOID       Context
);

Parameter

[in] MiniportDmaHandle

Ein Handle für einen Kontextbereich, den NDIS zum Verwalten einer DMA-Ressource verwendet. Der Aufrufer hat dieses Handle abgerufen, indem er die NdisMRegisterScatterGatherDma-Funktion .

[in] Length

Die Anzahl der zu belegenden Bytes.

[in] Cached

Dieser Parameter wird ignoriert (zwischengespeicherter Arbeitsspeicher wird immer auf x86- und x64-Systemen verwendet).

[in] Context

Ein Zeiger auf den vom Treiber bestimmten Kontext, der beim Aufruf an die Funktion MiniportSharedMemoryAllocateComplete übergeben werden soll.

Rückgabewert

NdisMAllocateSharedMemoryAsyncEx kann eine der folgenden Rückgaben:

Rückgabecode	Beschreibung
NDIS_STATUS_PENDING	NDIS ruft die MiniportSharedMemoryAllocateComplete-Funktion auf und stellt Informationen bereit, die den zugeordneten freigegebenen Arbeitsspeicher beschreiben. Wenn der Versuch, freigegebenen Arbeitsspeicher zuzuweisen, fehlschlägt, ruft NDIS MiniportSharedMemoryAllocateComplete auf und übergibt NULL-Zeiger .
NDIS_STATUS_FAILURE	Der angeforderte Arbeitsspeicher konnte zu diesem Zeitpunkt nicht zugeordnet werden. Wenn NdisMAllocateSharedMemoryAsyncEx diese status zurückgibt, kann ein nachfolgender Aufruf mit den gleichen Parametern erfolgreich sein, je nachdem, ob Systemressourcen verfügbar sind.

Hinweise

Hinweis Ein Miniporttreiber muss bereits NdisMRegisterScatterGatherDma oder NdisMRegisterDmaChannel aufgerufen haben, um vor dem Aufrufen von NdisMAllocateSharedMemoryAsyncEx einen Punkt/Gather-DMA-Kanal zu initialisieren.

Treiber von Bus-master DMA-NICs rufen NdisMAllocateSharedMemoryAsyncEx auf, um gemeinsam genutzten Arbeitsspeicher dynamisch zuzuweisen. Diese Treiber weisen während der Initialisierung auch freigegebenen Speicherplatz zu. Diese Treiber verwenden den dynamisch zugeordneten freigegebenen Arbeitsspeicher für Übertragungsvorgänge, wenn ein hoher Netzwerkdatenverkehr zu hohe Anforderungen an den vorhandenen freigegebenen Speicherplatz stellt.

Ein solcher Miniporttreiber verwaltet in der Regel eine oder mehrere Zustandsvariablen, um die Anzahl der freigegebenen Speicherpuffer nachzuverfolgen, die für eingehende Übertragungen verfügbar sind. Wenn die Anzahl der verfügbaren Puffer einen vom Treiber festgelegten Niedrigen erreicht, ruft der Miniporttreiber NdisMAllocateSharedMemoryAsyncEx auf, um mehr Pufferspeicherplatz im freigegebenen Speicher zuzuweisen. Wenn die Anzahl der verfügbaren Puffer auf ein vom Treiber festgelegtes Hoch steigt, ruft der Miniporttreiber einmal oder mehrmals NdisMFreeSharedMemory auf, um seine vorherigen dynamischen Zuordnungen freizugeben.

In der Regel behält ein solcher Miniporttreiber den Block des gemeinsam genutzten Arbeitsspeichers bei, den seine MiniportInitializeEx-Funktion NdisMAllocateSharedMemory zugeordnet hat, bis eine NIC entfernt wird. Wenn die NIC entfernt wird, ruft NDIS die MiniportHaltEx-Funktion des Miniport-Treibers auf. Diese Zuordnung reicht aus, um einen durchschnittlichen Bedarf an Übertragungen über die Netzwerkkarte zu bewältigen.

Ein Miniporttreiber sollte einen Grenzwert für die Zuweisung von gemeinsam genutztem Arbeitsspeicher festlegen. Dieser Grenzwert ist treiberspezifisch und sollte hoch genug sein, damit dem Treiber nicht die Puffer ausgehen. Achten Sie nicht auf ein übermäßig hohes Limit, da dies zu einem verschwenderlichen Verbrauch von gemeinsam genutztem Arbeitsspeicher führen kann, der die Systemleistung beeinträchtigen könnte.

Jeder Miniporttreiber, der NdisMAllocateSharedMemoryAsyncEx oder NdisMAllocateSharedMemory aufruft, muss alle ausstehenden Zuordnungen mit einem oder mehreren Aufrufen von NdisMFreeSharedMemory freigeben, wenn seine NIC entfernt wird.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.0 und höher.
Zielplattform	Universell
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	Irql_Gather_DMA_Function(ndis)