Schreiben Ihres ersten USB-Clienttreibers (KMDF)

  • Artikel

In diesem Artikel verwenden Sie die mit Microsoft Visual Studio bereitgestellte USB-Kernel-Mode-Treibervorlage , um einen einfachen KmDF-basierten Clienttreiber zu schreiben. Nach dem Erstellen und Installieren des Clienttreibers zeigen Sie den Clienttreiber in Geräte-Manager an und zeigen die Treiberausgabe in einem Debugger an.

Eine Erklärung zum von der Vorlage generierten Quellcode finden Sie unter Grundlegendes zum KMDF-Vorlagencode für einen USB-Clienttreiber.

Voraussetzungen

Zum Entwickeln, Debuggen und Installieren eines Kernelmodustreibers benötigen Sie zwei Computer:

  • Ein Hostcomputer, auf dem Windows 7 oder eine höhere Version des Windows-Betriebssystems ausgeführt wird. Der Hostcomputer ist Ihre Entwicklungsumgebung, in der Sie Ihren Treiber schreiben und debuggen.
  • Ein Zielcomputer, auf dem Windows Vista oder eine höhere Version von Windows ausgeführt wird. Der Zielcomputer verfügt über den Kernelmodustreiber, den Sie debuggen möchten.

Bevor Sie beginnen, stellen Sie sicher, dass Sie die folgenden Anforderungen erfüllen:

Softwareanforderungen

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

Hardwareanforderungen

Rufen Sie ein USB-Gerät ab, für das Sie den Clienttreiber schreiben. In den meisten Fällen erhalten Sie ein USB-Gerät und dessen Hardwarespezifikation. In der Spezifikation werden die Gerätefunktionen und die unterstützten Anbieterbefehle beschrieben. Verwenden Sie die Spezifikation, um die Funktionalität des USB-Treibers und die zugehörigen Entwurfsentscheidungen zu bestimmen.

Wenn Sie noch nicht mit der Entwicklung von USB-Treibern vertraut sind, verwenden Sie das OSR USB FX2-Lernkit, um USB-Beispiele zu untersuchen, die im WDK enthalten sind. Sie können das Lernkit von OSR Online erhalten. Es enthält das USB FX2-Gerät und alle erforderlichen Hardwarespezifikationen, um einen Clienttreiber zu implementieren.

Sie können auch ein Microsoft USB Test Tool (MUTT)-Geräte erhalten. MUTT-Hardware kann bei JJG Technologies erworben werden. Auf dem Gerät ist keine installierte Firmware installiert. Laden Sie zum Installieren der Firmware das MUTT-Softwarepaket von dieser Website herunter, und führen Sie MUTTUtil.exe aus. Weitere Informationen finden Sie in der Im Paket enthaltenen Dokumentation.

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

Anweisungen zum Generieren von KMDF-Treibercode finden Sie in den Schritten unter Schreiben eines KMDF-Treibers basierend auf einer Vorlage.

Wählen Sie für USB-spezifischen Code die folgenden Optionen in Visual Studio aus:

  1. Geben Sie im Dialogfeld Neues Projekt im Suchfeld oben USB ein.
  2. Wählen Sie im mittleren Bereich Kernelmodustreiber, USB (KMDF) aus.
  3. Wählen Sie Weiter aus.
  4. Geben Sie einen Projektnamen ein, wählen Sie einen Speicherort aus, und wählen Sie Erstellen aus.

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

Neue Visual Studio-Projektoptionen.

Zweiter Bildschirm für neue Visual Studio-Projektoptionen.

In diesem Artikel wird davon ausgegangen, dass der Name des Visual Studio-Projekts "MyUSBDriver_" lautet. Er enthält die folgenden Dateien:

Dateien BESCHREIBUNG
Public.h Stellt allgemeine Deklarationen bereit, die vom Clienttreiber und Benutzeranwendungen freigegeben werden, die mit dem USB-Gerät kommunizieren.
<Projektname.inf> Enthält Informationen, die zum Installieren des Clienttreibers auf dem Zielcomputer erforderlich sind.
Trace.h Deklariert Ablaufverfolgungsfunktionen und Makros.
Driver.h; Driver.c Deklariert und definiert Treibereinstiegspunkte und Ereignisrückrufroutinen.
Device.h; Device.c Deklariert und definiert die Ereignisrückrufroutine für das Hardwarevorbereitungsereignis.
Queue.h; Queue.c Deklariert und definiert eine Ereignisrückrufroutine für das Ereignis, das vom Warteschlangenobjekt des Frameworks ausgelöst wird.

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

Bevor Sie den Treiber erstellen, müssen Sie die VORLAGEN-INF-Datei mit Informationen zu Ihrem Gerät ändern, insbesondere die Hardware-ID-Zeichenfolge.

Doppelklicken Sie in Projektmappen-Explorer unter Treiberdateien auf die INF-Datei.

In der INF-Datei können Sie Informationen wie den Hersteller- und Anbieternamen, die Gerätesetupklasse usw. angeben. Eine Information, die Sie angeben müssen, ist die Hardware-ID Ihres Geräts.

So geben Sie die Hardware-ID-Zeichenfolge an:

  1. Schließen Sie Ihr USB-Gerät an Ihren Hostcomputer an, und lassen Sie windows das Gerät auflisten.

  2. Öffnen Sie Geräte-Manager eigenschaften für Ihr Gerät.

  3. Wählen Sie auf der Registerkarte Details unter Eigenschaft die Option Hardward-IDsaus.

    Die Hardware-ID für das Gerät wird im Listenfeld angezeigt. Halten Sie (oder klicken Sie mit der rechten Maustaste) und kopieren Sie die Hardware-ID-Zeichenfolge.

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

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

Schritt 3: Erstellen des USB-Clienttreibercodes

So erstellen Sie Ihren Treiber:

  1. Öffnen des Treiberprojekts oder der Projektmappe in Visual Studio
  2. Wählen Sie die Projektmappe im Projektmappen-Explorer aus, halten Sie sie gedrückt (oder klicken Sie mit der rechten Maustaste darauf), und wählen Sie Configuration Manager aus.
  3. Wählen Sie auf der Configuration Manager die Aktive Projektmappenkonfiguration (z. B. Debuggen oder Release) und die Active Solution Platform (z. B. Win32) aus, die dem Typ des builds entsprechen, 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

Zum Testen und Debuggen eines Treibers führen Sie den Debugger auf dem Hostcomputer und den Treiber auf dem Zielcomputer aus. Bisher haben Sie Visual Studio auf dem Hostcomputer verwendet, um einen Treiber zu erstellen. Als Nächstes müssen Sie einen Zielcomputer konfigurieren. Befolgen Sie zum Konfigurieren eines Zielcomputers die Anweisungen unter Bereitstellen eines Computers für die Treiberbereitstellung und -tests.

Schritt 5: Aktivieren der Ablaufverfolgung für kerneldebuggen

Der Vorlagencode enthält mehrere Ablaufverfolgungsmeldungen (TraceEvents), mit denen Sie Funktionsaufrufe nachverfolgen können. Alle Funktionen im Quellcode enthalten Ablaufverfolgungsmeldungen, die den Eintrag und das Beenden einer Routine markieren. Bei Fehlern enthält die Ablaufverfolgungsmeldung den Fehlercode und eine aussagekräftige Zeichenfolge. Da die WPP-Ablaufverfolgung für Ihr Treiberprojekt aktiviert ist, enthält die während des Buildvorgangs erstellte PDB-Symboldatei Anweisungen zur Formatierung von Ablaufverfolgungsmeldungen. Wenn Sie den Host und die Zielcomputer für die WPP-Ablaufverfolgung konfigurieren, kann Ihr Treiber Ablaufverfolgungsmeldungen an eine Datei oder den Debugger senden.

So konfigurieren Sie Ihren Hostcomputer für die WPP-Ablaufverfolgung:

  1. Erstellen Sie TMF-Dateien (Trace Message Format), indem Sie Anweisungen zur Formatierung von Ablaufverfolgungsnachrichten 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. Mit dem folgenden Befehl werden TMF-Dateien für das Treiberprojekt erstellt.

    tracepdb -f <PDBFiles> -p <TMFDirectory>

    Die Option -f gibt 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 Speicherort werden drei Dateien (eine pro C-Datei im Projekt) angezeigt. Sie erhalten GUID-Dateinamen.

  2. Geben Sie im Debugger die folgenden Befehle ein:

    1. .load Wmitrace

      Lädt die Wmitrace.dll-Erweiterung.

    2. .Kette

      Vergewissern Sie sich, dass die Debuggererweiterung geladen ist.

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

      Fügen Sie den Speicherort der TMF-Dateien zum Suchpfad der Debuggererweiterung 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 die WPP-Ablaufverfolgung:

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

  2. Öffnen Sie ein Befehlsfenster , und führen Sie als Administrator 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 Ablaufverfolgungssitzung mit dem Namen MyTrace.

    Das guid-Argument gibt die GUID des Ablaufverfolgungsanbieters an, bei dem es sich um den Clienttreiber handelt. Sie können die GUID aus Trace.h im projekt Visual Studio Professional 2019 abrufen. 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 Bindestrichformat:

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

    Sie können die Ablaufverfolgungssitzung beenden, indem Sie den folgenden Befehl eingeben:

    tracelog -stop MyTrace

Schritt 6: Bereitstellen des Treibers auf dem Zielcomputer

  1. Wählen Sie im Projektmappen-Explorer Fenster den *<Projektnamen>*Paket aus, und halten Sie sie gedrückt (oder klicken Sie mit der rechten Maustaste darauf), und wählen Sie Eigenschaften aus.
  2. Navigieren Sie im linken Bereich zu Konfigurationseigenschaften > Treiberinstallationsbereitstellung>.
  3. Aktivieren Sie Bereitstellung aktivieren, und aktivieren Sie Den Treiberspeicher importieren.
  4. Geben Sie unter Remotecomputername den Namen des Zielcomputers an.
  5. Wählen Sie Installieren und Überprüfen aus.
  6. Klicken Sie auf OK.
  7. Wählen Sie im Menü Debuggen die Option Debuggen starten aus, oder drücken Sie F5 auf der Tastatur.

Hinweis

Geben Sie die Hardware-ID Ihres Geräts nicht unter Hardware-ID-Treiberupdate an. Die Hardware-ID darf nur in der INF-Datei (Information) Ihres Treibers angegeben werden.

Weitere Informationen zum Bereitstellen des Treibers im Zielsystem in Visual Studio finden Sie unter Bereitstellen eines Treibers auf einem Testcomputer.

Sie können den Treiber auch manuell auf dem Zielcomputer installieren, indem Sie Geräte-Manager verwenden. Wenn Sie den Treiber über eine Eingabeaufforderung installieren möchten, stehen folgende Hilfsprogramme zur Verfügung:

  • PnPUtil

    Dieses Tool wird im Lieferumfang von Windows verwendet. Es befindet sich in Windows\System32. Sie können dieses Hilfsprogramm verwenden, um den Treiber dem Treiberspeicher 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. Sie können sie verwenden, um Treiber zu installieren und zu aktualisieren.

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

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

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

    devmgmt

  2. Stellen Sie sicher, dass Geräte-Manager einen Knoten für den folgenden Knoten anzeigt:

    Beispiele

    MyUSBDriver_Device

Schritt 8: Anzeigen der Ausgabe im Debugger

Visual Studio zeigt zuerst den Fortschritt im Ausgabefenster an. Anschließend wird das Debugger-Direktfenster geöffnet. Vergewissern Sie sich, dass Ablaufverfolgungsmeldungen im Debugger auf dem Hostcomputer 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