NdisMAllocateSharedMemory-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.

NdisMAllocateSharedMemory einen Hostspeicherbereich zuordnet und zuordnet, sodass der Speicherbereich sowohl über das Hostsystem als auch über eine DMA-NIC gleichzeitig zugänglich ist.

Syntax

void NdisMAllocateSharedMemory(
  [in]  NDIS_HANDLE            MiniportAdapterHandle,
  [in]  ULONG                  Length,
  [in]  BOOLEAN                Cached,
  [out] PVOID                  *VirtualAddress,
  [out] PNDIS_PHYSICAL_ADDRESS PhysicalAddress
);

Parameter

[in] MiniportAdapterHandle

Gibt die Handleeingabe für MiniportInitializeEx-an.

[in] Length

Gibt die Anzahl der zuzuordnenden Bytes an.

[in] Cached

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

[out] VirtualAddress

Zeiger auf eine vom Aufrufer bereitgestellte Variable, in der diese Funktion die virtuelle Basisadresse der Zuordnung für die Verwendung durch den Miniporttreiber zurückgibt. Wenn NdisMAllocateSharedMemory den Aufrufer nicht erfüllen kann, wird NULL- zurückgegeben, um anzugeben, dass kein Speicher zugewiesen wurde.

[out] PhysicalAddress

Zeiger auf eine vom Aufrufer bereitgestellte Variable, in der diese Funktion eine physische Adresse zurückgibt, die für die Verwendung durch die NIC geeignet ist, die dem bei VirtualAddresszurückgegebenen entspricht, oder es gibt NULL-zurück.

Rückgabewert

Nichts

Bemerkungen

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

Microsoft Windows Server 2003, Windows XP Service Pack 1 und höhere Versionen von Windows ermöglichen sowohl Busmaster-DMA-NICs als auch untergeordnete DMA-NICs, NdisMAllocateSharedMemoryaufzurufen. In früheren Versionen können nur Busmaster-DMA-NICs NdisMAllocateSharedMemoryaufrufen. Wenn in diesen früheren Versionen MiniportInitializeEx nicht angegeben hat, dass die NIC ein Busmaster ist, wenn sie NdisMSetMiniportAttributes, NdisMAllocateSharedMemory einfach die Steuerung zurückgibt, ohne eine Zuordnung vorzunehmen.

NdisMAllocateSharedMemory stellt sowohl den zugeordneten virtuellen Adressbereich bereit, den der Treiber für den Zugriff auf den freigegebenen Speicherblock verwendet, als auch den von der NIC verwendeten Bereich vom Typ "-NDIS_PHYSICAL_ADDRESS". Ein bei PhysicalAddress zurückgegebener Wert kann vom System doubly zugeordnet werden. Das heißt, ein "physischer" Adressbereich, der durch den Wert bei PhysicalAddress und Length beschrieben wird, kann ein Bereich zugeordneter logischer Adressen sein, die nicht mit den physischen Hostadressen für die Zuordnung auf jeder möglichen Plattform übereinstimmen.

NdisMAllocateSharedMemory kann nur von MiniportInitializeExaufgerufen werden. Wie groß eine Anforderungszuweisung ist, hängt davon ab, wie der Treiberautor, wissend über die Funktionen und Features der NIC, entscheidet, den Kompromiss zwischen der folgenden Leistung gegenüber dem Größenproblem zu machen:

In Zeiträumen mit hohem Netzwerkdatenverkehr kann ein Miniporttreiber keinen hohen E/A-Durchsatz beibehalten, wenn er für auf Geräte zugängliche Datenpuffer wenig Speicherplatz aufweist.
Beispielsweise könnte der Miniporttreiber angeben, dass Puffer im gemeinsam genutzten Speicher schneller empfangen werden, als solche Puffer von gebundenen Protokolltreibern zurückgegeben werden, wenn eine Flut von Empfangen in eine NIC kommt. Wenn der gesamte freigegebene Speicherplatz von ausstehenden Empfangspuffern genutzt wird, muss der Miniporttreiber möglicherweise die Empfangsunterbrechungen in einer NIC deaktivieren, bis er über einen freigegebenen Speicherplatz verfügt, der für den Empfang von Puffern verfügbar ist.
Andererseits macht das Aufrufen NdisMAllocateSharedMemory mit einer Length ausgewählt, um eine maximale Übertragungsnachfrage zu antizipieren, das Image des Fahrers zu vergrößern und seine Ressourcennutzung ziemlich unwirtschaftlich zu machen, außer bei seltenen Zeiträumen sehr hoher E/A-Nachfrage. Darüber hinaus geben NdisMAllocateSharedMemory- dem Treiber möglicherweise keinen so großen Block, wenn nicht genügend Systemspeicher verfügbar ist, sodass der Treiber die Initialisierung fehlschlägt.

Ein Miniporttreiber, der einen MiniportSharedMemoryAllocateComplete Funktion hat deutlich mehr Flexibilität bei der Auflösung der vorherigen Leistung im Vergleich zu Größen-Dilemma. MiniportInitializeEx- sollte nur genügend gemeinsam genutzter Arbeitsspeicher mit NdisMAllocateSharedMemory- für einen moderaten Bedarf an Netzwerkübertragungsvorgängen über die NIC zuweisen, wenn der Treiber über eine MiniportSharedMemoryAllocateComplete--Funktion verfügt. Ein solcher Miniporttreiber kann anrufen NdisMAllocateSharedMemoryAsyncEx dynamisch, um mehr gemeinsam genutzten Speicher in Zeiträumen mit schwererem Übertragungsbedarf für eine NIC zuzuweisen. Wenn die hohe Nachfrage nach Übertragungen abfällt, ruft ein solcher Treiber NdisMFreeSharedMemory auf, um den zugewiesenen zusätzlichen Speicher freizugeben. Beachten Sie, dass nur Busmaster-DMA-NICs NdisMAllocateSharedMemoryAsyncEx aufrufen und MiniportSharedMemoryAllocateCompleteexportieren können. Diese Funktionalität wird für untergeordnete DMA-NICs nicht unterstützt.

NdisMAllocateSharedMemory und NdisMAllocateSharedMemoryAsyncEx sind die einzigen NdisXxx Funktionen, die aufgerufen werden können, um Hostspeicher zuzuweisen, der zwischen dem Treiber gemeinsam genutzt wird, und einer NIC, die die entsprechenden logischen Adressen verwendet.

Ein Miniporttreiber sollte die Puffer ausrichten, die er aus freigegebenem zwischengespeichertem Speicher an einer integralen Grenze der Hostdatencache-Linie zuweist, um zu verhindern, dass die Zwischenzeilen während des DMA getrennt werden. Zwischenspeicherzeilenumbruch kann zu Problemen mit der Datenintegrität im Treiber führen oder die E/A-Leistung des Treibers (und die System-E/A-Leistung) beeinträchtigen, da übermäßiges Leeren des Datencaches erforderlich ist, um die Datenintegrität aufrechtzuerhalten. MiniportInitializeEx- kann NdisMGetDmaAlignment- aufrufen, um die Ausrichtungsgrenze in der aktuellen Plattform für gerätegeschützte Puffer zu bestimmen, die der Treiber innerhalb eines zugewiesenen Bereichs gemeinsam genutzten Speichers eingerichtet.

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. Legen Sie keinen Grenzwert fest, der übermäßig hoch ist, da dies zu einem verschwendeten Verbrauch von gemeinsam genutztem Arbeitsspeicher führen kann, der die Systemleistung verringern könnte.

MiniportInitializeEx kann auch NdisSystemProcessorCount aufrufen, bevor NdisMAllocateSharedMemory- aufgerufen wird, wenn der Treiberschreiber entscheidet, einen größeren gemeinsam genutzten Speicherblock auf Multiprozessorcomputern zuzuweisen, wenn angenommen wird, dass jeder SMP-Computer ein Netzwerkserver mit höheren Netzwerkübertragungsanforderungen an die NIC ist als eine Arbeitsstation.

Wenn der Aufruf von NdisMAllocateSharedMemory fehlschlägt, kann MiniportInitializeEx- erneut eine kleinere Zuordnung anfordern. Wenn MiniportInitializeEx- jedoch nicht genügend gemeinsam genutzten Speicher für die NIC zuweisen kann, muss er alle Ressourcen freigeben, die sie bereits zugewiesen hat, und die Initialisierung fehlschlägt.

Wenn der Miniporttreiber anschließend angibt, dass er mit NdisMIndicateReceiveNetBufferLists, muss sie einige Anzahl von Pufferdeskriptoren aus dem Pufferpool zuordnen, die die Empfangspuffer der NIC im freigegebenen Speicherblock zuordnen.

Wenn der zugewiesene Speicher zwischengespeichert wird und daher bei Übertragungen geleert werden muss, muss der Miniporttreiber NdisAllocateMdl aufrufen, um einen NDIS_BUFFER-Typdeskriptor für den freigegebenen Speicherbereich zuzuweisen. Der Miniporttreiber muss KeFlushIoBuffers- mit diesem Pufferdeskriptor aufrufen, um eine solche Leerung durchzuführen.

Wenn ein Miniporttreiber aufruft NdisMAllocateSharedMemoryAsyncEx oder NdisMAllocateSharedMemorymuss es alle ausstehenden Zuordnungen mit einem oder mehreren Aufrufen von NdisMFreeSharedMemory freigeben, wenn eine NIC entfernt wird, d. h., wenn seine MiniportHaltEx Funktion aufgerufen 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)
Library	Ndis.lib
IRQL-	PASSIVE_LEVEL