Portieren eines Treibers von UMDF 1 zu UMDF 2
In diesem Thema wird beschrieben, wie Sie einen Umdf 1-Treiber (User-Mode Driver Framework) zu UMDF 2 portieren. Sie können mit einem UMDF 1-Treiber beginnen, der Sources/Dirs-Dateien verwendet (kein Visual Studio-Projekt), oder Sie können einen UMDF 1-Treiber konvertieren, der in einem Visual Studio-Projekt enthalten ist. Das Ergebnis ist ein UMDF 2-Treiberprojekt in Visual Studio. UMDF 2-Treiber werden sowohl auf Windows 10 für Desktopeditionen (Home, Pro, Enterprise und Education) als auch auf Windows 10 Mobile ausgeführt.
Das Echo-Treiberbeispiel ist ein Beispiel für einen Treiber, der von UMDF 1 zu UMDF 2 portiert wurde.
Erste Schritte
Öffnen Sie zunächst ein neues Treiberprojekt in Visual Studio. Wählen Sie die Vorlage Visual C++->Windows Driver-WDF-User>> Mode Driver (UMDF 2) aus. Visual Studio öffnet eine teilweise aufgefüllte Vorlage, die Stubs für die Rückruffunktionen enthält, die Ihr Treiber implementieren muss. Dieses neue Treiberprojekt bildet die Grundlage Ihres UMDF 2-Treibers. Verwenden Sie das UMDF 2 Echo-Beispiel als Leitfaden für den Codetyp, den Sie einführen sollten.
Überprüfen Sie als Nächstes Den vorhandenen UMDF 1-Treibercode, und ermitteln Sie Objektzuordnungen. Jedes COM-Objekt in UMDF 1 verfügt über ein entsprechendes WDF-Objekt in UMDF 2. Beispielsweise wird die IWDFDevice-Schnittstelle dem WDF-Geräteobjekt zugeordnet, das durch ein WDFDEVICE-Handle dargestellt wird. Fast alle vom Framework bereitgestellten Schnittstellenmethoden in UMDF 1 verfügen über entsprechende Methoden in UMDF 2. Beispielsweise wird IWDFDevice::GetDefaultIoQueueWdfDeviceGetDefaultQueue zugeordnet.
Ebenso verfügen vom Treiber bereitgestellte Rückruffunktionen in den beiden Versionen über Entsprechungen. In UMDF 1 lautet die Namenskonvention für vom Treiber bereitgestellte Schnittstellen (mit Ausnahme von IDriverEntry) IObjectCallbackXxx, während in UMDF 2 die Namenskonvention für vom Treiber bereitgestellte Routinen EvtObjectXxx lautet. Die IDriverEntry::OnDeviceAdd-Rückrufmethode wird beispielsweise EvtDriverDeviceAdd zugeordnet.
Ihr Treiber implementiert Rückruffunktionen sowohl in UMDF 1 als auch in 2, aber die Art und Weise, wie der Treiber Zeiger auf seine Rückrufe bereitstellt, unterscheidet sich. In UMDF 1 implementiert der Treiber Rückrufmethoden als Member der vom Treiber bereitgestellten Schnittstellen. Der Treiber registriert diese Schnittstellen beim Framework, wenn framework-Objekte erstellt werden, z. B. durch Aufrufen von IWDFDriver::CreateDevice.
In UMDF 2 stellt der Treiber Zeiger auf vom Treiber bereitgestellte Rückruffunktionen in Konfigurationsstrukturen wie WDF_DRIVER_CONFIG und WDF_IO_QUEUE_CONFIG bereit.
Verwalten der Objektlebensdauer
Treiber, die UMDF 1 verwenden, müssen die Verweiszählung implementieren, um zu bestimmen, wann das Löschen von Objekten sicher ist. Da das Framework Objektverweise im Namen des Treibers nachverfolgt, muss ein UMDF 2-Treiber keine Verweise zählen.
In UMDF 2 verfügt jedes Frameworkobjekt über ein übergeordnetes Standardobjekt. Wenn ein übergeordnetes Objekt gelöscht wird, löscht das Framework zugeordnete untergeordnete Objekte. Wenn Ihr Treiber eine Objekterstellungsmethode wie WdfDeviceCreate aufruft, kann er das übergeordnete Standardelement akzeptieren oder ein benutzerdefiniertes übergeordnetes Element in einer WDF_OBJECT_ATTRIBUTES-Struktur angeben. Eine Liste der Frameworkobjekte und deren übergeordnete Standardobjekte finden Sie unter Zusammenfassung der Frameworkobjekte.
Initialisierung des Treibers
Ein UMDF 1-Treiber implementiert die IDriverEntry-Schnittstelle . In der IDriverEntry::OnDeviceAdd-Rückrufmethode ist der Treiber in der Regel:
- Erstellt und initialisiert eine instance des Geräterückrufobjekts.
- Erstellt das neue Framework-Geräteobjekt, indem IWDFDriver::CreateDevice aufgerufen wird.
- Richtet die Warteschlangen des Geräts und die entsprechenden Rückrufobjekte ein.
- Erstellt eine instance einer Geräteschnittstellenklasse, indem IWDFDevice::CreateDeviceInterface aufgerufen wird.
Ein UMDF 2-Treiber implementiert DriverEntry und EvtDriverDeviceAdd. In der DriverEntry-Routine ruft ein UMDF 2-Treiber in der Regel WDF_DRIVER_CONFIG_INIT auf, um die WDF_DRIVER_CONFIG-Struktur des Treibers zu initialisieren. Anschließend wird diese Struktur an WdfDriverCreate übergeben.
In seiner EvtDriverDeviceAdd-Funktion kann der Treiber einige der folgenden Aktionen ausführen:
- Füllen Sie die WDFDEVICE_INIT-Struktur aus, die Informationen bereitstellt, die zum Erstellen des Geräteobjekts verwendet werden. Weitere Informationen zur Verwendung von WDFDEVICE_INIT finden Sie unter Erstellen eines Framework-Geräteobjekts.
- Richten Sie den Kontextbereich des Geräteobjekts ein. Informationen zum Zuweisen und Zugreifen auf Kontextraum für Frameworkobjekte finden Sie unter Framework Object Context Space.
- Erstellen Sie das Geräteobjekt.
- Geben Sie Anforderungshandler für das Geräteobjekt an.
- Erstellen sie E/A-Warteschlangen.
- Erstellen sie Geräteschnittstellen.
- Legen Sie die Richtlinie für den Leerlauf des Geräts und die Aktivierungseinstellungen fest, wenn das Geräteobjekt die Energierichtlinie besitzt.
- Erstellen Sie Interruptobjekte, wenn die Hardware Interrupts unterstützt.
Installieren des Treibers
Wenn Sie ein neues Treiberprojekt in Visual Studio erstellen, enthält das neue Projekt eine INX-Datei. Wenn Sie Ihren Treiber erstellen, kompiliert Visual Studio Ihre INX-Datei in eine INF-Datei, die als Teil eines Treiberpakets verwendet werden kann.
Während eine INF-Datei für einen UMDF 1-Treiber eine Treiberklassen-ID enthalten muss, ist in einer INF-Datei für einen UMDF 2-Treiber keine DriverCLSID erforderlich.
Auch wenn ein UMDF 1-Treiber in seiner INF-Datei auf den Co-Installer verweisen muss, ist in einer UMDF 2-INF-Datei kein Constallerverweis erforderlich. Obwohl ein Coinstallerverweis in einer INF-Datei für einen UMDF 2-Treiber angezeigt werden kann, ist kein Verweis erforderlich.
Speichern des Gerätekontexts
In UMDF 1 speichert der Treiber in der Regel den Gerätekontext in einem vom Treiber erstellten Rückrufobjekt, z. B. durch Angabe privater Member der Geräterückrufobjektklasse. Alternativ kann ein UMDF 1-Treiber die IWDFObject::AssignContext-Methode aufrufen, um den Kontext für ein Frameworkobjekt zu registrieren.
In UMDF 2 ordnet das Framework den Kontextbereich basierend auf der optionalen WDF_OBJECT_ATTRIBUTES-Struktur zu, die der Treiber beim Aufrufen einer Objekterstellungsmethode bereitstellt. Nach dem Aufrufen der Create-Methode eines Objekts kann ein Treiber WdfObjectAllocateContext mehrmals aufrufen, um einem bestimmten Objekt zusätzlichen Kontextbereich zuzuweisen. Die Schritte, die ein UMDF 2-Treiber verwenden sollte, um eine Kontextstruktur und eine Accessormethode zu definieren, finden Sie unter Framework Object Context Space.
Debuggen des Treibers
Zum Debuggen eines UMDF 2-Treibers verwenden Sie Erweiterungen in Wdfkd.dll anstelle von Wudfext.dll. Weitere Informationen zu Erweiterungen in Wudfext.dll finden Sie unter Zusammenfassung der Debuggererweiterungen in Wdfkd.dll.
In UMDF 2 können Sie auch zusätzliche Treiberdebugginginformationen über den Inflight Trace Recorder (IFR) abrufen, wie unter Using Inflight Trace Recorder in KMDF and UMDF 2 Drivers beschrieben. Außerdem können Sie den eigenen In-Flight-Recorder (IFR) des Frameworks verwenden. Weitere Informationen finden Sie unter Verwenden der Ereignisprotokollierung des Frameworks.