NdisMAllocateNetBufferSGList-Funktion (ndis.h)
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.
Busmaster-Miniporttreiber rufen die NdisMAllocateNetBufferSGList Funktion auf, um eine Punkt-/Sammelliste 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 zu einem Kontextbereich, den NDIS zum Verwalten einer DMA-Ressource verwendet. Der Aufrufer hat dieses Handle durch Aufrufen des NdisMRegisterScatterGatherDma Funktion.
[in] NetBuffer
Ein Zeiger auf eine NET_BUFFER Struktur. NdisMAllocateNetBufferSGList eine Punkt-/Sammelliste für die Netzwerkdaten zuordnet, die dieser NET_BUFFER Struktur zugeordnet sind. Die Punkt-/Gather-Liste wird aus den Daten generiert, die am Anfang der MDL beginnen, die am CurrentMdl Member 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 Punkt/Gather-Liste erstellt hat. Der Aufrufer kann diesen Kontextbereich für eigene 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 Null fest. Diese Funktion unterstützt die NDIS_SG_LIST_WRITE_TO_DEVICE Kennzeichnung; wenn festgelegt, gibt die Richtung der DMA-Übertragung vom NET_BUFFER zum Gerät an. Wenn NDIS_SG_LIST_WRITE_TO_DEVICE klar ist, erfolgt die Übertragung vom Gerät. Miniport-Treiber sollten dieses Kennzeichen auf dem Sendepfad festlegen, wenn DMA-Vorgang Daten von einem NET_BUFFER an das Gerät überträgt. Miniporttreiber, die DMA-Vorgänge vom Gerät zu einer vorab zugeordneten NET_BUFFER ausführen, z. B. Schornstein-Offload-fähige NICs während des Empfangsvorgangs, sollten diese Kennzeichnung löschen.
[in, optional] ScatterGatherListBuffer
Wenn nicht NULL-, gibt ScatterGatherListBuffer- einen Zeiger an, den der Aufrufer zur Aufbewahrung der Punkt/Gather-Liste zuweist. Wenn NULL-, weist NDIS Speicher für die Punkt/Gather-Liste zu.
[in] ScatterGatherListBufferSize
Wenn der ScatterGatherListBuffer Parameter nicht NULL-ist, gibt ScatterGatherListBufferSize die Größe des Puffers an, der die Punkt/Gather-Liste enthält. Wenn diese Größe zu klein ist, weist NDIS Speicher für die Punkt/Gather-Liste zu. Wenn der ScatterGatherListBuffer Parameter NULL-ist, wird dieser Parameter nicht verwendet.
Rückgabewert
NdisMAllocateNetBufferSGList gibt eine der folgenden Werte zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
NdisMAllocateNetBufferSGList die Punkt-/Gather-Liste für die angegebene NET_BUFFER Struktur erfolgreich erstellt. |
|
NdisMAllocateNetBufferSGList aufgrund unzureichender Ressourcen fehlgeschlagen. |
Bemerkungen
Ein NDIS-Bus-Master-Miniporttreiber ruft NdisMAllocateNetBufferSGList von seinem MiniportSendNetBufferLists Funktion. Der Miniporttreiber ruft NdisMAllocateNetBufferSGList einmal für jede NET_BUFFER Struktur auf, für die sie eine Punkt/Gather-Liste abrufen muss.
Wenn ein Miniporttreiber NdisMAllocateNetBufferSGListaufruft, ruft NDIS HAL auf, um die Punkt/Gather-Liste zu erstellen. Nachdem HAL die Punkt/Gather-Liste erstellt hat, ruft sie die MiniportProcessSGList Funktion auf, die der miniport-Treiber durch Aufrufen registriert hat. NdisMRegisterScatterGatherDma.
HAL kann MiniportProcessSGList- vor oder nach der Rückgabe von NDIS aus NdisMAllocateNetBufferSGListaufrufen. Miniport-Treiber dürfen erst versuchen, auf die Punkt/Gather-Liste zuzugreifen, nachdem HAL-Aufrufe MiniportProcessSGList.
Um die Systemleistung zu verbessern, sollten Miniporttreiber Puffer für die Verwendung im ScatterGatherListBuffer Parameter von NdisMAllocateNetBufferSGListvorzuweisen. NDIS stellt die empfohlene Größe für die Puffer im ScatterGatherListSize Member des DmaDescription Parameter bereit, wenn der Miniporttreiber NdisMRegisterScatterGatherDmaaufruft. Miniport-Treiber geben die Größe des Puffers im ScatterGatherListBufferSize Parameter an, wenn sie NdisMAllocateNetBufferSGListaufrufen.
NDIS kann einen Puffer zuordnen, auch wenn der Miniporttreiber einen Puffer im ScatterGatherListBuffer Parameter angibt. Dies kann passieren, wenn der angegebene Puffer zu klein ist, um die Punkt/Gather-Liste zu halten. Daher dürfen Treiberautoren nicht davon ausgehen, dass der im ScatterGatherListBuffer Parameter angegebene Puffer die Punkt/Gather-Liste enthält. HAL übergibt den richtigen Punkt/Gather-Listenzeiger an die MiniportProcessSGList-Funktion des Miniporttreibers.
Zur Verbesserung der Systemleistung wird die Punkt-/Gather-Liste aus den Netzwerkdaten generiert, beginnend am Anfang der MDL, die am CurrentMdl Member der zugeordneten NET_BUFFER_DATA Struktur angegeben ist. Der Anfang der Netzwerkdaten in der SG-Liste wird vom Anfang der SG-Liste um den wert versetzt, der im CurrentMdlOffset Member der zugeordneten NET_BUFFER_DATA Struktur angegeben ist.
Miniport-Treiber müssen die NdisMFreeNetBufferSGList Funktion aufrufen, um eine Punkt/Sammelliste freizuschalten.
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- | DISPATCH_LEVEL |
| DDI-Complianceregeln | Irql_Gather_DMA_Function(ndis) |