Så här skriver du din första USB-klientdrivrutin (KMDF)

I den här artikeln använder du mallen USB Kernel-Mode Driver som medföljer Microsoft Visual Studio för att skriva en enkel kmdf-baserad klientdrivrutin (kernel-mode driver framework). När du har skapat och installerat klientdrivrutinen visar du klientdrivrutinen i Device Manager och visar drivrutinsutdata i ett felsökningsprogram.

En förklaring av källkoden som genereras av mallen finns i Förstå KMDF-mallkoden för en USB-klientdrivrutin.

Förutsättningar

För att utveckla, felsöka och installera en drivrutin i kernelläge behöver du två datorer:

• En värddator som kör Windows 7 eller en senare version av Windows-operativsystemet. Värddatorn är din utvecklingsmiljö, där du skriver och felsöker drivrutinen.
• En måldator som kör Windows Vista eller en senare version av Windows. Måldatorn har den drivrutin i läge för kärnan som du vill felsöka.

Kontrollera att du uppfyller följande krav innan du börjar:

Programvarukrav

• Värddatorn är värd för utvecklingsmiljön och har Visual Studio.
• Värddatorn har det senaste Windows Driver Kit (WDK). Paketet innehåller rubriker, bibliotek, verktyg, dokumentation och de felsökningsverktyg som krävs för att utveckla, skapa och felsöka en KMDF-drivrutin. Information om hur du hämtar den senaste versionen av WDK finns i Ladda ned Windows Driver Kit (WDK).
• Värddatorn har den senaste versionen av felsökningsverktygen för Windows. Du kan hämta den senaste versionen från WDK eller så kan du Ladda ned och installera felsökningsverktyg för Windows.
• Måldatorn kör Windows Vista eller en senare version av Windows.
• Värd- och måldatorerna har konfigurerats för kernel-felsökning. Mer information finns i Konfigurera en nätverksanslutning i Visual Studio.

Maskinvarukrav

Hämta en USB-enhet som du kommer att skriva klientdrivrutinen för. I de flesta fall får du en USB-enhet och dess maskinvaruspecifikation. Specifikationen beskriver enhetsfunktioner och de leverantörskommandon som stöds. Använd specifikationen för att fastställa funktionerna i USB-drivrutinen och de relaterade designbesluten.

Om du inte har använt USB-drivrutinsutveckling tidigare använder du OSR USB FX2-utbildningspaketet för att studera USB-exempel som ingår i WDK. Du kan hämta utbildningspaketet från OSR Online. Den innehåller USB FX2-enheten och alla nödvändiga maskinvaruspecifikationer för att implementera en klientdrivrutin.

Du kan också hämta enheter såsom Microsoft USB-testverktyg (MUTT). MUTT-maskinvara kan köpas från JJG Technologies. Enheten har inte installerad inbyggd programvara installerad. För att installera firmware, ladda ner MUTT-programvarupaketet från den här webbplatsen och kör MUTTUtil.exe. Mer information finns i dokumentationen som ingår i paketet.

Rekommenderad läsning

• begrepp för alla drivrutinsutvecklare
• Enhetsnoder och enhetsstackar
• Kom igång med drivrutiner i Windows
• Kernel-Mode Driver Framework
• Utveckla drivrutiner med Windows Driver Foundation, skriven av Penny Orwick och Guy Smith. Mer information finns i Utveckla drivrutiner med WDF-.

Steg 1: Generera KMDF-drivrutinskoden med hjälp av Visual Studio USB-drivrutinsmallen

Anvisningar om hur du genererar KMDF-drivrutinskod finns i stegen i Skriva en KMDF-drivrutin baserat på en mall.

För USB-specifik kod väljer du följande alternativ i Visual Studio:

1. I dialogrutan Nytt projekt skriver du USB i sökrutan längst upp.
2. I det mellersta fönstret väljer du kernellägesdrivrutin, USB (KMDF).
3. Välj Nästa.
4. Ange ett projektnamn, välj en plats för att spara och välj Skapa.

Följande skärmbilder visar dialogrutan Nytt projekt för mallen USB Kernel-Mode Driver.

Den här artikeln förutsätter att namnet på Visual Studio-projektet är "MyUSBDriver_". Den innehåller följande filer:

Steg 2: Ändra INF-filen för att lägga till information om enheten

Innan du skapar drivrutinen måste du ändra INF-mallfilen med information om enheten, särskilt maskinvaru-ID-strängen.

Dubbelklicka på INF-filen under Driver Filesi Solution Explorer.

I INF-filen kan du ange information som tillverkare och leverantörsnamn, enhetsinstallationsklassen och så vidare. En information som du måste ange är enhetens maskinvaruidentifierare.

Så här anger du maskinvaru-ID-strängen:

1. Anslut DIN USB-enhet till värddatorn och låt Windows räkna upp enheten.

2. Öppna Device Manager och öppna egenskaper för enheten.

3. På fliken Information väljer du hårdvaru-ID:er under Egenskap.

   Enhetens maskinvaru-ID visas i listrutan. Välj och håll (eller högerklicka) och kopiera maskinvaru-ID-strängen.

4. Ersätt USB\VID_vvvv&PID_pppp i följande rad med maskinvaru-ID-strängen.

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

Steg 3: Skapa USB-klientdrivrutinskoden

Så här skapar du drivrutinen:

1. Öppna drivrutinsprojektet eller lösningen i Visual Studio
2. Välj och håll (eller högerklicka) lösningen i Solution Explorer och välj Configuration Manager.
3. Från Configuration Managerväljer du Active Solution Configuration (till exempel Debug eller Release) och Active Solution Platform (till exempel Win32) som motsvarar den typ av version som du är intresserad av.
4. På menyn Build väljer du Build Solution.

Mer information finns i Skapa en drivrutin.

Steg 4: Konfigurera en dator för testning och felsökning

Om du vill testa och felsöka en drivrutin kör du felsökningsprogrammet på värddatorn och drivrutinen på måldatorn. Hittills har du använt Visual Studio på värddatorn för att skapa en drivrutin. Därefter måste du konfigurera en måldator. Om du vill konfigurera en måldator följer du anvisningarna i Etablera en dator för drivrutinsdistribution och testning.

Steg 5: Aktivera spårning för kernel-felsökning

Mallkoden innehåller flera spårningsmeddelanden (TraceEvents) som kan hjälpa dig att spåra funktionsanrop. Alla funktioner i källkoden innehåller spårningsmeddelanden som markerar in- och utmatningen av en rutin. För fel innehåller spårningsmeddelandet felkoden och en meningsfull sträng. Eftersom WPP-spårning är aktiverat för drivrutinsprojektet innehåller PDB-symbolfilen som skapades under byggprocessen formateringsinstruktioner för spårningsmeddelanden. Om du konfigurerar värd- och måldatorerna för WPP-spårning kan drivrutinen skicka spårningsmeddelanden till en fil eller felsökningsprogrammet.

Så här konfigurerar du värddatorn för WPP-spårning:

1. Skapa TMF-filer (Trace Message Format) genom att extrahera formateringsinstruktioner för spårningsmeddelanden från PDB-symbolfilen.

   Du kan använda Tracepdb.exe för att skapa TMF-filer. Verktyget finns i <installationsmappen>Windows Kits\10.0\bin\<arkitektur> mappen för WDK. Följande kommando skapar TMF-filer för drivrutinsprojektet.

   tracepdb -f <PDBFiles> -p <TMFDirectory>

   Alternativet -f anger platsen och namnet på PDB-symbolfilen. Alternativet -p anger platsen för de TMF-filer som skapas av Tracepdb. Mer information finns i Tracepdb-kommandon.

   På den angivna platsen visas tre filer (en per .c-fil i projektet). De får GUID-filnamn.

2. I felsökningsprogrammet skriver du följande kommandon:

   1. .load Wmitrace

      Läser in tillägget Wmitrace.dll.

   2. .chain

      Kontrollera att felsökningstillägget har lästs in.

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

      Lägg till platsen för TMF-filerna i sökvägen för felsökningstillägget.

      Utdata liknar följande:

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

Så här konfigurerar du måldatorn för WPP-spårning:

1. Kontrollera att du har verktyget Tracelog på måldatorn. Verktyget finns i mappen <install_folder>Windows Kits\8.0\Tools\<arch> mappen för WDK. Mer information finns i Tracelog Command Syntax.

2. Öppna ett kommandofönster och kör som administratör.

3. Skriv följande kommando:

   spårningslogg -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

   Kommandot startar en spårningssession med namnet MyTrace.

   Argumentet guid anger GUID för spårningsprovidern, som är klientdrivrutinen. Du kan hämta GUID från Trace.h i Visual Studio Professional 2019-projektet. Som ett annat alternativ kan du skriva följande kommando och ange GUID i en GUID-fil. Filen innehåller GUID i bindestrecksformat:

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

   Du kan stoppa spårningssessionen genom att skriva följande kommando:

   spårningslogg -stop MyTrace

Steg 6: Distribuera drivrutinen på måldatorn

1. I fönstret Solution Explorer väljer du och håller (eller högerklickar) projektnamnet *<>*Package och väljer Egenskaper.
2. I den vänstra rutan går du till Konfigurationsegenskaper > Drivrutinsinstallation > Distribution.
3. Kontrollera Aktivera distribution och kontrollera Importera till drivrutinsarkivet.
4. För Fjärrdatornamnanger du namnet på måldatorn.
5. Välj Installera och verifiera.
6. Välj Ok.
7. På menyn Felsökning väljer du Starta felsökningeller trycker på F5 på tangentbordet.

Mer information om hur du distribuerar drivrutinen till målsystemet i Visual Studio finns i Distribuera en drivrutin till en testdator.

Du kan också installera drivrutinen manuellt på måldatorn med hjälp av Enhetshanteraren. Om du vill installera drivrutinen från en kommandotolk är dessa verktyg tillgängliga:

• PnPUtil

  Det här verktyget levereras med Windows. Den finns i Windows\System32. Du kan använda det här verktyget för att lägga till drivrutinen i drivrutinsarkivet.

  C:\>pnputil /a m:\MyDriver_.inf
  Microsoft PnP Utility
  
  Processing inf : MyDriver_.inf
  Driver package added successfully.
  Published name : oem22.inf
  

  Mer information finns i PnPUtil-exempel.

• DevCon Uppdatering

  Det här verktyget levereras med WDK. Du kan använda den för att installera och uppdatera drivrutiner.

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

Steg 7: Visa drivrutinen i Enhetshanteraren

1. Ange följande kommando för att öppna Device Manager:

   devmgmt
   

2. Kontrollera att Device Manager- visar en nod för följande nod:

   Exempel

   MyUSBDriver_Device

Steg 8: Visa utdata i felsökningsprogrammet

Visual Studio visar först förloppet i fönstret Utdata. Sedan öppnas felsökningsprogrammets omedelbara fönster. Kontrollera att spårningsmeddelanden visas i felsökningsprogrammet på värddatorn. Utdata bör se ut så här, där "MyUSBDriver_" är namnet på drivrutinsmodulen:

[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

Relaterade ämnen

• Förstå KMDF-mallkoden för en USB-klientdrivrutin
• Komma igång med utveckling av USB-klientdrivrutiner