NdisMAllocateSharedMemoryAsyncEx-Funktion (ndis.h)

Artikel
02/07/2025

Vorsicht

Für ARM- und ARM64-Prozessoren empfehlen wir dringend, 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 Drivers.

Weitere Informationen zu WDM DMA finden Sie in den DMA-bezogenen untergeordneten Themen Managing Input/Output for Drivers.

Miniport-Treiber rufen die NdisMAllocateSharedMemoryAsyncEx--Funktion auf, um zusätzlichen Arbeitsspeicher zuzuweisen, der zwischen dem Treiber und dem Busmaster DMA NIC gemeinsam genutzt wird, in der Regel, wenn der Miniporttreiber unter den verfügbaren NIC-Empfangspuffern ausgeführt wird.

Syntax

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

Parameter

[in] MiniportDmaHandle

Ein Handle zu einem Kontextbereich, den NDIS zum Verwalten einer DMA-Ressource verwendet. Der Aufrufer hat dieses Handle durch Aufrufen des NdisMRegisterScatterGatherDma Funktion.

[in] Length

Die Anzahl der zuzuordnenden Bytes.

[in] Cached

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

[in] Context

Ein Zeiger auf den treiberbestimmten Kontext, der beim Aufruf an die MiniportSharedMemoryAllocateComplete-Funktion übergeben werden soll.

Rückgabewert

NdisMAllocateSharedMemoryAsyncEx- kann eine der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
NDIS_STATUS_PENDING	NDIS ruft die MiniportSharedMemoryAllocateComplete-Funktion auf und stellt Informationen bereit, die den zugewiesenen freigegebenen Speicher beschreiben. Wenn der Versuch, gemeinsam genutzten Speicher zuzuweisen, fehlschlägt, ruft NDIS MiniportSharedMemoryAllocateComplete auf und übergibt NULL- Zeiger.
NDIS_STATUS_FAILURE	Der angeforderte Arbeitsspeicher konnte zurzeit nicht zugewiesen werden. Wenn NdisMAllocateSharedMemoryAsyncEx diesen Status zurückgibt, kann ein nachfolgender Aufruf mit denselben Parametern erfolgreich sein, je nachdem, ob Systemressourcen verfügbar sind.

Bemerkungen

Hinweis Ein Miniporttreiber muss bereits NdisMRegisterScatterGatherDma- oder NdisMRegisterDmaChannel- aufgerufen haben, um einen Scatter/Gather-DMA-Kanal zu initialisieren, bevor NdisMAllocateSharedMemoryAsyncExaufgerufen wird.

Treiber von Busmaster-DMA-NICs rufen NdisMAllocateSharedMemoryAsyncEx auf, um freigegebenen Speicher dynamisch zuzuweisen. Solche Treiber weisen während der Initialisierung auch gemeinsam genutzten Speicherplatz zu. Diese Treiber verwenden den dynamisch zugewiesenen freigegebenen Speicher für Übertragungsvorgänge, wenn hoher Netzwerkdatenverkehr übermäßige Anforderungen an den vorhandenen freigegebenen Speicherbereich stellt.

Ein solcher Miniporttreiber verwaltet in der Regel eine oder mehrere Statusvariablen, um die Anzahl der freigegebenen Speicherpuffer nachzuverfolgen, die für eingehende Übertragungen verfügbar sind. Wenn die Anzahl der verfügbaren Puffer einen treiberbestimmten niedrigen Wert erreicht, ruft der Miniporttreiber NdisMAllocateSharedMemoryAsyncEx auf, um mehr Pufferspeicher im gemeinsam genutzten Speicher zuzuweisen. Wenn die Anzahl der verfügbaren Puffer zu einem treiberbestimmten Hoch steigt, ruft der Miniporttreiber NdisMFreeSharedMemory mindestens ein Mal auf, um seine vorherigen dynamischen Zuordnungen freizugeben.

In der Regel behält ein solcher Miniporttreiber den Block des freigegebenen Speichers bei, den seine MiniportInitializeEx--Funktion NdisMAllocateSharedMemory, bis eine NIC entfernt wird. Wenn die NIC entfernt wird, ruft NDIS die MiniportHaltEx--Funktion des Miniporttreibers auf. Diese Zuweisung reicht aus, um einen durchschnittlichen Bedarf an Übertragungen über die NIC zu bewältigen.

Ein Miniporttreiber sollte einen Grenzwert für die Zuweisung des freigegebenen Speichers festlegen. Dieser Grenzwert ist treiberspezifisch und sollte hoch genug sein, damit der Treiber keine Puffer ausläuft. Beschränken Sie sich nicht auf eine übermäßig hohe Grenze, da dies zu einem verschwendeten Verbrauch von gemeinsam genutztem Speicher führen kann, der die Systemleistung verringern 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
mindestens unterstützte Client-	Unterstützt in NDIS 6.0 und höher.
Zielplattform-	Universal
Header-	ndis.h (include Ndis.h)
IRQL-	<= DISPATCH_LEVEL
DDI-Complianceregeln	Irql_Gather_DMA_Function(ndis)