Share via

Schreiben eines universellen Windows-Treibers (KMDF) basierend auf einer Vorlage

  • Artikel

In diesem Thema wird beschrieben, wie Sie einen universellen Windows-Treiber mit Kernel-Mode Driver Framework (KMDF) schreiben. Sie beginnen mit einer Microsoft Visual Studio-Vorlage und stellen dann Ihren Treiber auf einem separaten Computer bereit und installieren diesen.

Bevor Sie fortfahren, müssen Sie die unter Herunterladen des Windows Driver Kit (WDK) aufgeführten Installationsschritte ausführen.

Debugtools für Windows sind bei der Installation des WDK enthalten.

Erstellen und Erstellen eines Treibers

  1. Öffnen Sie Microsoft Visual Studio. Wählen Sie im Menü Datei die Option Neues > Projekt aus.

  2. Wählen Sie im Dialogfeld Neues Projekt erstellen in der linken Dropdownliste C++ aus, wählen Sie in der mittleren Dropdownliste Windows und in der rechten Dropdownliste Treiber aus.

  3. Wählen Sie kernel Mode Driver (KMDF) aus der Liste der Projekttypen aus. Wählen Sie Weiter aus.

    Screenshot des Dialogfelds

  4. Geben Sie im Dialogfeld Neues Projekt konfigurieren den Namen "KmdfDriver" in das Feld Projektname ein.

    Hinweis

    Wenn Sie einen neuen KMDF- oder UMDF-Treiber erstellen, müssen Sie einen Treibernamen auswählen, der maximal 32 Zeichen umfasst. Diese Längenbegrenzung ist in wdfglobals.h definiert.  

  5. Geben Sie im Feld Speicherort das Verzeichnis ein, in dem Sie das neue Projekt erstellen möchten.

  6. Aktivieren Sie Projektmappe und Projekt im gleichen Verzeichnis platzieren , und wählen Sie Erstellen aus.

    Screenshot des Dialogfelds

    Visual Studio erstellt ein Projekt und eine Projektmappe. Diese werden im Fenster Projektmappen-Explorer angezeigt. (Wenn das fenster Projektmappen-Explorer nicht angezeigt wird, wählen Sie im Menü Ansichtdie Option Projektmappen-Explorer aus.) Die Projektmappe verfügt über ein Treiberprojekt mit dem Namen KmdfDriver. Um den Quellcode des Treibers anzuzeigen, öffnen Sie eine der Dateien unter Quelldateien. Driver.c und Device.c sind gute Ausgangspunkte.

    Screenshot des Projektmappen-Explorers mit den Dateien im Treiberprojekt.

  7. Wählen Sie im fenster Projektmappen-ExplorerkmdfDriver aus, halten Sie es gedrückt (oder klicken Sie mit der rechten Maustaste darauf), und wählen Sie Eigenschaften aus. Navigieren Sie zu Konfigurationseigenschaften > Treibereinstellungen > Allgemein, und beachten Sie, dass die Zielplattform standardmäßig universal ist.

  8. Wählen Sie zum Erstellen Ihres Treibers im Menü Erstellen die Option Projektmappeerstellen aus. Microsoft Visual Studio zeigt den Buildstatus im Fenster Ausgabe an. (Wenn das Fenster Ausgabe nicht angezeigt wird, wählen Sie im Menü Ansicht die Option Ausgabe aus.)

    Überprüfen Sie, ob die Buildausgabe Folgendes enthält:

    >    Driver is 'Universal'.

    Wenn Sie überprüft haben, ob die Projektmappe erfolgreich erstellt wurde, können Sie Visual Studio schließen.

  9. Um den integrierten Treiber anzuzeigen, wechseln Sie in Explorer zu Ihrem KmdfDriver-Ordner und dann zu x64\Debug\KmdfDriver. Das Verzeichnis enthält die folgenden Dateien:

    • KmdfDriver.sys : Die Treiberdatei im Kernelmodus
    • KmdfDriver.inf – eine Informationsdatei, die Windows bei der Installation des Treibers verwendet

Bereitstellen des Treibers

Wenn Sie einen Treiber testen und debuggen, werden der Debugger und der Treiber in der Regel auf separaten Computern ausgeführt. Der Computer, auf dem der Debugger ausgeführt wird, wird als Hostcomputer bezeichnet, und der Computer, auf dem der Treiber ausgeführt wird, wird als Zielcomputer bezeichnet. Der Zielcomputer wird auch als Testcomputer bezeichnet. Weitere Informationen zum Debuggen von Treibern finden Sie unter Debugtools für Windows.

Bisher haben Sie Visual Studio verwendet, um einen Treiber auf dem Hostcomputer zu erstellen. Jetzt müssen Sie einen Zielcomputer konfigurieren.

  1. Befolgen Sie die Anweisungen unter Bereitstellen eines Computers für die Treiberbereitstellung und -tests (WDK 10).

    Tipp

    Wenn Sie die Schritte zum automatischen Bereitstellen des Zielcomputers mithilfe eines Netzwerkkabels ausführen, notieren Sie sich den Port und den Schlüssel. Sie verwenden sie später im Debugschritt. In diesem Beispiel verwenden wir 50000 als Port und 1.2.3.4 als Schlüssel.

    In szenarien mit echtem Treiberdebuggen wird die Verwendung eines von KDNET generierten Schlüssels empfohlen. Weitere Informationen zur Verwendung von KDNET zum Generieren eines zufälligen Schlüssels finden Sie im Thema Debug Drivers – Step by Step Lab (Sysvad Kernel Mode).

  2. Öffnen Sie auf dem Hostcomputer Ihre Projektmappe in Visual Studio. Sie können in Ihrem KmdfDriver-Ordner auf die Projektmappendatei KmdfDriver.sln doppelklicken.

  3. Wählen Sie im fenster Projektmappen-Explorer das KmdfDriver-Projekt aus, halten Sie es gedrückt (oder klicken Sie mit der rechten Maustaste darauf), und wählen Sie Eigenschaften aus.

  4. Wechseln Sie im Fenster KmdfDriver-Paketeigenschaftenseiten im linken Bereich zu Konfigurationseigenschaften > Treiberinstallationsbereitstellung>.

  5. Aktivieren Sie Vorherige Treiberversionen vor der Bereitstellung entfernen.

  6. Wählen Sie unter Name des Remotecomputers den Namen des Computers aus, den Sie zum Testen und Debuggen konfiguriert haben. In dieser Übung verwenden wir einen Computer namens MyTestComputer.

  7. Wählen Sie Hardware-ID-Treiberupdate aus, und geben Sie die Hardware-ID für Ihren Treiber ein. In dieser Übung lautet die Hardware-ID Root\KmdfDriver. Klicken Sie auf OK.

    Screenshot des Kmdfdriver-Paketeigenschaftenseitenfensters mit ausgewählter Installation des Bereitstellungstreibers

    Hinweis

    In dieser Übung identifiziert die Hardware-ID keine echte Hardware. Es identifiziert ein imaginäres Gerät, das einen Platz in der Gerätestruktur als untergeordnetes Element des Stammknotens erhält. Wählen Sie für echte Hardware nicht Hardware-ID-Treiberupdate aus. Wählen Sie stattdessen Installieren und Überprüfen aus. Die Hardware-ID wird in der Inf-Datei (Driver's Information) angezeigt. Navigieren Sie im fenster Projektmappen-Explorer zu KmdfDriver-Treiberdateien>, und doppelklicken Sie auf KmdfDriver.inf. Die Hardware-ID befindet sich unter [Standard.NT$ARCH$].

    [Standard.NT$ARCH$]
%KmdfDriver.DeviceDesc%=KmdfDriver_Device, Root\KmdfDriver

  8. Wählen Sie im Menü Erstellen die Option Lösung bereitstellen aus. Visual Studio kopiert automatisch die Dateien, die zum Installieren und Ausführen des Treibers auf den Zielcomputer erforderlich sind. Dies kann ein oder zwei Minuten dauern.

    Wenn Sie einen Treiber bereitstellen, werden die Treiberdateien in den Ordner %Systemdrive%\drivertest\drivers auf dem Testcomputer kopiert. Wenn während der Bereitstellung ein Fehler auftritt, können Sie überprüfen, ob die Dateien auf den Testcomputer kopiert werden. Vergewissern Sie sich, dass die Dateien .inf, .cat, test cert und .sys sowie alle anderen erforderlichen Dateien im Ordner %systemdrive%\drivertest\drivers vorhanden sind.

    Weitere Informationen zum Bereitstellen von Treibern finden Sie unter Bereitstellen eines Treibers auf einem Testcomputer.

Installieren des Treibers

Nachdem Ihr KMDF-Treiber auf dem Zielcomputer bereitgestellt wurde, installieren Sie nun den Treiber. Wenn Sie den Zielcomputer zuvor mit Visual Studio mithilfe der automatischen Option bereitgestellt haben, richtet Visual Studio den Zielcomputer so ein, dass testsignierte Treiber im Rahmen des Bereitstellungsprozesses ausgeführt werden. Jetzt müssen Sie nur noch den Treiber mithilfe des DevCon-Tools installieren.

  1. Navigieren Sie auf dem Hostcomputer in Ihrer WDK-Installation zum Ordner Tools, und suchen Sie das DevCon-Tool. Sehen Sie sich beispielsweise den folgenden Ordner an:

    C:\Programme (x86)\Windows Kits\10\Tools\x64\devcon.exe

    Kopieren Sie das DevCon-Tool auf Ihren Remotecomputer.

  2. Installieren Sie den Treiber auf dem Zielcomputer, indem Sie zu dem Ordner navigieren, der die Treiberdateien enthält, und führen Sie dann das DevCon-Tool aus.

    1. Dies ist die allgemeine Syntax für das devcon-Tool, das Sie zum Installieren des Treibers verwenden:

      devcon install <INF file><hardware ID>

      Die für die Installation dieses Treibers erforderliche INF-Datei ist KmdfDriver.inf. Die INF-Datei enthält die Hardware-ID für die Installation der Treiberbinärdatei ,KmdfDriver.sys. Denken Sie daran, dass die Hardware-ID in der INF-Datei Root\KmdfDriver lautet.

    2. Öffnen Sie ein Eingabeaufforderungsfenster als Administrator. Navigieren Sie zu Ihrem Treiberpaketordner, und geben Sie dann den folgenden Befehl ein:

      devcon install kmdfdriver.inf root\kmdfdriver

      Wenn Sie eine Fehlermeldung erhalten, dass devcon nicht erkannt wird, versuchen Sie, den Pfad zum devcon-Tool hinzuzufügen. Wenn Sie es beispielsweise in einen Ordner mit dem Namen C:\Tools auf dem Zielcomputer kopiert haben, versuchen Sie, den folgenden Befehl zu verwenden:

      c:\tools\devcon install kmdfdriver.inf root\kmdfdriver

      Ein Dialogfeld wird angezeigt, das angibt, dass der Testtreiber ein nicht signierter Treiber ist. Wählen Sie Diesen Treiber trotzdem installieren aus, um fortzufahren.

      Screenshot der Treiberinstallationswarnung.

Debuggen des Treibers

Nachdem Sie ihren KMDF-Treiber nun auf dem Zielcomputer installiert haben, fügen Sie einen Debugger remote vom Hostcomputer an.

  1. Öffnen Sie auf dem Hostcomputer ein Eingabeaufforderungsfenster als Administrator. Wechseln Sie zum verzeichnis WinDbg.exe. Wir verwenden die x64version von WinDbg.exe aus dem Windows Driver Kit (WDK), das im Rahmen der Installation des Windows-Kits installiert wurde. Hier ist der Standardpfad für WinDbg.exe:

    C:\Programme (x86)\Windows Kits\10\Debuggers\x64

  2. Starten Sie WinDbg, um mithilfe des folgenden Befehls eine Verbindung mit einer Kerneldebugsitzung auf dem Zielcomputer herzustellen. Der Wert für Port und Schlüssel sollte mit dem wert identisch sein, den Sie zum Bereitstellen des Zielcomputers verwendet haben. Wir verwenden 50000 für den Port und 1.2.3.4 für den Schlüssel, die Werte, die wir während des Bereitstellungsschritts verwendet haben. Das k-Flag gibt an, dass es sich um eine Kerneldebugsitzung handelt.

    WinDbg -k net:port=50000,key=1.2.3.4

  3. Wählen Sie im Menü Debuggen die Option Umbruch aus. Der Debugger auf dem Hostcomputer wird in den Zielcomputer eingebrochen. Im Fenster Debuggerbefehl wird die Kerneldebugging-Eingabeaufforderung kd> angezeigt.

  4. An diesem Punkt können Sie mit dem Debugger experimentieren, indem Sie An der kd-Eingabeaufforderung> Befehle eingeben. Sie können beispielsweise die folgenden Befehle ausprobieren:

  5. Um den Zielcomputer erneut ausführen zu lassen, wählen Sie im Menü Debuggendie Option Go aus, oder drücken Sie "g", und drücken Sie dann die EINGABETASTE.

  6. Um die Debugsitzung zu beenden, wählen Sie im Menü Debuggen die Option Debuggen trennen aus.

    Wichtig

    Stellen Sie sicher, dass Sie den Befehl "Go" verwenden, um den Zielcomputer erneut ausführen zu lassen, bevor Sie den Debugger beenden, sonst reagiert der Zielcomputer nicht auf Ihre Maus- und Tastatureingabe, da er weiterhin mit dem Debugger spricht.

Eine ausführliche schrittweise exemplarische Vorgehensweise zum Debuggen des Treibers finden Sie unter Debuggen von universellen Treibern – Schritt-für-Schritt-Lab (Echo-Kernel-Modus).

Weitere Informationen zum Remotedebuggen finden Sie unter Remotedebuggen mithilfe von WinDbg.

Verwenden des Treibermodulframeworks (DMF)

Das Driver Module Framework (DMF) ist eine Erweiterung von WDF, die zusätzliche Funktionen für einen WDF-Treiberentwickler ermöglicht. Es hilft Entwicklern, jeden Typ von WDF-Treibern besser und schneller zu schreiben.

DMF als Framework ermöglicht die Erstellung von WDF-Objekten namens DMF Modules. Der Code für diese DMF-Module kann von verschiedenen Treibern gemeinsam genutzt werden. Darüber hinaus bündelt DMF eine Bibliothek mit DMF-Modulen, die wir für unsere Treiber entwickelt haben und der Meinung sind, dass sie anderen Treiberentwicklern einen Mehrwert bieten würde.

DMF ersetzt WDF nicht. DMF ist ein zweites Framework, das mit WDF verwendet wird. Der Entwickler, der DMF nutzt, verwendet weiterhin WDF und alle seine Grundtypen, um Gerätetreiber zu schreiben.

Weitere Informationen finden Sie unter Driver Module Framework (DMF).