Dela via

Självstudie: Skriva en UNIVERSELL Windows-drivrutin (KMDF) baserat på en mall

Den här artikeln beskriver hur du skriver en Universell Windows-drivrutin med hjälp av Kernel-Mode Driver Framework (KMDF). Du börjar med en Microsoft Visual Studio-mall och distribuerar och installerar sedan drivrutinen på en separat dator.

Förutsättningar

  • Följ stegen för att installera Windows Driver Kit (WDK). Felsökningsverktyg för Windows ingår när du installerar WDK.

  • Installera Visual Studio 2022. När du installerar Visual Studio 2022 väljer du Desktop-utveckling med C++ arbetsbelastning. Under enskilda komponenter lägg till:

    • MSVC v143 – VS 2022 C++ ARM64/ARM64EC Spectre-begränsade bibliotek (Senaste)
    • MSVC v143 – VS 2022 C++ x64/x86 Spectre-mitigationsbibliotek (Senaste versionen)
    • C++ ATL för de senaste v143-byggverktygen med Spectre Mitigations (ARM64/ARM64EC)
    • C++ ATL för de senaste v143-byggverktygen med Spectre Mitigations (x86 & x64)
    • C++ MFC för de senaste v143-byggverktygen med Spectre Mitigations (ARM64/ARM64EC)
    • C++ MFC för de senaste v143-byggverktygen med Spectre Mitigations (x86 & x64)
    • Windows Driver Kit

Skapa och bygg en drivrutin

  1. Öppna Microsoft Visual Studio. På menyn Arkiv väljer du Nytt > Projekt.

  2. I dialogrutan Skapa ett nytt projekt väljer du C++ i den vänstra listrutan, väljer Windows i den mellersta listrutan och väljer Driver i den högra listrutan.

  3. Välj KMDF(Kernel Mode Driver) i listan över projekttyper. Välj Nästa.

    Skärmbild av den nya projektdialogrutan med drivrutinen för kernelläge markerad.

    Tips

    Om du inte hittar drivrutinsprojektmallar i Visual Studio installerades inte WDK Visual Studio-tillägget korrekt. Lös problemet genom att starta Visual Studio Installer, välja Ändra, lägga till Windows Driver Kits på fliken enskild komponent och välj Ändra.

  4. I dialogrutan Konfigurera ditt nya projekt anger du "KmdfDriver" i fältet Projektnamn.

    Notera

    När du skapar en ny KMDF- eller UMDF-drivrutin måste du välja ett drivrutinsnamn med högst 32 tecken. Den här längdgränsen definieras i wdfglobals.h.  

  5. I fältet Plats anger du katalogen där du vill skapa det nya projektet.

  6. Kontrollera Placera lösning och projekt i samma katalog och välj Skapa.

    Skärmbild av dialogrutan projektkonfiguration.

    Visual Studio skapar ett projekt och en lösning. Du kan se dem i fönstret Solution Explorer. (Om Solution Explorer-fönstret inte är synligt väljer du Solution Explorer på menyn Visa .) Lösningen har ett drivrutinsprojekt med namnet KmdfDriver. Om du vill se drivrutins källkoden öppnar du någon av filerna under Källfiler. Driver.c och Device.c är bra platser att börja på.

    Skärmbild av Solution Explorer som visar filerna i drivrutinsprojektet.

  7. I fönstret Solution Explorer väljer du och håller (eller högerklickar) KmdfDriveroch väljer Egenskaper. Gå till Konfigurationsegenskaper > Drivrutinsinställningar > Allmännaoch observera att Målplattform är standardvärdet Universal.

  8. Skapa drivrutinen genom att välja Build Solution på menyn Build. Microsoft Visual Studio visar byggframsteg i produktionsfönstret. (Om utdatafönstret inte visas väljer du Utdata på menyn Visa .)

    Kontrollera att byggutdata innehåller:

    >    Driver is 'Universal'.

    När du kontrollerar att lösningen har skapats kan du stänga Visual Studio.

  9. Om du vill se den inbyggda drivrutinen går du till mappen KmdfDriver i Utforskaren och sedan till x64\Debug\KmdfDriver. Katalogen innehåller följande filer:

    • KmdfDriver.sys--kärnlägesdrivrutinfilen
    • KmdfDriver.inf – en informationsfil som Windows använder när du installerar drivrutinen

Installera drivrutinen

Vanligtvis när du testar och felsöker en drivrutin körs felsökningsprogrammet och drivrutinen på separata datorer. Datorn som kör felsökningsprogrammet kallas värddatoroch den dator som kör drivrutinen kallas måldator. Måldatorn kallas även testdator. Mer information om felsökning av drivrutiner finns i Felsökningsverktyg för Windows.

Hittills har du använt Visual Studio för att skapa en drivrutin på värddatorn. Nu måste du konfigurera en måldator.

  1. Följ anvisningarna i Etablera en dator för drivrutinsdistribution och -testning (WDK 10).

    Tips

    När du följer stegen för att etablera måldatorn automatiskt med hjälp av en nätverkskabel bör du notera porten och nyckeln. Du använder dem senare i felsökningssteget. I det här exemplet använder vi 50000 som port och 1.2.3.4 som nyckel.

    I verkliga felsökningsscenarier för drivrutiner rekommenderar vi att du använder en KDNET-genererad nyckel. Mer information om hur du använder KDNET för att generera en slumpmässig nyckel finns i artikeln Felsöka drivrutiner – Steg för steg-labb (Sysvad Kernel Mode).

  2. Öppna lösningen i Visual Studio på värddatorn. Du kan dubbelklicka på lösningsfilen KmdfDriver.sln i mappen KmdfDriver.

  3. I fönstret Solution Explorer väljer du och håller (eller högerklickar) projektet KmdfDriver och väljer Egenskaper.

  4. I fönstret KmdfDriver Package Property Pages, i det vänstra fönstret, går du till Konfigurationsegenskaper > Drivrutinsinstallation > Distribution.

  5. Kontrollera Ta bort tidigare drivrutinsversioner innan distributionen.

  6. För Fjärrdatornamnväljer du namnet på den dator som du konfigurerade för testning och felsökning. I den här övningen använder vi en dator med namnet MyTestComputer.

  7. Välj Uppdatering av maskinvaru-ID-drivrutinoch ange maskinvaru-ID för drivrutinen. I den här övningen är maskinvaru-ID:t Root\KmdfDriver. Välj OK.

    skärmbild av fönstret för paketegenskapssidor för kmdfdriver, där installation av distributionsdrivrutin är vald

    Notera

    I den här övningen identifierar maskinvaru-ID:t inte någon riktig maskinvara. Den identifierar en imaginär enhet som ges en plats i enhetsträdet som ett barn av rotnoden. För verklig maskinvara väljer du inte Uppdatering av maskinvaru-ID-drivrutin. i stället väljer du Installera och verifiera. Du ser maskinvaru-ID:t i inf-filen (drivrutinsinformation). I fönstret Solution Explorer går du till KmdfDriver > Driver Files och dubbelklickar på KmdfDriver.inf. Maskinvaru-ID:t finns under [Standard.NT$ARCH$].

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

  8. På menyn Build väljer du Deploy Solution. Visual Studio kopierar automatiskt de filer som krävs för att installera och köra drivrutinen till måldatorn.

    När du distribuerar en drivrutin kopieras drivrutinsfilerna till mappen %Systemdrive%\drivertest\drivers på testdatorn. Om något går fel under distributionen kan du kontrollera om filerna kopieras till testdatorn. Kontrollera att filerna .inf, .cat, test cert och .sys och andra nödvändiga filer finns i mappen %systemdrive%\drivertest\drivers.

    Mer information om hur du distribuerar drivrutiner finns i Distribuera en drivrutin till en testdator.

Installera drivrutinen

Nu när kmdf-drivrutinen har distribuerats till måldatorn installerar du drivrutinen. När du tidigare etablerade måldatorn med Visual Studio med hjälp av alternativet automatisk konfigurerade Visual Studio måldatorn för att köra testsignerade drivrutiner som en del av etableringsprocessen. Nu behöver du bara installera drivrutinen med devcon-verktyget.

  1. På värddatorn navigerar du till mappen Verktyg i WDK-installationen och letar upp DevCon-verktyget. Titta till exempel i följande mapp:

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

    Kopiera DevCon-verktyget till fjärrdatorn.

  2. Installera drivrutinen på måldatorn genom att navigera till mappen som innehåller drivrutinsfilerna och sedan köra DevCon-verktyget.

    1. Här är den allmänna syntaxen för devcon-verktyget som du använder för att installera drivrutinen:

      devcon install <INF-fil><maskinvaru-ID>

      DEN INF-fil som krävs för att installera drivrutinen är KmdfDriver.inf. INF-filen innehåller maskinvaru-ID:t för att installera drivrutinsbinärfilen KmdfDriver.sys. Kom ihåg att maskinvaru-ID:t, som finns i INF-filen, är Root\KmdfDriver.

    2. Öppna ett kommandotolkfönster som administratör. Gå till mappen för drivrutinspaketet och ange sedan följande kommando:

      devcon installera kmdfdriver.inf root\kmdfdriver

      Om du får ett felmeddelande om att devcon inte identifieras, kan du prova att lägga till sökvägen till verktyget devcon. Om du till exempel kopierade den till en mapp på måldatorn med namnet C:\Toolskan du prova att använda följande kommando:

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

      En dialogruta visas och anger att testdrivrutinen är en osignerad drivrutin. Välj Installera den här drivrutinen ändå för att fortsätta.

      skärmbild av varning om drivrutinsinstallation.

Felsöka drivrutinen

Nu när du har installerat KMDF-drivrutinen på måldatorn ansluter du ett felsökningsprogram via fjärranslutning från värddatorn.

  1. Öppna kommandotolken som administratör på värddatorn. Byt till katalogen WinDbg.exe. Använd x64version av WinDbg.exe från Windows Driver Kit (WDK) som installerades som en del av Windows Kit-installationen. Här är standardsökvägen till WinDbg.exe:

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

  2. Starta WinDbg för att ansluta till en kernel-felsökningssession på måldatorn med hjälp av följande kommando. Värdet för porten och nyckeln ska vara detsamma som det du använde för att konfigurera måldatorn. Vi använder 50000 för porten och 1.2.3.4 för nyckeln, de värden som vi använde under distributionssteget. Flaggan k anger att det här är en kernel-felsökningssession.

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

  3. På menyn Felsöka väljer du Break. Felsökningsprogrammet på värddatorn bryter sig in på måldatorn. I fönstret Felsökningskommando kan du se kommandotolken för kernelfelsökning: kd>.

  4. Nu kan du experimentera med felsökningsprogrammet genom att ange kommandon i kd-prompten> . Du kan till exempel prova följande kommandon:

  5. Om du vill låta måldatorn köras igen väljer du Gå från menyn Felsök eller trycker på "g" och trycker sedan på "retur".

  6. Om du vill stoppa felsökningssessionen väljer du Koppla från debuggee- från menyn Felsökning.

    Viktig

    Kontrollera att du använder kommandot "go" för att låta måldatorn köras igen innan du avslutar felsökningsprogrammet, eller så svarar måldatorn fortfarande inte på mus- och tangentbordsindata eftersom den fortfarande pratar med felsökningsprogrammet.

En detaljerad stegvis genomgång av felsökningsprocessen för drivrutiner finns i Felsöka universella drivrutiner – Steg för steg-labb (Echo Kernel-Mode).

Mer information om fjärrfelsökning finns i Fjärrfelsökning med WinDbg.

Användning av Driver Module Framework (DMF)

Driver Module Framework (DMF) är ett tillägg till WDF som möjliggör extra funktioner för en WDF-drivrutinsutvecklare. Det hjälper utvecklare att skriva alla typer av WDF-drivrutin bättre och snabbare.

Med DMF som ramverk kan du skapa WDF-objekt som kallas DMF-moduler. Koden för dessa DMF-moduler kan delas mellan olika drivrutiner. Dessutom paketar DMF ett bibliotek med DMF-moduler som vi har utvecklat för våra drivrutiner och som vi anser skulle ge värde till andra drivrutinsutvecklare.

DMF ersätter inte WDF. DMF är ett andra ramverk som används med WDF. Utvecklaren som använder DMF använder fortfarande WDF och alla dess primitiver för att skriva enhetsdrivrutiner.

Mer information finns i Driver Module Framework (DMF).

  • Last updated on