USB Audio 2.0 Drivers - Windows drivers
Driver on

How to write your first USB client driver (UMDF) – Windows drivers

On this matter you will use the USB Person-Mode Driver template supplied with Microsoft Visible Studio 2019 to put in writing a user-mode driver framework (UMDF)-based shopper driver. After constructing and putting in the shopper driver, you will view the shopper driver in Machine Supervisor and look at the motive force output in a debugger.

UMDF (known as the framework on this matter) relies on the element object mannequin (COM). Each framework object should implement IUnknown and its strategies, QueryInterface, AddRef, and Launch, by default. The AddRef and Launch strategies handle the article’s lifetime, so the shopper driver doesn’t want to keep up the reference rely. The QueryInterface methodology allows the shopper driver to get interface tips that could different framework objects within the Home windows Driver Frameworks (WDF) object mannequin. Framework objects carry out sophisticated driver duties and work together with Home windows. Sure framework objects expose interfaces that allow a shopper driver to work together with the framework.

A UMDF-based shopper driver is applied as an in-process COM server (DLL), and C++ is the popular language for writing a shopper driver for a USB machine. Usually, the shopper driver implements a number of interfaces uncovered by the framework. This matter refers to a shopper driver-defined class that implements framework interfaces as a callback class. After these courses are instantiated, the ensuing callback objects are partnered with explicit framework objects. This partnership provides the shopper driver the chance to answer machine or system-related occasions which might be reported by the framework. Every time Home windows notifies the framework about sure occasions, the framework invokes the shopper driver’s callback, if one is on the market. In any other case the framework proceeds with the default processing of the occasion. The template code defines driver, machine, and queue callback courses.

For an evidence in regards to the supply code generated by the template, see Understanding the UMDF template code for USB shopper driver.

Conditions

For growing, debugging, and putting in a user-mode driver, you want two computer systems:

  • A number laptop operating Home windows 7 or a later model of the Home windows working system. The host laptop is your improvement surroundings, the place you write and debug your driver.
  • A goal laptop operating the model of the working system that you simply wish to check your driver on, for instance, Home windows 10, model 1903. The goal laptop has the user-mode driver that you simply wish to debug and one of many debuggers.

In some circumstances, the place the host and goal computer systems are operating the identical model of Home windows, you possibly can have only one laptop operating Home windows 7 or a later model of the Home windows. This matter assumes that you’re utilizing two computer systems for growing, debugging, and putting in your consumer mode driver.

Earlier than you start, just remember to meet the next necessities:

Software program necessities

  • Your host laptop has Visible Studio 2019.

  • Your host laptop has the newest Home windows Driver Equipment (WDK) for Home windows 10, model 1903.

    The package embrace headers, libraries, instruments, documentation, and the debugging instruments required to develop, construct, and debug a USB shopper driver. You may get the newest model of the WDK from How one can Get the WDK.

  • Your host laptop has the newest model of debugging instruments for Home windows. You may get the newest model from the WDK or you possibly can Obtain and Set up Debugging Instruments for Home windows.

  • In case you are utilizing two computer systems, you will need to configure the host and goal computer systems for user-mode debugging. For extra info, see Setting Up Person-Mode Debugging in Visible Studio.

{Hardware} necessities

Get a USB machine for which you may be writing the shopper driver. Usually, you might be supplied with a USB machine and its {hardware} specification. The specification describes machine capabilities and the supported vendor instructions. Use the specification to find out the performance of the USB driver and the associated design selections.

In case you are new to USB driver improvement, use the OSR USB FX2 studying package to review USB samples included with the WDK. It incorporates the USB FX2 machine and all of the required {hardware} specs to implement a shopper driver.

Directions

Step 1: Generate the UMDF driver code through the use of the Visible Studio 2019 USB driver template

For directions about producing UMDF driver code, see Writing a UMDF driver primarily based on a template.

For USB-specific code, choose the next choices in Visible Studio 2019

  1. Within the New Challenge dialog field, within the search field on the high, kind USB.
  2. n the center pane, choose Person Mode Driver, USB (UMDF V2).
  3. lick Subsequent.
  4. Enter a undertaking identify, select a save location, and click on Create.

The next display pictures present the New Challenge dialog field for the USB Person-Mode Driver template.

visual studio new project options

visual studio new project options second screen

This matter assumes that the identify of the undertaking is “MyUSBDriver_UMDF_”. It incorporates the next recordsdata:

Information Description
Driver.h; Driver.c Declares and defines a callback class that implements the IDriverEntry interface. The category defines strategies which might be invoked by the framework driver object. The principle objective of this class is to create a tool object for the shopper driver.
Machine.h; Machine.c Declares and defines a callback class that implements the IPnpCallbackHardware interface. The category defines strategies which might be invoked by the framework machine object. The principle objective of this class is to deal with occasions occurring because of Plug and Play (PnP) state modifications. The category additionally allocates and initializes sources required by the shopper driver so long as it’s loaded within the system.
IoQueue.h; IoQueue.c Declares and defines a callback class that implements the IQueueCallbackDeviceIoControl interface. The category defines strategies which might be invoked by the framework queue object. The aim of this class is to retrieve I/O requests which might be queued within the framework.
Inside.h Supplies frequent declarations shared by the shopper driver and consumer functions that talk with the USB machine. It additionally declares tracing features and macros.
Dllsup.cpp Incorporates the implementation of the motive force module’s entry level.
.inf INF file that’s required to put in the shopper driver on the goal laptop.
Exports.def DEF file that exports the entry level perform identify of the motive force module.

Step 2: Modify the INF file so as to add details about your machine

Earlier than you construct the motive force, you will need to modify the template INF file with details about your machine, particularly the {hardware} ID string.

To supply the {hardware} ID string

  1. Connect your USB machine to your host laptop and let Home windows enumerate the machine.

  2. Open Machine Supervisor and open properties to your machine.

  3. On the Particulars tab, choose Hardward Ids below Property.

    The {hardware} ID for the machine is displayed within the checklist field. Choose and maintain (or right-click) and replica the {hardware} ID string.

  4. In Resolution Explorer, broaden Driver Information, and open the INF.

  5. Exchange the next your {hardware} ID string.

    [Standard.NT$ARCH$]

    %DeviceName%=MyDevice_Install, USBVID_vvvv&PID_pppp

Discover the AddReg entries within the driver’s info (INF) file.

[CoInstallers_AddReg] ;

HKR,,CoInstallers32,0x00010008,"WudfCoinstaller.dll"

HKR,,CoInstallers32,0x00010008,"WudfUpdate_01011.dll"

HKR,,CoInstallers32,0x00010008,"WdfCoInstaller01011.dll,WdfCoInstaller"

HKR,,CoInstallers32,0x00010008,"WinUsbCoinstaller2.dll"

  • WudfCoinstaller.dll (configuration co-installer)
  • WUDFUpdate_.dll (redistributable co-installer)
  • Wdfcoinstaller.dll (co-installers for KMDF)
  • Winusbcoinstaller2.dll ((co-installers for Winusb.sys)
  • MyUSBDriver_UMDF_.dll (shopper driver module)

In case your INF AddReg directive references the UMDF redistributable co-installer (WUDFUpdate_.dll ), you will need to not make a reference to the configuration co-installer (WUDFCoInstaller.dll). Referencing each co-installers within the INF will result in set up errors.

All UMDF-based USB shopper drivers require two Microsoft-provided drivers: the reflector and WinUSB.

  • Reflector—In case your driver will get loaded efficiently, the reflector is loaded because the top-most driver within the kernel-mode stack. The reflector should be the highest driver within the kernel mode stack. To satisfy this requirement, the template’s INF file specifies the reflector as a service and WinUSB as a lower-filter driver within the INF:

    [MyDevice_Install.NT.Services]

    AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall ; flag 0x2 units this because the service for the machine

    AddService=WinUsb,0x000001f8,WinUsb_ServiceInstall ; this service is put in as a result of its a filter.

  • WinUSB—The set up package deal should include coinstallers for Winusb.sys as a result of for the shopper driver, WinUSB is the gateway to the kernel-mode USB driver stack. One other element that will get loaded is a user-mode DLL, named WinUsb.dll, within the shopper driver’s host course of (Wudfhost.exe). Winusb.dll exposes WinUSB Features that simplify the communication course of between the shopper driver and WinUSB.

Step 3: Construct the USB shopper driver code

To construct your driver

  1. Open the motive force undertaking or answer in Visible Studio 2019.
  2. Proper-click the answer within the Resolution Explorer and choose Configuration Supervisor.
  3. From the Configuration Supervisor, choose your Energetic Resolution Configuration (for instance, Debug or Launch) and your Energetic Resolution Platform (for instance, Win32) that correspond to the kind of construct you have an interest in.
  4. Confirm that your machine interface GUID is correct all through the undertaking.
    • The machine interface GUID is outlined in Hint.h and is referenced from MyUSBDriverUMDFCreateDevice in Machine.c. Once you create your undertaking with the identify “MyUSBDriver_UMDF_”, Visible Studio 2019 defines the machine interface GUID with the identify GUID_DEVINTERFACE_MyUSBDriver_UMDF_ however calls WdfDeviceCreateDeviceInterface with the inaccurate parameter “GUID_DEVINTERFACE_MyUSBDriverUMDF”. Exchange the inaccurate parameter with the identify outlined in Hint.h to make sure that the motive force builds correctly.
  5. From the Construct menu, click on Construct Resolution.

For extra info, see Constructing a Driver.

Step 4: Configure a pc for testing and debugging

To check and debug a driver, you run the debugger on the host laptop and the motive force on the goal laptop. Thus far, you have got used Visible Studio on the host laptop to construct a driver. Subsequent it’s essential configure a goal laptop. To configure a goal laptop, comply with the directions in Provision a pc for driver deployment and testing.

Step 5: Allow tracing for kernel debugging

The template code incorporates a number of hint messages (TraceEvents) that may assist you to observe perform calls. All features within the supply code include hint messages that mark the entry and exit of a routine. For errors, the hint message incorporates the error code and a significant string. As a result of WPP tracing is enabled to your driver undertaking, the PDB image file created in the course of the construct course of incorporates hint message formatting directions. If you happen to configure the host and goal computer systems for WPP tracing, your driver can ship hint messages to a file or the debugger.

To configure your host laptop for WPP tracing

  1. Create hint message format (TMF) recordsdata by extracting hint message formatting directions from the PDB image file.

    You should use Tracepdb.exe to create TMF recordsdata. The instrument is positioned within the Home windows Kits10bin folder of the WDK. The next command creates TMF recordsdata for the motive force undertaking.

    tracepdb -f [PDBFiles] -p [TMFDirectory]

    The -f choice specifies the situation and the identify of the PDB image file. The -p choice specifies the situation for the TMF recordsdata which might be created by Tracepdb. For extra info, see Tracepdb Instructions.

    On the specified location you will see three recordsdata (one per .c file within the undertaking). They’re given GUID file names.

  2. Within the debugger, kind the next instructions:

.load Wmitrace

.chain

!wmitrace.searchpath +***<TMF file location>

These instructions:

  • Load the Wmitrace.dll extension.
  • Verfies that the debugger extension is loaded.
  • Provides the situation of the TMF recordsdata to the debugger extension’s search path.

The output resembles this:

    Hint Format search path is: 'C:Program Information (x86)Microsoft Visible Studio 14.0Common7IDE;c:driverstmf

To configure your goal laptop for WPP tracing

  1. Be sure you have the Tracelog instrument in your goal laptop. The instrument is positioned within the Home windows Kits10Instruments folder of the WDK. For extra info, see Tracelog Command Syntax.
  2. Open a Command Window and run as administrator.
  3. Sort the next command:
   **tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd**

The command begins a hint session named MyTrace.

The guid argument specifies the GUID of the hint supplier, which is the shopper driver. You may get the GUID from Hint.h within the Visible Studio 2019 undertaking. As an alternative choice, you possibly can kind the next command and specify the GUID in a .guid file. The file incorporates the GUID in hyphen format:

   **tracelog -start MyTrace -guid c:driversProvider.guid -flag 0xFFFF -level 7-rt -kd**

You may cease the hint session by typing the next command:

   **tracelog -stop MyTrace**

Step 6: Deploy the motive force on the goal laptop

  1. Within the Resolution Explorer window, choose and maintain (or right-click) the Bundle , and select Properties.
  2. Within the left pane, navigate to Configuration Properties > Driver Set up > Deployment.
  3. Examine Allow deployment, and examine Import into driver retailer.
  4. For Distant Pc Title, specify the identify of the goal laptop.
  5. Choose Set up and Confirm.
  6. Choose Okay.
  7. On the Debug menu, select Begin Debugging, or press F5 on the keyboard.

Word

Do not specify the {hardware} ID of your machine below {Hardware} ID Driver Replace. The {hardware} ID should be specified solely in your driver’s info (INF) file.

Step 7: View the motive force in Machine Supervisor

  1. Enter the next command to open Machine Supervisor.

    devmgmt

  2. Confirm that Machine Supervisor reveals the next node.

    USB Machine

    MyUSBDriver_UMDF_Device

Step 8: View the output within the debugger

Confirm that hint messages seem within the Debugger Instant Window on the host laptop.

The output must be just like the next:

[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

Remarks

Let’s check out how the framework and the shopper driver work collectively to work together with Home windows and deal with requests despatched to the USB machine. This illustration reveals the modules loaded within the system for a UMDF -based USB shopper driver.

user mode client driver architecture

The aim of every module is described right here:

  • Utility—a user-mode course of that points I/O requests to speak with the USB machine.
  • I/O Supervisor—a Home windows element that creates I/O request packets (IRPs) to symbolize the obtained software requests, and forwards them to the highest of the kernel-mode machine stack for the goal machine.
  • Reflector—a Microsoft-provided kernel-mode driver put in on the high of the kernel-mode machine stack (WUDFRd.sys). The reflector redirects IRPs obtained from the I/O supervisor to the shopper driver host course of. Upon receiving the request, the framework and the shopper driver deal with the request.
  • Host course of —the method during which the user-mode driver runs (Wudfhost.exe). It additionally hosts the framework and the I/O dispatcher.
  • Consumer driver—the user-mode perform driver for the USB machine.
  • UMDF—the framework module that handles most interactions with Home windows on the behalf of the shopper driver. It exposes the user-mode machine driver interfaces (DDIs) that the shopper driver can use to carry out frequent driver duties.
  • Dispatcher—mechanism that runs within the host course of; determines find out how to ahead a request to the kernel mode after it has been processed by user-mode drivers and has reached the underside of the user-mode stack. Within the illustration, the dispatcher forwards the request to the user-mode DLL, Winusb.dll.
  • Winusb.dll—a Microsoft-provided user-mode DLL that exposes WinUSB Features that simplify the communication course of between the shopper driver and WinUSB (Winusb.sys, loaded in kernel mode).
  • Winusb.sys—a Microsoft-provided driver that’s required by all UMDF shopper drivers for USB gadgets. The motive force should be put in beneath the reflector and acts because the gateway to the USB driver stack within the kernel-mode. For extra info, see WinUSB.
  • USB driver stack—a set of drivers, offered by Microsoft, that deal with protocol-level communication with the USB machine. For extra info, see USB host-side drivers in Home windows.

Every time an software makes a request for the USB driver stack, the Home windows I/O supervisor sends the request to the reflector, which directs it to shopper driver in consumer mode. The shopper driver handles the request by calling particular UMDF strategies, which internally name WinUSB Features to ship the request to WinUSB. Upon receiving the request, WinUSB both processes the request or forwards it to the USB driver stack.

Understanding the UMDF template code for USB shopper driver
How one can allow USB selective droop and system wake within the UMDF driver for a USB machine
Getting began with USB shopper driver improvement

Leave a Reply

Your email address will not be published. Required fields are marked *