Delen via

Zelfstudie: Een UNIVERSAL Windows-stuurprogramma (KMDF) schrijven op basis van een sjabloon

  • Artikel

In dit onderwerp wordt beschreven hoe u een Universeel Windows-stuurprogramma schrijft met behulp van Kernel-Mode Driver Framework (KMDF). U begint met een Microsoft Visual Studio-sjabloon en implementeert en installeert vervolgens uw stuurprogramma op een afzonderlijke computer.

Vereiste voorwaarden

  • Volg de stappen voor het installeren van Windows Driver Kit (WDK). Hulpprogramma's voor foutopsporing voor Windows is opgenomen wanneer u de WDK installeert.

  • Installeer Visual Studio 2022. Wanneer u Visual Studio 2022 installeert, selecteert u de Desktopontwikkeling met C++ workload en voegt u vervolgens onder Afzonderlijke onderdelen toe:

    • MSVC v143 - VS 2022 C++ ARM64/ARM64EC Spectre-gemitigeerde bibliotheken (Nieuwste)
    • MSVC v143 - VS 2022 C++ x64/x86 bibliotheken met Spectre-mitigatie (laatste versie)
    • C++ ATL voor de nieuwste v143-buildtools met Spectre-mitigaties (ARM64/ARM64EC)
    • C++ ATL voor de nieuwste v143-buildtools met Spectre-beveiligingen (x86 & x64)
    • C++ MFC voor de nieuwste v143-buildtools met Spectre-beveiligingsmaatregelen (ARM64/ARM64EC)
    • C++ MFC voor de nieuwste v143 buildtools met Spectre-beveiligingsmaatregelen (x86 & x64)
    • Windows Driver Kit

Een stuurprogramma maken en bouwen

  1. Open Microsoft Visual Studio. Kies in het menu BestandNieuw > Project.

  2. Selecteer in het dialoogvenster Een nieuw project maken de optie C++ in de keuzelijst links, kies Windows in de middelste keuzelijst, en kies stuurprogramma in de rechter keuzelijst.

  3. Selecteer KMDF (Kernel Mode Driver) in de lijst met projecttypen. Kies Volgende.

    Schermopname van het dialoogvenster Nieuw project, waarin het stuurprogramma voor de kernelmodus is geselecteerd.

    Hint

    Als u geen stuurprogrammaprojectsjablonen in Visual Studio kunt vinden, is de WDK Visual Studio-extensie niet correct geïnstalleerd. U kunt dit oplossen door Visual Studio Installer-te starten, wijzigen te selecteren, Windows Driver Kits toe te voegen op het tabblad Afzonderlijke onderdelen en Wijzigente selecteren.

  4. Voer in het dialoogvenster Uw nieuwe project configureren 'KmdfDriver' in het veld Projectnaam in.

    Opmerking

    Wanneer u een nieuw KMDF- of UMDF-stuurprogramma maakt, moet u een stuurprogrammanaam met 32 tekens of minder selecteren. Deze lengtelimiet wordt gedefinieerd in wdfglobals.h.  

  5. Voer in het veld Locatie de map in waar u het nieuwe project wilt maken.

  6. Controleer Oplossing en project in dezelfde map plaatsen en selecteer maken.

    Schermafbeelding van het dialoogvenster projectconfiguratie.

    Visual Studio maakt één project en een oplossing. U kunt deze zien in het Solution Explorer-venster. (Als het Venster Solution Explorer niet zichtbaar is, kiest u Solution Explorer in het menu Beeld .) De oplossing heeft een stuurprogrammaproject met de naam KmdfDriver. Als u de broncode van het stuurprogramma wilt zien, opent u een van de bestanden onder Bronbestanden. Driver.c en Device.c zijn goede plaatsen om te beginnen.

    Schermafbeelding van Solution Explorer met de bestanden in het stuurprogrammaproject.

  7. Selecteer en houd kmdfDriver in het venster Solution Explorer ingedrukt (of klik erop met de rechtermuisknop) en kies Eigenschappen. Ga naar configuratie-eigenschappen > stuurprogramma-instellingen > Algemeneen houd er rekening mee dat doelplatform standaard is ingesteld op Universeel.

  8. Als u het stuurprogramma wilt bouwen, kiest u Build Solution in het menu Build. Microsoft Visual Studio geeft de voortgang van de build weer in het venster Output. (Als het venster Uitvoer niet zichtbaar is, kiest u Uitvoer- in het menu Weergave.)

    Controleer of de build-uitvoer het volgende bevat:

    >    Driver is 'Universal'.

    Wanneer u hebt gecontroleerd of de oplossing is gebouwd, kunt u Visual Studio sluiten.

  9. Als u het ingebouwde stuurprogramma wilt zien, gaat u in Verkenner naar de map KmdfDriver en vervolgens naar x64\Debug\KmdfDriver. De map bevat de volgende bestanden:

    • KmdfDriver.sys - het stuurprogrammabestand voor de kernelmodus
    • KmdfDriver.inf- een informatiebestand dat Door Windows wordt gebruikt bij het installeren van het stuurprogramma

Het stuurprogramma implementeren

Wanneer u een stuurprogramma test en foutopsporing uitvoert, worden het foutopsporingsprogramma en het stuurprogramma meestal uitgevoerd op afzonderlijke computers. De computer waarop het foutopsporingsprogramma wordt uitgevoerd, wordt de hostcomputergenoemd en de computer waarop het stuurprogramma wordt uitgevoerd, wordt de doelcomputergenoemd. De doelcomputer wordt ook wel de testcomputergenoemd. Zie Hulpprogramma's voor foutopsporing voor Windows voor meer informatie over foutopsporingsstuurprogramma's.

Tot nu toe hebt u Visual Studio gebruikt om een stuurprogramma op de hostcomputer te bouwen. Nu moet u een doelcomputer configureren.

  1. Volg de instructies in Een computer inrichten voor het implementeren en testen van stuurprogramma's (WDK 10).

    Hint

    Wanneer u de stappen volgt om de doelcomputer automatisch in te richten met behulp van een netwerkkabel, noteert u de poort en sleutel. U gebruikt deze later in de stap voor foutopsporing. In dit voorbeeld gebruiken we 50000 als poort en 1.2.3.4 als sleutel.

    In scenario's voor foutopsporing van echte stuurprogramma's wordt u aangeraden een door KDNET gegenereerde sleutel te gebruiken. Zie het onderwerp Foutopsporingsstuurprogramma's - Stapsgewijze lab (Sysvad-kernelmodus) voor meer informatie over het gebruik van KDNET om een willekeurige sleutel te genereren.

  2. Open uw oplossing op de hostcomputer in Visual Studio. U kunt dubbelklikken op het oplossingsbestand, KmdfDriver.sln, in de map KmdfDriver.

  3. Selecteer en houd het KmdfDriver-project in het venster Solution Explorer ingedrukt (of klik erop met de rechtermuisknop) en kies Eigenschappen.

  4. Ga in het venster KmdfDriver Package Property Pages in het linkerdeelvenster naar Configuratie-eigenschappen > Stuurprogramma-installatie > Implementatie.

  5. Controleer Vorige stuurprogrammaversies verwijderen vóór de implementatie.

  6. Selecteer bij Externe computernaam de naam van de computer die u hebt geconfigureerd voor testen en foutopsporing. In deze oefening gebruiken we een computer met de naam MyTestComputer.

  7. Selecteer hardware-id-stuurprogramma-updateen voer de hardware-id voor uw stuurprogramma in. In deze oefening is de hardware-id Root\KmdfDriver. Kies OK.

    schermopname van het venster met eigenschappenpagina's van het kmdfdriver-pakket, waarin de installatie van het implementatiestuurprogramma is geselecteerd

    Opmerking

    In deze oefening identificeert de hardware-id geen echt stukje hardware. Het identificeert een denkbeeldig apparaat dat een plek krijgt in de apparaatstructuur als een kind van het hoofdknooppunt. Selecteer voor echte hardware niet Stuurprogramma-update van hardware-id, maar kies Installeren en Verifiëren. U ziet de hardware-id in het INF-bestand (Informatie van het stuurprogramma). Ga in het venster Solution Explorer naar KmdfDriver-stuurprogrammabestanden > en dubbelklik op KmdfDriver.inf. De hardware-id bevindt zich onder [Standard.NT$ARCH$].

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

  8. Kies in het menu Build de optie Deploy Solution. Visual Studio kopieert automatisch de bestanden die nodig zijn om het stuurprogramma te installeren en uit te voeren naar de doelcomputer. Dit kan een paar minuten duren.

    Wanneer u een stuurprogramma implementeert, worden de stuurprogrammabestanden gekopieerd naar de map %Systemdrive%\drivertest\drivers op de testcomputer. Als er iets misgaat tijdens de implementatie, kunt u controleren of de bestanden naar de testcomputer worden gekopieerd. Controleer of de bestanden .inf, .cat, testcertificaat en .sys en eventuele andere benodigde bestanden aanwezig zijn in de map %systemdrive%\drivertest\drivers.

    Zie Een stuurprogramma implementeren op een testcomputervoor meer informatie over het implementeren van stuurprogramma's.

Het stuurprogramma installeren

Nu het KMDF-stuurprogramma is geïmplementeerd op de doelcomputer, installeert u het stuurprogramma. Wanneer u de doelcomputer eerder hebt ingericht met Visual Studio met behulp van de optie automatische, stelt Visual Studio de doelcomputer in om ondertekende stuurprogramma's uit te voeren als onderdeel van het inrichtingsproces. Nu hoeft u alleen het stuurprogramma te installeren met behulp van het DevCon-hulpprogramma.

  1. Navigeer op de hostcomputer naar de map Hulpprogramma's in uw WDK-installatie en zoek het DevCon-hulpprogramma. Kijk bijvoorbeeld in de volgende map:

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

    Kopieer het DevCon-hulpprogramma naar uw externe computer.

  2. Installeer het stuurprogramma op de doelcomputer door naar de map met de stuurprogrammabestanden te navigeren en vervolgens het DevCon-hulpprogramma uit te voeren.

    1. Hier volgt de algemene syntaxis voor het devcon-hulpprogramma dat u gaat gebruiken om het stuurprogramma te installeren:

      devcon installeren <INF-bestand><hardware-id>

      Het INF-bestand dat is vereist voor het installeren van dit stuurprogramma, is KmdfDriver.inf. Het INF-bestand bevat de hardware-id voor het installeren van het binaire stuurprogramma, KmdfDriver.sys. Zoals u weet, is de hardware-id, die zich in het INF-bestand bevindt, root\KmdfDriver.

    2. Open een opdrachtpromptvenster als beheerder. Navigeer naar de map van het stuurprogrammapakket en voer vervolgens deze opdracht in:

      devcon install kmdfdriver.inf root\kmdfdriver

      Als u een foutbericht krijgt waarin staat dat devcon niet wordt herkend, probeer dan het pad toe te voegen aan het devcon hulpprogramma. Als u deze bijvoorbeeld hebt gekopieerd naar een map op de doelcomputer met de naam C:\Tools, gebruikt u de volgende opdracht:

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

      Er wordt een dialoogvenster weergegeven dat aangeeft dat het teststuurprogramma een niet-ondertekend stuurprogramma is. Selecteer Dit stuurprogramma toch installeren om door te gaan.

      schermopname van waarschuwing over de installatie van stuurprogramma's.

Fouten opsporen in het stuurprogramma

Nu u het KMDF-stuurprogramma op de doelcomputer hebt geïnstalleerd, koppelt u een foutopsporingsprogramma op afstand vanaf de hostcomputer.

  1. Open op de hostcomputer een opdrachtpromptvenster als administrator. Ga naar de directory WinDbg.exe. We gebruiken de x64version van WinDbg.exe van de Windows Driver Kit (WDK) die is geïnstalleerd als onderdeel van de installatie van de Windows-kit. Dit is het standaardpad naar WinDbg.exe:

    C:\Program Files (x86)\Windows Kits\10\Debuggers\x64

  2. Start WinDbg om verbinding te maken met een kernelfoutopsporingssessie op de doelcomputer met behulp van de volgende opdracht. De waarde voor de poort en sleutel moet gelijk zijn aan de waarde die u hebt gebruikt om de doelcomputer in te richten. We gebruiken 50000 voor de poort en 1.2.3.4 voor de sleutel, de waarden die we tijdens de implementatiestap hebben gebruikt. De vlag k geeft aan dat dit een kernelfoutopsporingssessie is.

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

  3. Kies in het menu FoutopsporingPauze. Het foutopsporingsprogramma op de hostcomputer breekt in op de doelcomputer. In het venster Opdracht voor foutopsporingsprogramma ziet u de opdrachtprompt voor kernelfoutopsporing: kd>.

  4. Op dit moment kunt u experimenteren met het foutopsporingsprogramma door opdrachten in te voeren bij de kd> prompt. U kunt bijvoorbeeld de volgende opdrachten proberen:

  5. Als u de doelcomputer opnieuw wilt laten draaien, kiest u Go in het menu Foutopsporing of drukt u op 'g' en vervolgens op ' Enter '.

  6. Als u de foutopsporingssessie wilt stoppen, kiest u Debuggee loskoppelen in het menu Foutopsporing .

    Belangrijk

    Zorg ervoor dat u de opdracht 'go' gebruikt om de doelcomputer opnieuw uit te voeren voordat u het foutopsporingsprogramma afsluit. De doelcomputer reageert niet op uw muis- en toetsenbordinvoer omdat deze nog steeds met het foutopsporingsprogramma praat.

Zie Debug Universal Drivers - Step by Step Lab (Echo Kernel-Mode)voor een gedetailleerd stapsgewijze procedure voor het foutopsporingsproces van stuurprogramma's.

Zie Remote Debugging using WinDbg(WinDbg-) voor meer informatie over foutopsporing op afstand.

Het Driver Module Framework (DMF) gebruiken

De Driver Module Framework (DMF) is een extensie voor WDF die extra functionaliteit biedt voor een ontwikkelaar van WDF-stuurprogramma's. Hiermee kunnen ontwikkelaars elk type WDF-stuurprogramma beter en sneller schrijven.

Met DMF als framework kunt u WDF-objecten maken met de naam DMF-modules. De code voor deze DMF-modules kan worden gedeeld tussen verschillende stuurprogramma's. Daarnaast bundelt DMF een bibliotheek met DMF-modules die we hebben ontwikkeld voor onze stuurprogramma's en waarvan we denken dat ze waardevol zouden zijn voor andere ontwikkelaars van stuurprogramma's.

DMF vervangt WDF niet. DMF is een tweede framework dat wordt gebruikt met WDF. De ontwikkelaar die DMF gebruikt, gebruikt nog steeds WDF en alle primitieven om apparaatstuurprogramma's te schrijven.

Zie Driver Module Framework (DMF)voor meer informatie.