NdisMRegisterScatterGatherDma-Funktion (ndis.h)

Artikel
08/07/2023

Achtung

Für ARM- und ARM64-Prozessoren empfehlen wir dringend, dass NDIS-Treiberschreiber 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 NdisMRegisterScatterGatherDma-Funktion von MiniportInitializeEx auf, um einen Scatter/Gather-DMA-Kanal zu initialisieren.

Syntax

NDIS_STATUS NdisMRegisterScatterGatherDma(
  [in]      NDIS_HANDLE              MiniportAdapterHandle,
  [in, out] PNDIS_SG_DMA_DESCRIPTION DmaDescription,
  [out]     PNDIS_HANDLE             NdisMiniportDmaHandle
);

Parameter

[in] MiniportAdapterHandle

Das Miniporthandle, das NDIS an MiniportInitializeEx übergeben hat.

[in, out] DmaDescription

Ein Zeiger auf eine NDIS_SG_DMA_DESCRIPTION-Struktur. Diese Struktur beschreibt die Scatter/Gather-DMA-Eigenschaften des Miniporttreibers. Die Struktur wird wie folgt definiert:

typedef struct _NDIS_SG_DMA_DESCRIPTION {
  NDIS_OBJECT_HEADER  Header;
  ULONG  Flags;
  ULONG  MaximumPhysicalMapping;
  MINIPORT_PROCESS_SG_LIST_HANDLER  ProcessSGListHandler;
  MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE_HANDLER  SharedMemAllocateCompleteHandler;
  ULONG  ScatterGatherListSize;
} NDIS_SG_DMA_DESCRIPTION, *PNDIS_SG_DMA_DESCRIPTION;

Diese Struktur enthält die folgenden Member:

Die NDIS_OBJECT_HEADER-Struktur für die NDIS_SG_DMA_DESCRIPTION-Struktur. Legen Sie das Typelement der Struktur, die Header angibt, auf NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, das Revisionselement auf NDIS_SG_DMA_DESCRIPTION_REVISION_1 und das Size-Element auf NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1 fest.

Flags

Eine Reihe von Bitflags, die Scatter-/Gather-Merkmale definieren. Legen Sie dieses Element auf das bitweise OR aller erforderlichen Flags fest.

Das flag NDIS_SG_DMA_64_BIT_ADDRESS gibt an, dass die NIC die 64-Bit-Adressierung für DMA-Vorgänge verwenden kann. Andernfalls verwendet die NIC die 32-Bit-Adressierung.

Legen Sie diesen Member auf 0 fest, wenn keine 64-Bit-Adressierung erforderlich ist.

MaximumPhysicalMapping

Die maximale Anzahl von Bytes, die die NIC in einem einzelnen DMA-Vorgang übertragen kann. NDIS stellt diesen Wert für die Hardware abstraction Layer (HAL) bereit, wenn ein DMA-Kanal zugewiesen wird, und HAL verwendet diesen Wert, um die maximale Anzahl von Kartenregistern zu bestimmen, die für die NIC reserviert werden sollen.

ProcessSGListHandler

Die MiniportProcessSGList-Funktion , die NDIS aufruft, wenn hal mit der Erstellung der Scatter/Gather-Liste fertig ist.

SharedMemAllocateCompleteHandler

The MiniportSharedMemoryAllocateComplete-Funktion für Miniporttreiber, die aufrufen NdisMAllocateSharedMemoryAsyncEx. Dieses Feld ist optional und sollte NULL sein, wenn der Miniporttreiber NdisMAllocateSharedMemoryAsyncEx nicht aufruft.

ScatterGatherListSize

Die Größe des Arbeitsspeichers in Bytes, der für eine Scatter/Gather-Liste erforderlich ist. NDIS legt diesen Wert fest, bevor er von NdisMRegisterScatterGatherDma zurückgibt. Miniport-Treiber sollten diese Größe verwenden, um Arbeitsspeicher für jede Punkt-/Sammlungsliste vorab zu verwenden.

[out] NdisMiniportDmaHandle

Ein Zeiger auf eine Variable, die der Aufrufer bereitstellt und die NDIS mit einem Handle füllt. Das Handle identifiziert einen Kontextbereich, den NDIS zum Verwalten dieser DMA-Ressource verwendet. Der Miniporttreiber übergibt dieses Handle an NDIS in nachfolgenden Aufrufen von NDIS, die diese DMA-Ressource einbeziehen.

Rückgabewert

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

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	NdisMRegisterScatterGatherDma hat Ressourcen erfolgreich für bus-master DMA-Vorgänge zugewiesen.
NDIS_STATUS_RESOURCES	Fehler bei NdisMRegisterScatterGatherDma aufgrund unzureichender Ressourcen.
NDIS_STATUS_NOT_SUPPORTED	Fehler bei NdisMRegisterScatterGatherDma, weil der Miniport nicht angegeben hat, dass er NDIS 6.0 oder höhere Versionen unterstützt, oder weil der Miniporttreiber nicht angegeben hat, dass seine NIC ein Bus-master DMA-Gerät ist. Ein Miniporttreiber gibt seine NDIS-Version an, wenn er aufruft NdisMRegisterMiniportDriver. Ein Miniporttreiber gibt an, dass er bus-master DMA-Geräte unterstützt, wenn er aufruft. NdisMSetMiniportAttributes.
NDIS_STATUS_BAD_VERSION	Die aktuelle Version von NDIS unterstützt nicht die Version, die im Revision-Member der Headerstruktur von DmaDescription angegeben ist.

Hinweise

Ein NDIS Bus-master Miniporttreiber ruft NdisMRegisterScatterGatherDma in seiner MiniportInitializeEx-Funktion auf, um Ressourcen für DMA-Vorgänge zu initialisieren. Der DmaDescription-Parameter , den der Miniporttreiber an NdisMRegisterScatterGatherDma übergibt, enthält die Informationen, die NDIS zum Initialisieren der scatter/gather DMA-Ressourcen verwendet. Nachdem NdisMRegisterScatterGatherDma zurückgegeben wurde, enthält das ScatterGatherListSize-Element von DmaDescription eine Puffergröße, die ausreichen sollte, um eine Scatter/Gather-Liste zu speichern. Miniport-Treiber sollten diese Größe verwenden, um den Speicher für Punkt-/Sammlungslisten vorab zuzuspeichern.

Das ProcessSGListHandler-Element im DmaDescription-Parameter definiert den Einstiegspunkt im Miniporttreiber für die MiniportProcessSGList-Funktion . Wenn ein Miniporttreiber aufruft NdisMAllocateNetBufferSGList, NDIS ruft HAL auf, um die Scatter/Gather-Liste für den Miniporttreiber bereitzustellen. HAL ruft MiniportProcessSGList auf, nachdem HAL die Erstellung der Scatter/Gather-Liste abgeschlossen hat. NDIS kann MiniportProcessSGList außerhalb des Kontexts des Aufrufs von NdisMAllocateNetBufferSGList aufrufen.

NdisMRegisterScatterGatherDma gibt einen Zeiger auf einen Kontextbereich zurück, der für den Miniporttreiber undurchsichtig ist. Der Miniporttreiber muss dieses Handle bei nachfolgenden Aufrufen von NDIS-DMA-Funktionen scatter/gather verwenden.

Bus-master Miniporttreiber anrufen NdisMAllocateSharedMemoryAsyncEx zum dynamischen Zuweisen des freigegebenen Arbeitsspeichers für Datenübertragungsvorgänge. Dieser Aufruf ist erforderlich, wenn ein hoher Netzwerkdatenverkehr dazu führt, dass der Miniporttreiber auf dem freigegebenen Speicherplatz, den der Treiber während der Initialisierung zugewiesen hat, knapp wird. Wenn NdisMAllocateSharedMemoryAsyncEx NDIS_STATUS_PENDING zurückgibt, ruft NDIS die MiniportSharedMemoryAllocateComplete-Funktion , um den Vorgang zu einem späteren Zeitpunkt abzuschließen. Miniport-Treiber geben den Einstiegspunkt für die MiniportSharedMemoryAllocateComplete-Funktion im SharedMemAllocateCompleteHandler-Element des DmaDescription-Parameters an.

Miniporttreiber rufen die NdisMDeregisterScatterGatherDma-Funktion , um die DMA-Ressourcen zu beheben, die NdisMRegisterScatterGatherDma zugewiesen hat .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.0 und höher.
Zielplattform	Universell
Header	ndis.h (einschließlich Ndis.h)
Bibliothek	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	Init_RegisterSG(ndis), Irql_Gather_DMA_Function(ndis)