Freigeben über

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

In diesem Artikel 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.

Voraussetzungen

  • Führen Sie die Schritte zum Installieren Windows Driver Kit (WDK)aus. Debugging-Tools für Windows sind enthalten, wenn Sie das Windows Driver Kit (WDK) installieren.

  • Installieren Sie Visual Studio 2022-. Wählen Sie bei der Installation von Visual Studio 2022 den Workload Desktop-Entwicklung mit C++ und fügen Sie dann unter Einzelne Komponenten hinzu:

    • MSVC v143: C++-Bibliotheken mit Spectre-Entschärfungen für ARM64/ARM64EC in VS 2022 (neueste Version)
    • MSVC v143 – VS 2022 C++ x64/x86 Spectre-geminderte Bibliotheken (Neueste)
    • C++ ATL für die neuesten v143-Build-Tools mit Spectre Mitigations (ARM64/ARM64EC)
    • C++ ATL für neueste v143-Buildtools mit Spectre-Abmilderungen (x86 & x64)
    • C++ MFC für die neuesten v143-Build-Tools mit Spectre-Mitigations (ARM64/ARM64EC)
    • C++ MFC für neueste v143-Buildtools mit Spectre Mitigations (x86 & x64)
    • Windows-Treiberkit

Erstellen und Entwickeln eines Treibers

  1. Öffnen Sie Microsoft Visual Studio. Wählen Sie im Menü DateiNeues >Projekt.

  2. Wählen Sie im Dialogfeld Erstellen eines neuen Projekts im linken Dropdownmenü C++- aus, wählen Sie Windows in der mittleren Dropdownliste und dann Treiber- in der rechten Dropdownliste aus.

  3. Wählen Sie den Kernelmodustreiber (KERNEL Mode Driver, KMDF) aus der Liste der Projekttypen aus. Wählen Sie Weiteraus.

    Screenshot des dialogfelds

    Tipp

    Wenn Sie in Visual Studio keine Treiberprojektvorlagen finden können, wurde die WDK Visual Studio-Erweiterung nicht ordnungsgemäß installiert. Um dieses Problem zu beheben, starten Sie Visual Studio Installer, wählen Sie Ändern, fügen Sie Windows Driver Kits auf der Registerkarte einzelne Komponente hinzu, und wählen Sie Ändernaus.

  4. Geben Sie im Dialogfeld " Neues Projekt konfigurieren " im Feld "Projektname " "KmdfDriver" ein.

    Hinweis

    Wenn Sie einen neuen KMDF- oder UMDF-Treiber erstellen, müssen Sie einen Treibernamen mit 32 Zeichen oder weniger auswählen. Dieser Längengrenzwert wird in wdfglobals.h definiert.  

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

  6. Markieren Sie Lösung und Projekt in dasselbe Verzeichnis legen und wählen Sie Erstellen.

    Screenshot des Dialogfelds

    Visual Studio erstellt ein Projekt und eine Projektmappe. Diese werden im Fenster Projektmappen-Explorer angezeigt. (Wenn das Projektmappen-Explorer-Fenster nicht sichtbar ist, wählen Sie im Menü "Ansicht" den Projektmappen-Explorer aus.) Die Lösung verfügt über ein Treiberprojekt mit dem Namen KmdfDriver. Um den Treiberquellcode anzuzeigen, öffnen Sie eine der Dateien unter "Quelldateien". Driver.c und Device.c sind gute Ausgangspunkte.

    Screenshot des Solution-Explorers mit den Dateien im Treiberprojekt.

  7. Wählen Sie im Solution ExplorerKmdfDriver aus und 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 Zielplattform standardmäßig auf Universal voreingestellt ist.

  8. Um Ihren Treiber zu erstellen, wählen Sie Lösung erstellen aus dem Menü Erstellen. Microsoft Visual Studio zeigt den Buildfortschritt im Ausgabefenster an. (Wenn das Ausgabefenster nicht angezeigt wird, wählen Sie " Ausgabe " im Menü "Ansicht " aus.)

    Stellen Sie sicher, dass die Buildausgabe Folgendes umfasst:

    >    Driver is 'Universal'.

    Wenn Sie verifizieren, dass die Lösung erfolgreich gebaut wurde, können Sie Visual Studio schließen.

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

    • KmdfDriver.sys--die Kernelmodustreiberdatei
    • KmdfDriver.inf-eine Informationsdatei, die Windows beim Installieren des Treibers verwendet

Bereitstellen des Treibers

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

Bisher haben Sie Visual Studio zum Erstellen eines Treibers auf dem Hostcomputer verwendet. Jetzt müssen Sie einen Zielcomputer konfigurieren.

  1. Folgen Sie den Anweisungen in Bereitstellen eines Computers für die Treiberbereitstellung und -tests (WDK 10).

    Tipp

    Wenn Sie die Schritte ausführen, um den Zielcomputer automatisch über ein Netzwerkkabel bereitzustellen, notieren Sie sich den Anschluss 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 echten Treiberdebuggingszenarien empfehlen wir die Verwendung eines von KDNET generierten Schlüssels. Weitere Informationen zur Verwendung von KDNET zum Generieren eines Zufallsschlüssels finden Sie im Artikel " Debug Drivers - Step by Step Lab (Sysvad Kernel Mode) ".

  2. Öffnen Sie auf dem Host-Computer Ihre Lösung in Visual Studio. Sie können in Ihrem KmdfDriver-Ordner auf die Lösungsdatei KmdfDriver.sln doppelklicken.

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

  4. Wechseln Sie im Fenster Eigenschaftenseiten des KmdfDriver-Pakets im linken Bereich zu Konfigurationseigenschaften > Treiberinstallation > Bereitstellung.

  5. Markieren Sie Vorherige Treiberversionen vor der Bereitstellung entfernen.

  6. Wählen Sie für den Namen 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-Treiberupdateaus, und geben Sie die Hardware-ID für Ihren Treiber ein. In dieser Übung ist die Hardware-ID "Root\KmdfDriver". Wählen Sie OK aus.

    Screenshot des Eigenschaftsseiten-Fensters des kmdfdriver-Pakets, bei dem die Installation des Bereitstellungstreibers ausgewählt ist

    Hinweis

    In dieser Übung identifiziert die Hardware-ID keine echte Hardware. Er identifiziert ein imaginäres Gerät, das als untergeordneter Knoten des Root-Knotens einen Platz im Gerätebaum erhält. Wählen Sie für echte Hardware kein 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. Wechseln Sie im Lösungs-Explorer-Fenster 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 zum Installieren und Ausführen des Treibers erforderlichen Dateien auf den Zielcomputer.

    Wenn Sie einen Treiber bereitstellen, werden die Treiberdateien auf dem Testcomputer in den Ordner %Systemdrive%\drivertest\drivers 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 .inf-, .cat-Dateien, das Testzertifikat, die .sys-Dateien 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 er im Rahmen des Bereitstellungsprozesses Tests von signierten Treibern ausführt. Jetzt müssen Sie nur den Treiber mithilfe des DevCon-Tools installieren.

  1. Navigieren Sie auf dem Hostcomputer zu dem Ordner "Tools" in Ihrer WDK-Installation, und suchen Sie das DevCon-Tool. Suchen Sie beispielsweise im folgenden Ordner:

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

    Kopieren Sie das DevCon-Tool auf Ihren Remotecomputer.

  2. Installieren Sie auf dem Zielcomputer den Treiber, 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-Datei><Hardware-ID>

      Die FÜR die Installation dieses Treibers erforderliche INF-Datei ist KmdfDriver.inf. Die INF-Datei enthält die Hardware-ID zum Installieren der Treiber-Binärdatei ,KmdfDriver.sys. Erinnern Sie sich daran, dass die Hardware-ID, die sich in der INF-Datei befindet, "Root\KmdfDriver" ist.

    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 die Fehlermeldung erhalten, dass devcon nicht erkannt wird, versuchen Sie, den Pfad zum devcon-Tool hinzuzufügen. Wenn Sie ihn beispielsweise in einen Ordner auf dem Zielcomputer kopiert haben, der C:\Toolsheißt, versuchen Sie es mit dem folgenden Befehl:

      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, um fortzufahren.

      Screenshot der Treiberinstallationswarnung.

Debuggen des Treibers

Nachdem Sie den 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 in das Verzeichnis WinDbg.exe. Verwenden Sie die x64version von WinDbg.exe aus dem Windows Driver Kit (WDK), das als Teil der Windows Kit-Installation installiert wurde. Hier ist der Standardpfad zu 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 übereinstimmen, was 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ü Debug die Option Break. Der Debugger auf dem Hostcomputer greift in den Zielcomputer ein. Im Fenster Debuggerbefehl sehen Sie die Kerneldebugging-Eingabeaufforderung: kd>.

  4. An dieser Stelle können Sie mit dem Debugger experimentieren, indem Sie Befehle an der KD-Eingabeaufforderung> eingeben. Sie können beispielsweise die folgenden Befehle ausprobieren:

  5. Um den Zielcomputer erneut auszuführen, wählen Sie Go aus dem Menü Debug, oder drücken Sie "g", dann "Enter".

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

    Von Bedeutung

    Stellen Sie sicher, dass Sie den Befehl "go" verwenden, damit der Zielcomputer wieder ausgeführt wird, bevor Sie den Debugger beenden, sonst reagiert der Zielcomputer nicht mehr auf Ihre Maus- und Tastatureingaben, da er immer noch mit dem Debugger kommuniziert.

Eine detaillierte schrittweise Vorgehensweise des Treiberdebuggingprozesses finden Sie unter Debuggen universeller Treiber – Schritt für Schritt -Übung (Echo Kernel-Mode).

Weitere Informationen zum Remotedebugging finden Sie unter Remotedebugging mit WinDbg.

Verwenden des Treibermodulframeworks (DMF)

Das Driver Module Framework (DMF) ist eine Erweiterung für 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 zwischen verschiedenen Treibern gemeinsam verwendet werden. Darüber hinaus bündelt DMF eine Bibliothek von DMF-Modulen, die wir für unsere Treiber entwickelt haben und von denen wir glauben, dass sie anderen Treiberentwicklern einen Mehrwert bieten könnten.

DMF ersetzt WDF nicht. DMF ist ein zweites Framework, das mit WDF verwendet wird. Der Entwickler, der DMF verwendet, verwendet weiterhin WDF und alle grundtypen zum Schreiben von Gerätetreibern.

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

  • Last updated on