Uw eerste USB-clientstuurprogramma schrijven (UMDF)

In dit artikel gebruik je de User Mode Driver, USB (UMDF V2)-sjabloon van Microsoft Visual Studio 2022 om een UMDF-gebaseerd clientstuurprogramma (user-mode driver framework) te schrijven. Nadat u het clientstuurprogramma hebt gebouwd en geïnstalleerd, bekijkt u het clientstuurprogramma in Device Manager en bekijkt u de uitvoer van het stuurprogramma in een foutopsporingsprogramma.

UMDF (het framework in dit artikel genoemd) is gebaseerd op het component object model (COM). Elk frameworkobject moet standaard IUnknown en de bijbehorende methoden, QueryInterface, AddRef en Release implementeren. De addRef- en releasemethoden beheren de levensduur van het object, zodat het clientstuurprogramma het aantal verwijzingen niet hoeft te onderhouden. Met de methode QueryInterface kan het clientstuurprogramma interfacepointers ophalen naar andere frameworkobjecten in het WDF-objectmodel (Windows Driver Frameworks). Framework-objecten voeren ingewikkelde stuurprogrammataken uit en werken met Windows. Bepaalde frameworkobjecten maken interfaces beschikbaar waarmee een clientstuurprogramma kan communiceren met het framework.

Een clientstuurprogramma op basis van UMDF wordt geïmplementeerd als een IN-process COM-server (DLL) en C++ is de voorkeurstaal voor het schrijven van een clientstuurprogramma voor een USB-apparaat. Normaal gesproken implementeert het clientstuurprogramma verschillende interfaces die door het framework worden weergegeven. Dit artikel verwijst naar een door het clientstuurprogramma gedefinieerde klasse die frameworkinterfaces implementeert als een callback-klasse. Nadat deze klassen zijn geïnstantieerd, worden de resulterende callback-objecten gekoppeld aan bepaalde frameworkobjecten. Deze samenwerking biedt het clientstuurprogramma de mogelijkheid om te reageren op apparaat- of systeemgerelateerde gebeurtenissen die door het framework zijn gerapporteerd. Wanneer Windows het framework over bepaalde gebeurtenissen op de hoogte stelt, roept het framework de callback van het clientstuurprogramma aan, indien beschikbaar. Anders gaat het framework verder met de standaardverwerking van de gebeurtenis. De sjablooncode definieert de callbackklassen voor stuurprogramma's, apparaten en wachtrijen.

Zie Inzicht verkrijgen in de UMDF-sjablooncode voor USB-clientstuurprogramma’s voor een uitleg over de broncode die door de sjabloon is gegenereerd.

Voordat u begint

Voor het ontwikkelen, opsporen van fouten en het installeren van een stuurprogramma voor de gebruikersmodus hebt u twee computers nodig:

• Een hostcomputer met Windows 10 of een latere versie van het Windows-besturingssysteem. De hostcomputer is uw ontwikkelomgeving, waar u het stuurprogramma schrijft en fouten opspoort.
• Een doelcomputer met de versie van het besturingssysteem waarop u uw stuurprogramma wilt testen, bijvoorbeeld Windows 11, versie 22H2. De doelcomputer heeft het gebruikersmodusstuurprogramma dat u wilt debuggen en een van de debuggers.

In sommige gevallen, waarbij de host- en doelcomputers dezelfde versie van Windows uitvoeren, kunt u slechts één computer met Windows 10 of een nieuwere versie van Windows hebben. In dit artikel wordt ervan uitgegaan dat u twee computers gebruikt voor het ontwikkelen, opsporen van fouten en het installeren van het stuurprogramma voor de gebruikersmodus.

Voordat u begint, moet u ervoor zorgen dat u aan de volgende vereisten voldoet:

Softwarevereisten

• Uw hostcomputer heeft Visual Studio 2022.

• Uw hostcomputer heeft de nieuwste Windows Driver Kit (WDK) voor Windows 11, versie 22H2.

  De kit bevat headers, bibliotheken, hulpprogramma's, documentatie en de hulpprogramma's voor foutopsporing die nodig zijn voor het ontwikkelen, bouwen en opsporen van fouten in een USB-clientstuurprogramma. U kunt de nieuwste versie van de WDK downloaden van How to Get the WDK.

• Uw hostcomputer heeft de nieuwste versie van foutopsporingsprogramma's voor Windows. U kunt de nieuwste versie downloaden van de WDK of Download- en installatietools voor Windows voor foutopsporing installeren.

• Als u twee computers gebruikt, moet u de host en doelcomputers configureren voor foutopsporing in de gebruikersmodus. Zie Het instellen van User-Mode foutopsporing in Visual Studio voor meer informatie.

Hardwarevereisten

Haal een USB-apparaat op waarvoor u het clientstuurprogramma schrijft. In de meeste gevallen krijgt u een USB-apparaat en de bijbehorende hardwarespecificatie. In de specificatie worden de mogelijkheden van apparaten en de ondersteunde leveranciersopdrachten beschreven. Gebruik de specificatie om de functionaliteit van het USB-stuurprogramma en de bijbehorende ontwerpbeslissingen te bepalen.

Als u geen kennis hebt met de ontwikkeling van USB-stuurprogramma's, gebruikt u de OSR USB FX2 Learning Kit om USB-monsters te bestuderen die zijn opgenomen in de WDK. Het bevat het USB FX2-apparaat en alle vereiste hardwarespecificaties voor het implementeren van een clientstuurprogramma.

Aanbevolen literatuur

• Concepten voor alle ontwikkelaars van stuurprogramma's
• Apparaatknooppunten en apparaatstapels
• Aan de slag met stuurprogramma's in Windows
• User-Mode Driver Framework
• Ontwikkelen van stuurprogramma's met Windows Driver Foundation, geschreven door Penny Orwick en Guy Smith. Zie Stuurprogramma's ontwikkelen met WDF voor meer informatie.

Stap 1: De stuurprogrammacode genereren

Zie Een UMDF-stuurprogramma schrijven op basis van een sjabloon voor meer informatie over het schrijven van UMDF-stuurprogrammacode.

Voor USB-specifieke code selecteert u de volgende opties in Visual Studio 2022

1. Typ in het dialoogvenster Nieuw project in het zoekvak bovenaan USB.
2. Selecteer in het middelste deelvenster het stuurprogramma van de gebruikersmodus, USB (UMDF V2).
3. Kies Volgende.
4. Voer een projectnaam in, kies een opslaglocatie en selecteer Maak.

In de volgende schermafbeeldingen ziet u het dialoogvenster Nieuw project voor de sjabloon USB-User-Mode stuurprogramma .

In dit artikel wordt ervan uitgegaan dat de naam van het project MyUSBDriver_UMDF_ is. Het bevat de volgende bestanden:

Bestanden	Beschrijving
Driver.h; Driver.c	Bevat de implementatie van het ingangspunt van de stuurprogrammamodule. DriverEntry en WDFDRIVER gerelateerde functionaliteit en callbacks.
Device.h; Device.c	WDFDEVICE en WDFUSBDEVICE gerelateerde functionaliteit en callbacks.
Queue.h; Queue.c	Aan WDFQUEUE gerelateerde functionaliteit en callbacks.
Trace.h	Hiermee definieert u de GUID van de apparaatinterface. Ook worden traceringsfuncties en macro's gedeclareerd.
<projectnaam>.inf	INF-bestand dat is vereist voor het installeren van het clientstuurprogramma op de doelcomputer.

Stap 2: Informatie over uw apparaat toevoegen

Voordat u het stuurprogramma bouwt, moet u informatie over uw apparaat toevoegen, met name de hardware-id. De hardware-id opgeven:

1. Klik in het venster Solution Explorer met de rechtermuisknop op MyUSBDriver_UMDF_ en kies Eigenschappen.
2. Ga in het venster MyUSBDriver_UMDF_ eigenschappenpagina's naar Configuratie-eigenschappen > Stuurprogramma-installatie > Implementatie, zoals hier getoond.
3. Controleer Vorige stuurprogrammaversies verwijderen vóór de implementatie.
4. Selecteer voor doelapparaatnaamde naam van de computer die u hebt geconfigureerd voor testen en foutopsporing.
5. Selecteer hardware-id-stuurprogramma-updateen voer de hardware-id voor uw stuurprogramma in. In deze oefening is de hardware-id Root\MyUSBDriver_UMDF_. Kies OK.

Notitie

In deze oefening identificeert de hardware-id geen echt stukje hardware. Het identificeert een imaginair apparaat dat een plaats in de apparaatstructuur krijgt als een kind van het hoofdknooppunt. Selecteer geen Hardware-ID stuurprogramma-update voor echte hardware. Selecteer in plaats daarvan Installeren en verifiëren. U kunt de hardware-id in het inF-bestand (Information) van uw stuurprogramma zien. Ga in het venster Solution Explorer naar MyUSBDriver_UMDF_ > stuurprogrammabestanden en dubbelklik op MyUSBDriver_UMDF_.inf. De hardware-id bevindt zich onder [Standard.NT$ARCH$].

Alle USB-clientstuurprogramma's op basis van UMDF vereisen twee door Microsoft geleverde stuurprogramma's, de reflector en WinUSB.

• Reflector: Als uw stuurprogramma met succes wordt geladen, wordt de reflector als het bovenste driver in de kernelmodusstack geladen. De reflector moet de bovenste driver in de kernel-modus stack zijn. Om aan deze vereiste te voldoen, specificeert het INF-bestand van de sjabloon de reflector als een service en WinUSB als een lager filterstuurprogramma in de INF:

  [MyDevice_Install.NT.Services]
  AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall  ; flag 0x2 sets this as the service for the device
  AddService=WinUsb,0x000001f8,WinUsb_ServiceInstall  ; this service is installed because its a filter.
  

• WinUSB: Het installatiepakket moet coinstallers voor Winusb.sys bevatten, omdat WinUSB voor het clientstuurprogramma de gateway is naar de kernelmodus USB-stuurprogrammastack. Een ander onderdeel dat wordt geladen, is een DLL in de gebruikersmodus, met de naam WinUsb.dll, in het hostproces van het clientstuurprogramma (Wudfhost.exe). Winusb.dll winUSB-functies beschikbaar maakt die het communicatieproces tussen het clientstuurprogramma en WinUSB vereenvoudigen.

Stap 3: de USB-clientstuurprogrammacode bouwen

Uw stuurprogramma bouwen:

1. Open het stuurprogrammaproject of de oplossing in Visual Studio 2022.
2. Klik met de rechtermuisknop op de oplossing in Solution Explorer en selecteer Configuration Manager.
3. Selecteer in Configuration Manager uw actieve oplossingsconfiguratie (bijvoorbeeld fouten opsporen of vrijgeven) en uw Active Solution Platform (bijvoorbeeld x64) die overeenkomen met het type build waarin u geïnteresseerd bent.
4. Controleer of de GUID van de apparaatinterface nauwkeurig is gedurende het hele project.
   • De GUID van de apparaatinterface wordt gedefinieerd in Trace.h en verwijst vanuit MyUSBDriverUMDFCreateDevice Device.c. Wanneer u uw project maakt met de naam MyUSBDriver_UMDF_, definieert Visual Studio 2022 de GUID van de apparaatinterface met de naam GUID_DEVINTERFACE_MyUSBDriver_UMDF_ , maar wordt aangeroepen WdfDeviceCreateDeviceInterface met de onjuiste parameter &GUID_DEVINTERFACE_MyUSBDriverUMDF. Vervang de onjuiste parameter door de naam die is gedefinieerd in Trace.h om ervoor te zorgen dat het stuurprogramma correct wordt gebouwd.
5. Vanuit het Build menu, selecteer Build Solution.

Zie Een stuurprogramma bouwenvoor meer informatie.

Stap 4: een computer configureren voor testen en foutopsporing

Als u een stuurprogramma wilt testen en fouten wilt opsporen, voert u het foutopsporingsprogramma uit op de hostcomputer en het stuurprogramma op de doelcomputer. Tot nu toe hebt u Visual Studio op de hostcomputer gebruikt om een stuurprogramma te bouwen. Vervolgens moet u een doelcomputer configureren. Als u een doelcomputer wilt configureren, volgt u de instructies in Een computer inrichten voor de implementatie van stuurprogramma's en het testen van.

Stap 5: tracering inschakelen voor kernelfoutopsporing

De sjablooncode bevat verschillende traceringsberichten (TraceEvents) waarmee u functieaanroepen kunt bijhouden. Alle functies in de broncode bevatten traceerberichten die de ingang en uitvoer van een routine markeren. Voor fouten bevat het traceringsbericht de foutcode en een zinvolle tekenreeks. Omdat WPP-tracering is ingeschakeld voor uw stuurprogrammaproject, bevat het PDB-symboolbestand dat tijdens het buildproces is gemaakt traceringsberichtopmaakinstructies. Als u de host- en doelcomputers configureert voor WPP-tracering, kan uw stuurprogramma traceringsberichten verzenden naar een bestand of het foutopsporingsprogramma.

Uw hostcomputer configureren voor WPP-tracering

1. Maak TMF-bestanden (Trace Message Format) door instructies voor traceringsberichten op te halen uit het PDB-symboolbestand.

   U kunt Tracepdb.exe gebruiken om TMF-bestanden te maken. Het hulpprogramma bevindt zich in de <installatiemap>Windows Kits\10\bin\<architecture> van de WDK. Met de volgende opdracht maakt u TMF-bestanden voor het stuurprogrammaproject.

   tracepdb -f <PDBFiles> -p <TMFDirectory>
   

   De optie -f geeft de locatie en de naam van het PDB-symboolbestand op. De optie -p geeft de locatie op voor de TMF-bestanden die zijn gemaakt door Tracepdb. Zie Tracepdb-opdrachten voor meer informatie.

   Er zijn drie bestanden op de opgegeven locatie, één per C-codebestand in het project. Ze krijgen GUID-bestandsnamen.

2. Typ in het foutopsporingsprogramma de volgende opdrachten:

   .load Wmitrace
   .chain
   !wmitrace.searchpath + <TMF file location>
   

Deze opdrachten:

• Laad de Wmitrace.dll-extensie.
• Controleert of de extensie voor het foutopsporingsprogramma is geladen.
• Hiermee voegt u de locatie van de TMF-bestanden toe aan het zoekpad van de extensie voor foutopsporingsprogramma's.

De uitvoer ziet er ongeveer als volgt uit:

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

Uw doelcomputer configureren voor WPP-tracering

1. Zorg ervoor dat u het hulpprogramma Tracelog op uw doelcomputer hebt. Het hulpprogramma bevindt zich in de <map install_folder>Windows Kits\10\Tools\<arch> van de WDK. Zie De syntaxis van de Tracelog-opdracht voor meer informatie.

2. Open een opdrachtvenster en voer deze uit als administrator.

3. Typ de volgende opdracht:

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

Met de opdracht wordt een traceringssessie gestart met de naam MyTrace.

Met het guid argument wordt de GUID van de traceringsprovider opgegeven. Dit is het clientstuurprogramma. U kunt de GUID ophalen van Trace.h in het Visual Studio 2022-project. Als een andere optie kunt u de volgende opdracht typen en de GUID opgeven in een GUID-bestand. Het bestand bevat de GUID met streepjes.

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

U kunt de traceringssessie stoppen door de volgende opdracht te typen:

tracelog -stop MyTrace

Stap 6: Het stuurprogramma implementeren op de doelcomputer

1. Klik in het venster Solution Explorer met de rechtermuisknop op de projectnaam (MyUSBDriver_UMDF_) en kies Eigenschappen.
2. Navigeer in het linkerdeelvenster naar Configuratie-eigenschappen > Stuurprogramma installeren > Implementatie.
3. Geef bij Doelapparaatnaam de naam van de doelcomputer op.
4. Selecteer Installeren/opnieuw installeren en verifiëren.
5. Selecteer Ok.
6. Kies in het menu FoutopsporingStart Foutopsporing, of druk op de toets F5 op het toetsenbord.

Notitie

Geef niet de hardware-id van uw apparaat op onder Hardware-ID-stuurprogramma-update. De hardware-id moet alleen worden opgegeven in het INF-bestand (informatie van het stuurprogramma).

Stap 7: het stuurprogramma weergeven in Apparaatbeheer

1. Voer de volgende opdracht in om Apparaatbeheer te openen.

   devmgmt
   

2. Controleer of Apparaatbeheer het volgende knooppunt weergeeft.

   USB-apparaat

   MyUSBDriver_UMDF_Device

Stap 8: De uitvoer weergeven in het foutopsporingsprogramma

Controleer of traceringsberichten worden weergegeven in het venster direct van de debugger op de hostcomputer.

De uitvoer moet er ongeveer als volgt uitzien:

[0]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::OnPrepareHardware Entry
[0]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::OnPrepareHardware Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::CreateInstanceAndInitialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Initialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Initialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::CreateInstanceAndInitialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Configure Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::CreateInstanceAndInitialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::Initialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::Initialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::CreateInstanceAndInitialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Configure Exit

Opmerkingen

Laten we eens kijken hoe het framework en het clientstuurprogramma samenwerken om te communiceren met Windows en aanvragen te verwerken die naar het USB-apparaat worden verzonden. In deze afbeelding ziet u de modules die in het systeem zijn geladen voor een UMDF--based USB-clientstuurprogramma.

Het doel van elke module wordt hier beschreven:

• Toepassing: een gebruikersmodusproces waarmee I/O-aanvragen worden verzonden om te communiceren met het USB-apparaat.
• I/O-beheer: een Windows-onderdeel dat I/O-aanvraagpakketten (IRP's) maakt om de ontvangen toepassingsaanvragen weer te geven en deze doorstuurt naar de bovenkant van de kernelmodusapparaatstack voor het doelapparaat.
• Reflector — een door Microsoft geleverde kernelmodusstuurprogramma dat boven aan de kernelmodusapparaatstack (WUDFRd.sys) is geïnstalleerd. De reflector stuurt IRP's die van de I/O-manager zijn ontvangen naar het clientstuurprogrammahostproces. Na ontvangst van de aanvraag verwerken het framework en het clientstuurprogramma de aanvraag.
• Hostproces: het proces waarin het stuurprogramma voor de gebruikersmodus wordt uitgevoerd (Wudfhost.exe). Het host ook het framework en de I/O-dispatcher.
• Clientstuurprogramma: het functiestuurprogramma voor de gebruikersmodus voor het USB-apparaat.
• UMDF: de frameworkmodule die de meeste interacties met Windows verwerkt namens het clientstuurprogramma. Hiermee worden de interfaces voor apparaatstuurprogramma's in de gebruikersmodus weergegeven die het clientstuurprogramma kan gebruiken om algemene stuurprogrammataken uit te voeren.
• Dispatcher: mechanisme dat wordt uitgevoerd in het hostproces; bepaalt hoe u een aanvraag doorstuurt naar de kernelmodus nadat deze is verwerkt door stuurprogramma's voor de gebruikersmodus en de onderkant van de gebruikersmodusstack is bereikt. In de afbeelding stuurt de dispatcher de aanvraag door naar het DLL-bestand in de gebruikersmodus, Winusb.dll.
• Winusb.dll: een door Microsoft geleverd DLL-bestand met gebruikersmodus waarmee WinUSB-functies worden weergegeven die het communicatieproces tussen het clientstuurprogramma en WinUSB (Winusb.sys, geladen in kernelmodus) vereenvoudigen.
• Winusb.sys: een door Microsoft geleverd stuurprogramma dat is vereist voor alle UMDF-clientstuurprogramma's voor USB-apparaten. Het stuurprogramma moet onder de reflector worden geïnstalleerd en fungeert als de gateway naar de USB-stuurprogrammastack in de kernelmodus. Zie Inleiding tot WinUSB voor ontwikkelaars voor meer informatie.
• USB-stuurprogrammastack: een set stuurprogramma's, geleverd door Microsoft, die communicatie op protocolniveau verwerken met het USB-apparaat. Voor meer informatie, zie stuurprogramma's voor USB-hostzijde in Windows.

Wanneer een toepassing een aanvraag indient voor de USB-stuurprogrammastack, stuurt de Windows I/O-manager de aanvraag naar de reflector, die het naar clientstuurprogramma in de gebruikersmodus leidt. Het clientstuurprogramma verwerkt de aanvraag door specifieke UMDF-methoden aan te roepen, waarmee WinUSB-functies intern worden aangeroepen om de aanvraag naar WinUSB te verzenden. Na ontvangst van de aanvraag verwerkt WinUSB de aanvraag of stuurt deze door naar de USB-stuurprogrammastack.

Verwante onderwerpen

• Informatie over de UMDF-sjablooncode voor het USB-clientstuurprogramma
• USB-selectieve onderbreking en systeemontwaking inschakelen in het UMDF-stuurprogramma voor een USB-apparaat
• Aan de slag met de ontwikkeling van USB-clientstuurprogramma's