NdisMAllocateNetBufferSGList-Funktion (ndis.h)

Artikel
02/26/2024

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.

Bus-master Miniporttreiber rufen die NdisMAllocateNetBufferSGList-Funktion auf, um eine Punkt-/Sammlungsliste für die Netzwerkdaten abzurufen, die einer NET_BUFFER-Struktur zugeordnet sind.

Syntax

NDIS_STATUS NdisMAllocateNetBufferSGList(
  [in]           NDIS_HANDLE NdisMiniportDmaHandle,
  [in]           PNET_BUFFER NetBuffer,
  [in]           PVOID       Context,
  [in]           ULONG       Flags,
  [in, optional] PVOID       ScatterGatherListBuffer,
  [in]           ULONG       ScatterGatherListBufferSize
);

Parameter

[in] NdisMiniportDmaHandle

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] NetBuffer

Ein Zeiger auf eine NET_BUFFER-Struktur. NdisMAllocateNetBufferSGList weist eine Punkt-/Gather-Liste für die Netzwerkdaten zu, die dieser NET_BUFFER-Struktur zugeordnet sind. Die Scatter/Gather-Liste wird aus den Daten generiert, die am Anfang der MDL beginnen, die am CurrentMdl-Element der zugeordneten NET_BUFFER_DATA-Struktur angegeben wird.

[in] Context

Ein Zeiger auf einen Kontextbereich, den der Aufrufer erstellt hat. HAL übergibt diesen Zeiger an MiniportProcessSGList , nachdem HAL die Scatter/Gather-Liste erstellt hat. Der Aufrufer kann diesen Kontextbereich für seine eigenen Zwecke verwenden.

[in] Flags

NDIS-Flags, die mit einem OR-Vorgang kombiniert werden können. Um alle Flags zu löschen, legen Sie dieses Element auf 0 (null) fest. Diese Funktion unterstützt das flag NDIS_SG_LIST_WRITE_TO_DEVICE, das; wenn festgelegt, gibt an, dass die Richtung der DMA-Übertragung vom NET_BUFFER zum Gerät erfolgt. Wenn NDIS_SG_LIST_WRITE_TO_DEVICE eindeutig ist, erfolgt die Übertragung vom Gerät. Miniporttreiber sollten dieses Flag auf dem Sendepfad festlegen, wenn der DMA-Vorgang Daten von einem NET_BUFFER an das Gerät überträgt. Miniporttreiber, die DMA-Vorgänge vom Gerät zu einem vorab zugewiesenen NET_BUFFER ausführen, z. B. Schornsteinabladungsfähige NICs während Empfangsvorgängen, sollten dieses Flag löschen.

[in, optional] ScatterGatherListBuffer

Wenn nicht NULL, gibt ScatterGatherListBuffer einen Zeiger auf den Speicher an, den der Aufrufer für die Scatter/Gather-Liste zuordnet. Wenn NULL, ordnet NDIS Speicher für die Punkt-/Sammlungsliste zu.

[in] ScatterGatherListBufferSize

Wenn der ScatterGatherListBuffer-Parameter nicht NULL ist, gibt ScatterGatherListBufferSize die Größe des Puffers an, der die Scatter/Gather-Liste enthält. Wenn diese Größe zu klein ist, ordnet NDIS Speicher für die Punkt-/Sammlungsliste zu. Wenn der ScatterGatherListBuffer-ParameterNULL ist, wird dieser Parameter nicht verwendet.

Rückgabewert

NdisMAllocateNetBufferSGList gibt eine der folgenden Rückgaben zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList hat erfolgreich die Scatter/Gather-Liste für die angegebene NET_BUFFER-Struktur erstellt.
NDIS_STATUS_RESOURCES	Fehler bei NdisMAllocateNetBufferSGList aufgrund unzureichender Ressourcen.

Hinweise

Ein NDIS-bus-master Miniporttreiber ruft NdisMAllocateNetBufferSGList über seine MiniportSendNetBufferLists-Funktion . Der Miniporttreiber ruft NdisMAllocateNetBufferSGList einmal für jede NET_BUFFER-Struktur auf, für die er eine Scatter-/Gather-Liste abrufen muss.

Wenn ein Miniporttreiber NdisMAllocateNetBufferSGList aufruft, ruft NDIS HAL auf, um die Scatter/Gather-Liste zu erstellen. Nachdem HAL die Scatter/Gather-Liste erstellt hat, ruft sie die MiniportProcessSGList-Funktion auf, die der Miniporttreiber durch Aufrufen von NdisMRegisterScatterGatherDma.

HAL kann MiniportProcessSGList vor oder nach der Rückgabe von NDIS aus NdisMAllocateNetBufferSGList aufrufen. Miniporttreiber dürfen erst versuchen, auf die Scatter/Gather-Liste zuzugreifen, nachdem HAL MiniportProcessSGList aufgerufen hat.

Um die Systemleistung zu verbessern, sollten Miniporttreiber Puffer für die Verwendung im ScatterGatherListBuffer-Parameter von NdisMAllocateNetBufferSGList vorab zuweisen. NDIS stellt die empfohlene Größe für die Puffer im ScatterGatherListSize-Member des DmaDescription-Parameters bereit, wenn der Miniporttreiber NdisMRegisterScatterGatherDma aufruft. Miniport-Treiber geben die Größe des Puffers im ScatterGatherListBufferSize-Parameter an, wenn sie NdisMAllocateNetBufferSGList aufrufen.

NDIS kann einen Puffer auch dann zuordnen, wenn der Miniporttreiber einen Puffer im ScatterGatherListBuffer-Parameter angibt. Dies kann passieren, wenn der angegebene Puffer zu klein ist, um die Punkt-/Sammlungsliste zu speichern. Daher dürfen Treiberautoren nicht davon ausgehen, dass der im ScatterGatherListBuffer-Parameter angegebene Puffer die Scatter/Gather-Liste enthält. HAL übergibt den richtigen Punkt-/Gather-Listenzeiger an die MiniportProcessSGList-Funktion des Miniport-Treibers .

Um die Systemleistung zu verbessern, wird die Scatter/Gather-Liste aus den Netzwerkdaten generiert, beginnend am Anfang der MDL, die am CurrentMdl-Member der zugeordneten NET_BUFFER_DATA-Struktur angegeben wird. Der Anfang der Netzwerkdaten in der SG-Liste wird vom Anfang der SG-Liste durch den Wert versetzt, der im CurrentMdlOffset-Element der zugeordneten NET_BUFFER_DATA-Struktur angegeben ist.

Miniport-Treiber müssen die NdisMFreeNetBufferSGList-Funktion aufrufen, um eine Punkt-/Sammlungsliste frei zu geben.

Anforderungen

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