NdisMAllocateNetBufferSGList-Funktion (ndis.h)
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 |
|---|---|
|
NdisMAllocateNetBufferSGList hat erfolgreich die Scatter/Gather-Liste für die angegebene NET_BUFFER-Struktur erstellt. |
|
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) |