Schreiben Ihres ersten USB-Client-Treibers (KMDF)

In diesem Artikel verwenden Sie die USB Kernel-Mode Driver-Vorlage, die mit Microsoft Visual Studio geliefert wird, um einen einfachen Kernel-Mode Driver Framework (KMDF)-basierten Client-Treiber zu schreiben. Nachdem Sie den Client-Treiber erstellt und installiert haben, werden Sie den Client-Treiber im Geräte-Manager anzeigen und die Treiberausgabe in einem Debugger betrachten.

Eine Erklärung des von der Vorlage generierten Quellcodes finden Sie unter Verstehen des KMDF-Vorlagencodes für einen USB Client-Treiber.

Voraussetzungen

Für die Entwicklung, das Debuggen und die Installation eines Kernel-Mode-Treibers benötigen Sie zwei Computer:

• Einen Host-Computer, auf dem Windows 7 oder eine neuere Version des Windows-Betriebssystems ausgeführt wird. Der Host-Computer ist Ihre Entwicklungsumgebung, in der Sie Ihren Treiber schreiben und debuggen.
• Einen Zielcomputer, auf dem Windows Vista oder eine neuere Version von Windows ausgeführt wird. Auf dem Zielcomputer befindet sich der Kernel-Mode-Treiber, den Sie debuggen möchten.

Bevor Sie beginnen, sollten Sie sicherstellen, dass Sie die folgenden Voraussetzungen erfüllen:

Softwareanforderungen

• Ihr Host-Computer hostet Ihre Entwicklungsumgebung und verfügt über Visual Studio.
• Ihr Host-Computer verfügt über das neueste Windows Driver Kit (WDK). Das Kit enthält Header, Bibliotheken, Tools, Dokumentation und die Debugging-Tools, die zum Entwickeln, Erstellen und Debuggen eines KMDF-Treibers erforderlich sind. Die neueste Version des WDK finden Sie unter Download des Windows Driver Kit (WDK).
• Ihr Host-Computer verfügt über die neueste Version der Debugging Tools für Windows. Die neueste Version erhalten Sie über das WDK oder Sie können Die Debugging Tools für Windows herunterladen und installieren.
• Auf Ihrem Zielcomputer wird Windows Vista oder eine neuere Version von Windows ausgeführt.
• Ihr Host und Ihr Zielcomputer sind zum Debuggen des Kernels konfiguriert. Weitere Informationen finden Sie unter Einrichten einer Netzwerkverbindung in Visual Studio.

Hardwareanforderungen

Besorgen Sie sich ein USB-Gerät, für das Sie den Client-Treiber schreiben werden. In den meisten Fällen werden Ihnen ein USB-Gerät und dessen Hardwarespezifikation zur Verfügung gestellt. Die Spezifikation beschreibt die Fähigkeiten des Geräts und die unterstützten Herstellerbefehle. Verwenden Sie die Spezifikation, um die Funktionalität des USB-Treibers und die damit verbundenen Designentscheidungen zu bestimmen.

Wenn Sie neu in der USB-Treiberentwicklung sind, verwenden Sie das OSR USB FX2 Learning Kit, um die im WDK enthaltenen USB-Beispiele zu studieren. Sie können das Learning Kit über OSR Online beziehen. Es enthält das USB FX2-Gerät und alle erforderlichen Hardwarespezifikationen, um einen Client-Treiber zu implementieren.

Sie können auch ein Microsoft USB Test Tool (MUTT)-Gerät erhalten. MUTT-Hardware kann über JJG Technologies bezogen werden. Auf dem Gerät ist keine Firmware installiert. Um die Firmware zu installieren, laden Sie das MUTT-Softwarepaket von dieser Website herunter und führen Sie MUTTUtil.exe aus. Weitere Informationen finden Sie in der Dokumentation, die dem Paket beiliegt.

Empfohlene Literatur

• Konzepte für alle Entwickler*innen von Treibern
• Geräteknoten und Gerätestacks
• Einstieg mit Treibern unter Windows
• Kernel-Mode Treiber-Framework
• Entwicklung von Treibern mit Windows Driver Foundation, geschrieben von Penny Orwick und Guy Smith. Weitere Informationen finden Sie unter Entwickeln von Treibern mit WDF.

Schritt 1: Generieren des KMDF-Treibercodes mit Hilfe der Visual Studio USB-Treibervorlage

Direktiveen zum Generieren von KMDF-Treiber Code finden Sie unter Schreiben eines KMDF-Treibers auf der Grundlage einer Vorlage.

Für USB-spezifischen Code wählen Sie in Visual Studio die folgenden Optionen:

1. Geben Sie im Dialogfeld Neues Projekt im oberen Suchfeld USB. ein.
2. Wählen Sie im mittleren Fensterbereich Kernel Mode Driver, USB (KMDF).
3. Wählen Sie Weiter aus.
4. Geben Sie einen Projektnamen ein, wählen Sie einen Speicherort, und wählen Sie Erstellen.

Die folgenden Screenshots zeigen das Dialogfeld Neues Projekt für die Vorlage USB Kernel-Mode Driver.

Dieser Artikel geht davon aus, dass der Name des Visual Studio-Projekts „MyUSBDriver_“ lautet. Er enthält die folgenden Dateien:

Dateien	Beschreibung
Public.h	Bietet allgemeine Deklarationen, die vom Client-Treiber und den Benutzeranwendungen, die mit dem USB-Gerät kommunizieren, gemeinsam genutzt werden.
<Projektname>.inf	Enthält Informationen, die für die Installation des Client-Treibers auf dem Zielcomputer erforderlich sind.
Trace.h	Deklariert Tracing-Funktionen und Makros.
Driver.h; Driver.c	Deklariert und definiert Treiber-Einstiegspunkte und Callback-Routinen für Ereignisse.
Device.h; Device.c	Deklariert und definiert eine Ereignis-Callback-Routine für das Ereignis prepare-hardware.
Queue.h; Queue.c	Deklariert und definiert eine Ereignis-Callback-Routine für das Ereignis, das durch das Warteschlangen-Objekt des Frameworks ausgelöst wird.

Schritt 2: Ändern der INF-Datei, um Informationen über Ihr Gerät hinzuzufügen

Bevor Sie den Treiber erstellen, müssen Sie die INF-Datei der Vorlage mit Informationen über Ihr Gerät, insbesondere die Zeichenfolge der Hardware-ID, ändern.

Doppelklicken Sie im Lösungs-Explorer unter Treiberdateien auf die INF-Datei.

In der INF-Datei können Sie Informationen wie den Namen des Herstellers und des Anbieters, die Einrichtungsklasse des Geräts und so weiter angeben. Eine Information, die Sie unbedingt angeben müssen, ist die Hardware-Kennung Ihres Geräts.

So geben Sie die Zeichenfolge für die Hardware-ID an:

1. Schließen Sie Ihr USB-Gerät an Ihren Host-Computer an und lassen Sie Windows das Gerät auflisten.

2. Öffnen Sie den Geräte-Manager und öffnen Sie die Eigenschaften für Ihr Gerät.

3. Wählen Sie auf der Registerkarte Details unter Eigenschaft die Option Hardware-Identifikation.

   Die Hardware-ID des Geräts wird in dem Listenfeld angezeigt. Halten Sie die Maustaste gedrückt (oder klicken Sie mit der rechten Maustaste) und kopieren Sie die Zeichenfolge der Hardware-ID.

4. Ersetzen Sie USB\VID_vvvv&PID_pppp in der folgenden Zeile durch Ihre Zeichenfolge für die Hardware-ID.

   [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

Schritt 3: Erstellen des Codes für den USB Client-Treiber

So erstellen Sie Ihren Treiber:

1. Öffnen Sie das Treiberprojekt oder die Lösung in Visual Studio
2. Halten Sie die Lösung im Lösungs-Explorer gedrückt (oder klicken Sie mit der rechten Maustaste) und wählen Sie Configuration Manager.
3. Wählen Sie im Configuration Manager die Aktive Projektmappenkonfiguration (z. B. Debug oder Release) und die Aktive Projektmappenplattform (z. B. Win32), die dem Typ des Builds entspricht, an dem Sie interessiert sind.
4. Klicken Sie im Menü Build (Erstellen) auf Build Solution (Projektmappe erstellen).

Weitere Informationen finden Sie unter Erstellen eines Treibers.

Schritt 4: Konfigurieren eines Computers zum Testen und Debuggen

Um einen Treiber zu testen und zu debuggen, führen Sie den Debugger auf dem Host-Computer und den Treiber auf dem Ziel-Computer aus. Bislang haben Sie Visual Studio auf dem Host-Computer verwendet, um einen Treiber zu erstellen. Als nächstes müssen Sie einen Zielcomputer konfigurieren. Um einen Zielcomputer zu konfigurieren, folgen Sie den Direktiveen in Bereitstellen eines Computers für die Bereitstellung und das Testen von Treibern.

Schritt 5: Aktivieren des Tracings zum Debuggen des Kernels

Der Code der Vorlage enthält mehrere Trace-Nachrichten (TraceEvents), mit deren Hilfe Sie Funktionsaufrufe verfolgen können. Alle Funktionen im Quellcode enthalten Trace-Nachrichten, die den Eintritt und den Austritt aus einer Funktion markieren. Bei Fehlern enthält die Trace-Nachricht den Code des Fehlers und eine aussagekräftige Zeichenfolge. Da das WPP Tracing für Ihr Treiberprojekt aktiviert ist, enthält die PDB-Symboldatei, die während des Build-Prozesses erstellt wird, Direktiveen zur Formatierung von Trace-Nachrichten. Wenn Sie den Host- und den Zielcomputer für das WPP Tracing konfigurieren, kann Ihr Treiber Trace-Nachrichten an eine Datei oder den Debugger senden.

So konfigurieren Sie Ihren Host-Computer für das WPP-Tracing:

1. Erstellen Sie Dateien im Trace Message Format (TMF), indem Sie die Formatierungsanweisungen für Trace-Nachrichten aus der PDB-Symboldatei extrahieren.

   Sie können Tracepdb.exe verwenden, um TMF-Dateien zu erstellen. Das Tool befindet sich im <Installationsordner>Windows Kits\10.0\bin\<architecture> des WDK. Der folgende Befehl erstellt TMF-Dateien für das Treiberprojekt.

   tracepdb -f <PDBFiles> -p <TMFDirectory>

   Mit der Option -f geben Sie den Speicherort und den Namen der PDB-Symboldatei an. Die Option -p gibt den Speicherort für die TMF-Dateien an, die von Tracepdb erstellt werden. Weitere Informationen finden Sie unter Tracepdb-Befehle.

   Am angegebenen Ort sehen Sie drei Dateien (eine pro .c-Datei im Projekt). Sie sind mit GUID-Dateinamen versehen.

2. Geben Sie im Debugger die folgenden Befehle ein:

   1. .load Wmitrace

      Lädt die Erweiterung Wmitrace.dll.

   2. .chain

      Vergewissern Sie sich, dass die Erweiterung für den Debugger geladen ist.

   3. !wmitrace.searchpath +<TMF-Dateispeicherort>

      Fügt den Speicherort der TMF-Dateien zum Suchpfad der Debugger-Erweiterung hinzu.

      Die Ausgabe sieht ungefähr wie folgt aus:

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

So konfigurieren Sie Ihren Zielcomputer für das WPP Tracing

1. Vergewissern Sie sich, dass Sie das Tool Tracelog auf Ihrem Zielcomputer installiert haben. Das Tool befindet sich im Ordner <Installationsordner>Windows Kits\8.0\Tools\<arch> des WDK. Weitere Informationen finden Sie unter Tracelog-Befehlssyntax.

2. Öffnen Sie ein Befehlsfenster und führen Sie es als Administrator*in aus.

3. Geben Sie folgenden Befehl ein:

   tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

   Der Befehl startet eine Tracing-Sitzung namens MyTrace.

   Das Argument guid gibt die GUID des Trace-Anbieters an, bei dem es sich um den Client-Treiber handelt. Die GUID können Sie der Datei Trace.h im Visual Studio Professional 2019 Projekt entnehmen. Als weitere Option können Sie den folgenden Befehl eingeben und die GUID in einer .guid-Datei angeben. Die Datei enthält die GUID im Bindestrich-Format:

   tracelog -start MyTrace -guid c:\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

   Sie können die Tracing-Sitzung beenden, indem Sie den folgenden Befehl eingeben:

   tracelog -stop MyTrace

Schritt 6: Bereitstellen des Treibers auf dem Zielcomputer

1. Wählen Sie im Fenster Lösungs-Explorer den *<Projektnamen>*Paket aus und halten Sie ihn gedrückt (oder klicken Sie mit der rechten Maustaste darauf), und wählen Sie Eigenschaften.
2. Navigieren Sie im linken Bereich zu Konfigurationseigenschaften > Treiberinstallation > Bereitstellung.
3. Aktivieren Sie Bereitstellung bereitstellen und aktivieren Sie Importieren in den Driver Store.
4. Geben Sie für Remote-Computer-Name den Namen des Remote-Computers an.
5. Wählen Sie Installieren und verifizieren.
6. Klicken Sie auf OK.
7. Wählen Sie im Menü Debuggen die Option Debuggen starten oder drücken Sie F5 auf der Tastatur.

Hinweis

Geben Sie nicht die Hardware-ID Ihres Geräts unter Hardware ID Treiber Update an. Die Hardware-ID muss nur in der Informationsdatei (INF) Ihres Treibers angegeben werden.

Weitere Informationen zum Bereitstellen des Treibers auf dem Zielsystem in Visual Studio finden Sie unter Treiber auf einem Testcomputer bereitstellen.

Sie können den Treiber auch manuell auf dem Zielcomputer installieren, indem Sie den Geräte-Manager verwenden. Wenn Sie den Treiber von einer Eingabeaufforderung aus installieren möchten, stehen Ihnen diese Dienstprogramme zur Verfügung:

• PnPUtil

  Dieses Tool ist im Lieferumfang von Windows enthalten. Es befindet sich in Windows\System32. Sie können dieses Dienstprogramm verwenden, um den Treiber dem Store hinzuzufügen.

  C:\>pnputil /a m:\MyDriver_.inf
  Microsoft PnP Utility
  
  Processing inf : MyDriver_.inf
  Driver package added successfully.
  Published name : oem22.inf
  

  Weitere Informationen finden Sie unter PnPUtil-Beispiele.

• DevCon Update

  Dieses Tool ist im Lieferumfang des WDK enthalten. Sie können es zur Installation und Aktualisierung von Treibern verwenden.

  devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6
  

Schritt 7: Anzeigen des Treibers im Geräte-Manager

1. Geben Sie den folgenden Befehl ein, um den Geräte-Manager zu öffnen:

   devmgmt
   

2. Überprüfen Sie, ob Geräte-Manager einen Knoten für den folgenden Knoten anzeigt:

   Beispiele

   MyUSBDriver_Device

Schritt 8: Anzeigen der Ausgabe im Debugger

Visual Studio zeigt den Fortschritt zunächst im Fenster Ausgabe an. Dann öffnet es das Debugger-Sofortfenster. Überprüfen Sie, ob im Debugger auf dem Host-Computer Tracing-Nachrichten angezeigt werden. Die Ausgabe sollte wie folgt aussehen, wobei „MyUSBDriver_“ der Name des Treibermoduls ist:

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit

Zugehörige Themen

• Verstehen des KMDF-Vorlagencodes für einen USB-Client-Treiber
• Erste Schritte mit der Entwicklung von USB-Client-Treibern