Portieren von NDIS-Miniporttreibern zu NetAdapterCx

Auf dieser Seite wird beschrieben, wie Sie einen NDIS 6.x-Miniporttreiber in einen NetAdapterCx-Clienttreiber konvertieren.

Allgemeine Informationen zu WDF finden Sie im WDF-Treiberentwicklungshandbuch.

Kompilierungseinstellungen

Öffnen Sie Ihr vorhandenes NDIS-Miniporttreiberprojekt in Visual Studio, und führen Sie die folgenden Schritte aus, um es in ein KMDF-Projekt zu konvertieren.

1. Navigieren Sie zunächst zu Configuration Properties-Driver> Einstellungen-Driver Model, und vergewissern Sie sich, dass der Typ des Treibers auf KMDF festgelegt ist, und dass die KMDF-Version Haupt- und KMDF-Version> Nebenversion leer sind.

2. Öffnen Sie in den Projekteigenschaften treiber Einstellungen-Netzwerkadaptertreiber>, und legen Sie "Link zur Netzwerkadapterklassenerweiterung" auf "Ja" fest.

   • Wenn Ihr konvertierter Treiber weiterhin NDIS-APIs aufruft, fahren Sie mit der Verknüpfung fort ndis.lib.

3. Entfernen Sie NDIS-Präprozessormakros, z. B NDIS650_MINIPORT=1. .

4. Fügen Sie die folgenden Kopfzeilen zu jeder Quelldatei (oder zu Ihrem allgemeinen/vorkompilierten Header) hinzu:

   #include <ntddk.h>
   #include <wdf.h>
   #include <netadaptercx.h>
   

5. Fügen Sie Standard-WDF-Dekorationen zu Ihrem INF hinzu:

   [Yourdriver.Wdf]
   KmdfService = Yourdriverservice, Yourdriver.wdfsect
   
   [Yourdriver.wdfsect]
   KmdfLibraryVersion = <insert here>
   

6. Fügen Sie dem NT-Abschnitt Ihrer INF neue erforderliche Netzwerk-Schlüsselwort (keyword) hinzu:

   • *If Verbinden orPresent

   • *Verbinden ionType

   • *DirectionType

   • *AccessType

   • *HardwareLoopback

     Weitere Informationen zu diesen Schlüsselwort (keyword) und einem Beispiel finden Sie unter INF-Dateien für NetAdapterCx-Clienttreiber.

Treiberinitialisierung

Entfernen Sie den Aufruf von NdisMRegisterMiniportDriver aus DriverEntry, und fügen Sie Folgendes hinzu:

WDF_DRIVER_CONFIG_INIT(&config, EvtDriverDeviceAdd);
status = WdfDriverCreate(. . . );
if (!NT_SUCCESS(status)) {
  return status;
}

Wenn sie festgelegt ist, entfernen Sie das WdfDriverInitNoDispatchOverride-Flag aus dem Aufruf von WdfDriverCreate.

DriverUnload ist eine optionale Routine für einen WDF-Netzwerkclienttreiber, sodass Sie es bei Bedarf entfernen können. Rufen Sie NdisMDeregisterMiniportDriver nicht von DriverUnload auf.

Geräteinitialisierung

Als Nächstes verteilen Sie Code von MiniportInitializeEx in die entsprechenden WDF-Ereignisrückrufhandler, von denen mehrere optional sind. Ausführliche Informationen zur Rückrufsequenz finden Sie unter Power-Up Sequence für einen WDF-Clienttreiber für den Netzwerkadapter.

Sie rufen die Methoden auf, die NdisMSetMiniportAttributes entsprechen, wenn Sie den Netzadapter starten, aber bevor Sie NetAdapterStart aufrufen. Anstatt jedoch eine Routine mit einer generischen NDIS_MINIPORT_ADAPTER_ATTRIBUTES-Struktur aufzurufen, ruft der Clienttreiber verschiedene Funktionen auf, um verschiedene Arten von Funktionen festzulegen.

Informationen zu den Rückrufen, die Sie bereitstellen müssen, und wann ein Netzadapter gestartet werden soll, finden Sie unter Geräte- und Adapterinitialisierung.

Lesen der Konfiguration aus der Registrierung

Ersetzen Sie als Nächstes Aufrufe an NdisOpenConfigurationEx und verwandte Funktionen durch die NetConfiguration* Methoden. Die NetConfiguration* Methoden ähneln den Ndis*Configuration* Funktionen, und Sie müssen den Code nicht neu strukturieren.

Weitere Informationen finden Sie unter Zugreifen auf Konfigurationsinformationen.

Empfangen von E/A-Steuercodes (IOCTLs) aus dem Benutzermodus

Lesen Sie diesen Abschnitt, wenn Ihr NDIS-Treiber NdisRegisterDeviceEx aufruft, eine Routine, die zum Erstellen eines Steuerelementgeräteobjekts (CONTROL Device Object, CDO) zum Empfangen von IOCTLs aus dem Benutzermodus verwendet wird.

Hier sind zwei Möglichkeiten, dies in Ihrem WDF-Netzwerkclienttreiber zu tun.

Der einfachste Port besteht darin, ein Steuerelementgeräteobjekt durch Aufrufen von WdfControlDeviceInitAllocate aus dem EVT_WDF_DRIVER_DEVICE_ADD Rückruf des Clients zu erstellen. Weitere Informationen finden Sie unter Verwenden von Steuerelementgeräteobjekten.

Die empfohlene Lösung besteht jedoch darin, eine Geräteschnittstelle zu erstellen, wie unter Verwendung von Geräteschnittstellen beschrieben.

Beenden der Geräteinitialisierung

An diesem Punkt in EVT_WDF_DRIVER_DEVICE_ADD können Sie alles tun, was Sie sonst noch tun möchten, um Ihr Gerät zu initialisieren, z. B. Unterbrechungen zuzuweisen.

Behandeln von Leistungszustandsänderungsbenachrichtigungen

Ein WDF-Clienttreiber empfängt keine OID_PNP_SET_POWER für Energiezustandsänderungen.

Stattdessen registriert ein WDF-Client optionale Rückruffunktionen, um Änderungsbenachrichtigungen für den Energiezustand zu erhalten. Eine Übersicht finden Sie unter Unterstützen von PnP und Power Management in Funktionstreibern.

Normalerweise wechselt der Code in Ihrem OID_PNP_SET_POWER-Handler zu EVT_WDF_DEVICE_D0_EXIT und EVT_WDF_DEVICE_D0_ENTRY.

Da sich der WDF-Energiezustandscomputer geringfügig unterscheidet, müssen Sie möglicherweise kleinere Änderungen am Code vornehmen.

In der MiniportInitializeEx-Rückruffunktion führt ein NDIS-Miniporttreiber einmalige Initialisierungsaufgaben aus und arbeitet auch daran, das Gerät in den D0-Zustand zu bringen. Anschließend wird die Arbeit wiederholt, um im OID_PNP_SET_POWER-Handler zu D0 zu wechseln.

Im Gegensatz dazu führt ein WDF-Client einmalige Initialisierungsaufgaben in Ereignisrückrufen vor EVT_WDF_DEVICE_D0_ENTRY durch, während der sich das Gerät in einem Energiesparzustand befindet. Dann funktioniert die Arbeit, um in EVT_WDF_DEVICE_D0_ENTRY nach D0 zu gehen.

Um zusammenzufassen, platzieren Sie in WDF den Code "Gehe zu D0" an einer Stelle statt an zwei Stellen.

Ausführliche Informationen zur Rückrufsequenz finden Sie unter Power-Up-Sequenz für einen NetAdapterCx-Clienttreiber.

Abfragen und Festlegen von Power Management-Funktionen

Ebenso empfängt ein WDF-Clienttreiber keine OID_PM_PARAMETERS , um Hardwarefunktionen für die Energieverwaltung des Netzwerkadapters abzufragen oder festzulegen.

Stattdessen fragt der Treiber die erforderliche Wake-on-LAN-Konfiguration (WoL) vom NETPOWERSETTINGS-Objekt ab. Weitere Informationen finden Sie unter Konfigurieren der Energieverwaltung.

Die tatsächlichen Flags, die Sie zurückholen, verfügen über dieselbe Semantik wie für einen NDIS 6-Miniport, sodass Sie keine tiefen Änderungen an der Logik vornehmen müssen. Der Standard Unterschied besteht darin, dass Sie diese Flags jetzt während der Power-Down-Sequenz abfragen können. Siehe Power-Down-Sequenz für einen NetAdapterCx-Clienttreiber.

Nachdem Sie diesen Code verschoben haben, können Sie die OID-Handler für OID_PNP_SET_POWER und OID_PM_PARAMETERS löschen.

Da das NetAdapter-Framework Ihr Gerät bei D0 hält, während der Host die Netzwerkschnittstelle verwendet, implementiert der Client in der Regel keine Energielogik. Das Standardmäßige Netzadapter-Leistungsverhalten ist ausreichend.

Datenpfad

Das Datenpfadprogrammierungsmodell hat sich erheblich geändert. Hier sind einige wichtige Unterschiede:

• Im NetAdapter-Modell ist der Netzwerkdatenverkehr nicht mehr pro Adapter, wie in NDIS, sondern pro WDF-Warteschlange. Siehe Erstellen von E/A-Warteschlangen.
• Anstelle von NET_BUFFER_LIST und NET_BUFFER Pools führt NetAdapterCx einen Ringpuffer ein, der aus Netpaketen besteht, die NDIS wie folgt zugeordnet sind:
  • Ein NET_PACKET ähnelt einem NET_BUFFER_LIST + NET_BUFFER.
  • Ein NET_PACKET_FRAGMENT ähnelt einer Speicherdeskriptorliste (MDL). Jeder NET_PACKET hat eine oder mehrere davon.
  • Ausführliche Informationen zu den Ersetzungsstrukturen und deren Verwendung finden Sie unter Paketdeskriptoren und Erweiterungen.
• In NDIS 6.x muss der Miniport die Start- und Pausensemantik behandeln. Im NetAdapterCx-Modell ist dies nicht mehr der Fall.
• Der EVT_RXQUEUE_ADVANCE Rückruf ähnelt MINIPORT_RETURN_NET_BUFFER_LISTS in NDIS 6.x.
• Der EVT_TXQUEUE_ADVANCE Rückruf ähnelt MINIPORT_SEND_NET_BUFFER_LISTS in NDIS 6.x.

Entfernen von Geräten

Das Entfernen eines WDF-NIC-Treibers ist identisch mit jedem anderen WDF-Gerätetreiber, ohne dass eine netzwerkspezifische Verarbeitung erforderlich ist. Der Netzwerkdatenpfad wird zuerst beendet, gefolgt vom WDF-Gerät. Informationen zum Herunterfahren von WDF finden Sie unter A User Unplugs a Device.

Ihr MiniportHaltEx-Handler wird wahrscheinlich zwischen EVT_WDF_DEVICE_D0_EXIT und EVT_WDF_DEVICE_RELEASE_HARDWARE verteilt.

Der WDF-Client muss weder netAdapter noch eine der von ihr erstellten Datenpfadwarteschlangen löschen. WDF löscht diese Objekte automatisch.

Sie können MiniportShutdownEx, MiniportResetEx und MiniportCheckForHangEx löschen. Diese Rückrufe werden nicht mehr unterstützt.

NDIS-WDF-Funktionsäquivalente

Die meisten NdisXxx Funktionen können durch eine WDF-Entsprechung ersetzt werden. Im Allgemeinen sollten Sie feststellen, dass Sie sehr wenig Funktionen benötigen, aus NDIS.SYSdenen importiert wird.

Eine Liste der Funktionsentsprechungen finden Sie unter NDIS-WDF-Funktionsentsprechungen.

Debuggen

Siehe Debuggen eines NetAdapterCx-Clienttreibers.

Die Debuggererweiterung !ndiskd.netadapter zeigt ähnliche Ergebnisse wie für einen NDIS 6-Treiber.ndiskd.miniport .

Zusammenfassung

Mit den Schritten in diesem Thema sollten Sie über einen funktionierenden Treiber verfügen, der Ihr Gerät startet und beendet.

Hinweis: NetAdapterCx unterstützt derzeit keinen iSCSI-Start.