Jak napsat první klientský ovladač USB (KMDF)

V tomto článku použijete šablonu ovladače USB Kernel-Mode , která je součástí sady Microsoft Visual Studio, k zápisu jednoduchého klientského ovladače založeného na režimu jádra (KMDF). Po sestavení a instalaci klientského ovladače zobrazíte klientský ovladač v Správce zařízení a zobrazíte výstup ovladače v ladicím programu.

Vysvětlení zdrojového kódu vygenerovaného šablonou najdete v tématu Vysvětlení kódu šablony KMDF pro ovladač klienta USB.

Požadavky

Pro vývoj, ladění a instalaci ovladače režimu jádra potřebujete dva počítače:

• Hostitelský počítač se systémem Windows 7 nebo novější verzí operačního systému Windows. Hostitelský počítač je vaše vývojové prostředí, ve kterém píšete a ladíte ovladač.
• Cílový počítač se systémem Windows Vista nebo novější verzí systému Windows. Cílový počítač má ovladač v režimu jádra, který chcete ladit.

Než začnete, ujistěte se, že splňujete následující požadavky:

Softwarové požadavky

• Hostitelský počítač hostuje vaše vývojové prostředí a má Sadu Visual Studio.
• Váš hostitelský počítač má nejnovější sadu Windows Driver Kit (WDK). Sada obsahuje hlavičky, knihovny, nástroje, dokumentaci a nástroje pro ladění potřebné k vývoji, sestavení a ladění ovladače KMDF. Pokud chcete získat nejnovější verzi WDK, přečtěte si téma Stažení sady Windows Driver Kit (WDK).
• Váš hostitelský počítač má nejnovější verzi nástrojů pro ladění pro Windows. Nejnovější verzi můžete získat z WDK nebo můžete stáhnout a nainstalovat nástroje ladění pro systém Windows.
• Cílový počítač používá systém Windows Vista nebo novější verzi systému Windows.
• Vaše hostitelské a cílové počítače jsou nakonfigurované pro ladění jádra. Další informace naleznete v tématu Nastavení síťového připojení v sadě Visual Studio.

Požadavky na hardware

Získejte zařízení USB, pro které budete psát klientský ovladač. Ve většině případů máte k dispozici zařízení USB a jeho hardwarovou specifikaci. Specifikace popisuje možnosti zařízení a podporované příkazy dodavatele. Pomocí specifikace můžete určit funkčnost ovladače USB a související rozhodnutí o návrhu.

Pokud s vývojem ovladačů USB začínáte, můžete pomocí výukové sady OSR USB FX2 studovat vzorky USB, které jsou součástí WDK. Výukové sady můžete získat z OSR Online. Obsahuje zařízení USB FX2 a všechny požadované hardwarové specifikace pro implementaci klientského ovladače.

Můžete také získat zařízení Microsoft USB Test Tool (MUTT). Hardware MUTT lze zakoupit od JJG Technologies. Zařízení nemá nainstalovaný firmware. Chcete-li nainstalovat firmware, stáhněte balíček softwaru MUTT z tohoto webu a spusťte MUTTUtil.exe. Další informace najdete v dokumentaci, která je součástí balíčku.

Doporučené zdroje informací

• Koncepty pro všechny vývojáře ovladačů
• Hardwarové uzly a zásobníky zařízení
• Začínáme s ovladači ve Windows
• Kernel-Mode Driver Framework
• Vývoj ovladačů s Windows Driver Foundation, napsal Penny Orwick a Guy Smith. Další informace naleznete v tématu Vývoj ovladačů pomocí WDF.

Krok 1: Vygenerování kódu ovladače KMDF pomocí šablony ovladače USB sady Visual Studio

Pokyny ke generování kódu ovladače KMDF najdete v krocích v části Zápis ovladače KMDF na základě šablony.

Pro kód specifický pro USB vyberte v sadě Visual Studio následující možnosti:

1. V dialogovém okně Nový projekt do vyhledávacího pole v horní části zadejte USB.
2. V prostředním podokně vyberte ovladač režimu jádra, USB (KMDF).
3. Vyberte Další.
4. Zadejte název projektu, zvolte umístění pro uložení a vyberte Vytvořit.

Následující snímky obrazovky ukazují dialogové okno Nový projekt pro šablonu ovladače USB Kernel-Mode .

Tento článek předpokládá, že název projektu sady Visual Studio je "MyUSBDriver_". Obsahuje následující soubory:

Soubory	Popis
Public.h	Poskytuje běžné deklarace sdílené klientským ovladačem a uživatelskými aplikacemi, které komunikují se zařízením USB.
<název projektu>.inf	Obsahuje informace potřebné k instalaci klientského ovladače do cílového počítače.
Trace.h	Deklaruje funkce trasování a makra.
Driver.h; Driver.c	Deklaruje a definuje vstupní body ovladače a rutiny zpětného volání událostí.
Device.h; Device.c	Deklaruje a definuje rutinu zpětného volání událostí pro událost přípravy hardwaru.
Queue.h; Queue.c	Deklaruje a definuje rutinu zpětného volání události pro událost vyvolanou objektem fronty rozhraní.

Krok 2: Úprava souboru INF pro přidání informací o zařízení

Před sestavením ovladače je nutné upravit soubor INF šablony s informacemi o vašem zařízení, konkrétně řetězec ID hardwaru.

V Průzkumníku řešení v části Soubory ovladačů poklikejte na soubor INF.

V souboru INF můžete zadat informace, jako je výrobce a název poskytovatele, třída nastavení zařízení atd. Jednou z informací, které musíte zadat, je hardwarový identifikátor vašeho zařízení.

Zadání řetězce ID hardwaru:

1. Připojte zařízení USB k hostitelskému počítači a nechte systém Windows vytvořit výčet zařízení.

2. Otevřete Správce zařízení a otevřete vlastnosti zařízení.

3. Na kartě Podrobnosti vyberte Hardward Ids v části Vlastnost.

   ID hardwaru zařízení se zobrazí v seznamu. Vyberte a podržte (nebo klikněte pravým tlačítkem) a zkopírujte řetězec ID hardwaru.

4. V následujícím řádku nahraďte USB\VID_vvvv&PID_pppp řetězcem ID hardwaru.

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

Krok 3: Sestavení kódu klientského ovladače USB

Jak vytvořit ovladač:

1. Otevřete projekt nebo řešení ovladače v sadě Visual Studio
2. V Průzkumníku řešení vyberte a podržte řešení (nebo na ho klikněte pravým tlačítkem myši) a vyberte Configuration Manager.
3. V Nástroji Configuration Manager vyberte konfiguraci aktivního řešení (například ladění nebo vydání) a aktivní platformu řešení (například Win32), která odpovídá typu sestavení, které vás zajímá.
4. V nabídce Build vyberte Build Solution.

Další informace naleznete v tématu Sestavení ovladače.

Krok 4: Konfigurace počítače pro testování a ladění

Chcete-li otestovat a ladit ovladač, spusťte ladicí program na hostitelském počítači a ovladač na cílovém počítači. Zatím jste pomocí sady Visual Studio na hostitelském počítači vytvořili ovladač. Dále je potřeba nakonfigurovat cílový počítač. Pokud chcete nakonfigurovat cílový počítač, postupujte podle pokynů v tématu Zřízení počítače pro nasazení ovladačů a testování.

Krok 5: Povolit trasování pro ladění jádra

Kód šablony obsahuje několik trasovacích zpráv (TraceEvents), které vám můžou pomoct sledovat volání funkcí. Všechny funkce ve zdrojovém kódu obsahují trasovací zprávy, které označují vstup a ukončení rutiny. V případě chyb obsahuje zpráva trasování kód chyby a smysluplný řetězec. Protože je pro projekt ovladače povoleno trasování WPP, soubor symbolů PDB vytvořený během procesu sestavení obsahuje pokyny k formátování zpráv trasování. Pokud nakonfigurujete hostitelský a cílový počítač pro trasování WPP, ovladač může odesílat trasovací zprávy do souboru nebo do ladicího programu.

Konfigurace hostitelského počítače pro trasování WPP:

1. Soubory trasovací zprávy formátu (TMF) vytvoříte extrahováním instrukcí formátování trasovacích zpráv ze souboru symbolů PDB.

   K vytvoření souborů TMF můžete použít Tracepdb.exe. Nástroj se nachází ve složce instalace<>sadyWindows Kits\10.0\bin\<architektura> v rámci složky WDK. Následující příkaz vytvoří soubory TMF pro projekt ovladače.

   tracepdb -f <PDBFiles> -p <TMFDirectory>

   Možnost -f určuje umístění a název souboru symbolů PDB. Možnost -p určuje umístění souborů TMF vytvořených službou Tracepdb. Další informace naleznete v tématu Příkazy Tracepdb.

   V zadaném umístění se zobrazí tři soubory (jeden na soubor .c v projektu). Udělují se jim názvy souborů GUID.

2. V ladicím nástroji napište následující příkazy:

   1. .load Wmitrace

      Načte rozšíření Wmitrace.dll.

   2. .řetěz

      Ověřte, že je načteno rozšíření ladicího programu.

   3. !wmitrace.searchpath +<Umístění souboru TMF>

      Přidejte umístění souborů TMF do hledací cesty rozšíření ladicího programu.

      Výstup bude vypadat nějak takto:

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

Abyste nakonfigurovali svůj cílový počítač pro trasování WPP, postupujte takto:

1. Ujistěte se, že v cílovém počítači máte nástroj Tracelog. Nástroj se nachází ve složce <install_folder>Windows Kits\8.0\Tools\<arch> ve WDK. Další informace naleznete v tématu Syntaxe příkazu Tracelog.

2. Otevřete příkazové okno a spusťte je jako správce.

3. Zadejte následující příkaz:

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

   Příkaz spustí relaci trasování s názvem MyTrace.

   Argument guid určuje identifikátor GUID zprostředkovatele trasování, což je klientský ovladač. Identifikátor GUID můžete získat z Trace.h v projektu Visual Studio Professional 2019. Jako další možnost můžete zadat následující příkaz a zadat identifikátor GUID v souboru .guid. Soubor obsahuje identifikátor GUID ve formátu spojovníku:

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

   Trasování můžete zastavit zadáním tohoto příkazu:

   tracelog -stop MyTrace

Krok 6: Nasazení ovladače na cílový počítač

1. V okně Průzkumníka řešení vyberte a podržte (nebo klikněte pravým tlačítkem) na *<název> projektu*Balíček a zvolte Vlastnosti.
2. V levém podokně přejděte na Vlastnosti konfigurace > Instalace ovladače > Nasazení.
3. Zkontrolujte povolení nasazení a zkontrolujte import do úložiště ovladačů.
4. Jako název vzdáleného počítače zadejte název cílového počítače.
5. Vyberte Nainstalovat a ověřit.
6. Vyberte OK.
7. V nabídce Ladění zvolte Spustit laděnínebo stiskněte F5 na klávesnici.

Poznámka:

Nezadávejte ID hardwaru vašeho zařízení v části Aktualizace ovladače ID hardwaru. ID hardwaru musí být zadáno pouze v souboru s informacemi o ovladači (INF).

Další informace o nasazení ovladače do cílového systému v sadě Visual Studio naleznete v tématu Nasazení ovladače do testovacího počítače.

Ovladač můžete také ručně nainstalovat do cílového počítače pomocí Správce zařízení. Pokud chcete ovladač nainstalovat z příkazového řádku, jsou k dispozici tyto nástroje:

• PnPUtil

  Tento nástroj se dodává s Windows. Je ve Windows\System32. Tento nástroj můžete použít k přidání ovladače do úložiště ovladačů.

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

  Další informace naleznete v tématu PnPUtil Příklady.

• Aktualizace DevCon

  Tento nástroj je součástí WDK. Můžete ho použít k instalaci a aktualizaci ovladačů.

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

Krok 7: Zobrazení ovladače ve Správci zařízení

1. Zadáním následujícího příkazu otevřete Správce zařízení:

   devmgmt
   

2. Ověřte, že Správce zařízení zobrazuje položku pro následující prvek:

   Ukázky

   MyUSBDriver_Device

Krok 8: Zobrazení výstupu v ladicím programu

Visual Studio nejprve zobrazí průběh v okně Výstup . Pak se otevře příkazové okno ladicího programu. Ověřte, že se v ladicím programu na hostitelském počítači zobrazují trasovací zprávy. Výstup by měl vypadat takto, kde "MyUSBDriver_" je název modulu ovladače:

[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

Související témata

• Pochopení kódu šablony KMDF pro USB klientský ovladač
• Začínáme s vývojem klientských ovladačů USB