Getting Started with Universal Windows drivers

Universal Windows drivers enable developers to create a single driver that runs across multiple different device types, from embedded systems to tablets and desktop PCs. Hardware developers can use their existing components and device drivers across different form factors. Universal Windows drivers run on Windows 10 for desktop editions (Home, Pro, and Enterprise), Windows 10 Mobile, Windows 10 IoT Core, Windows Server 2016 Technical Preview, as well as other Windows 10 editions that share a common set of interfaces.

Introduction to Universal Windows drivers

Windows 10 provides a set of API and DDI interfaces that are common to multiple editions of Windows. This set of interfaces is called the Universal Windows Platform (UWP).

A Universal Windows driver is a kernel-mode or user-mode driver binary that installs and runs on UWP-based editions of Windows 10.

A Universal Windows driver calls only device driver interfaces (DDIs) that are part of UWP. These DDIs are marked as Universal on the corresponding MSDN reference pages.

To determine if your existing driver calls any interfaces outside of UWP, recompile your driver as a Universal Windows driver. The compiler displays ApiValidator errors if the driver calls interfaces that are not part of UWP. In some cases, you can replace these calls with alternate DDIs that are listed on the MSDN reference pages for the desktop-only DDI. If you cannot find a suitable replacement, please submit feedback.

In other cases, you may have to code a workaround if there is not a suitable replacement. If you need to, write a new Universal Windows driver starting from the driver templates in the unified WDK.

The compiler might also display INF validation errors if you are not using a universal INF file.

A Universal Windows driver can use KMDF, UMDF 2 or the Windows Driver Model (WDM).

Building a Universal Windows driver

You can use Microsoft Visual Studio 2015 in conjunction with Windows Driver Kit (WDK) 10 to build drivers for desktop, mobile, or universal. You can download kits and tools from the Windows Hardware Dev Center.

In many cases, you can recompile an existing kernel-mode driver that runs on Windows 8.1 as a Universal Windows driver, as long as the driver does not work with any user-mode components. WDM and KMDF drivers that work with Windows 8.1 should recompile as Universal Windows drivers targeting Windows 10 with no conversion required.

In contrast, existing user-mode drivers may require modification to compile as Universal Windows drivers. Specifically, your driver package must not have any dependencies outside of UWP. For example, only some of the Win32 APIs are part of UWP.

Converting an existing driver project to a Universal Windows driver project

  1. In Visual Studio 2015, open the existing driver project.
  2. In the Solution Explorer pane, right-click the solution and choose Configuration Manager. Set the target operating system to Windows 10.
  3. Right-click the driver project and choose Properties. Under Configuration Properties->Driver, verify that Target Platform is set to Universal. Other choices include Desktop, to build a driver that runs on Windows 10 for desktop editions only, and Mobile, to build a driver that runs on Windows 10 Mobile only.
  4. Build the driver. You might see linker errors.
  5. Fix the errors one by one by going through the error log. Refer to individual reference pages in the documentation for possible alternate APIs. If replacements are not available, you may need to redesign your driver.

Creating a New Universal Windows driver Project in Microsoft Visual Studio

  1. Create a new driver from a template (File>New Project->Templates->Visual C++->Windows Driver->WDF) and choose either User Mode Driver (UMDF V2) or Kernel Mode Driver (KMDF).
  2. After you create the project, in the Solution Explorer pane, right-click the solution and choose Configuration Manager. Set Active solution configuration to the desired target Windows version, and set Active solution platform to Win32 or x64. If ARM is not listed, choose <New...> to build for ARM.

    If you choose Windows 10, the driver model defaults to Universal.

    To change driver model manually, right-click the driver project and choose Properties. Under Configuration Properties->Driver Settings->General, find the Target Platform entry. Choose Universal, Desktop, or Mobile. Microsoft Visual Studio uses this setting to determine what libraries to link against.

    Note You cannot build a Universal Windows driver for Windows versions earlier than Windows 10.

  3. You might need to modify the .inf file to specify the provider, specified as an %ManufacturerName% token that is expanded later in the INF file's Strings section. For example:

    Provider="Contoso"
    
  4. You can now build the solution. Visual Studio links against the required libraries and generates a .cat file, an .inf file, and a driver binary.

For information about the configuration settings you can use in Visual Studio when building your driver, see Building a Driver with the WDK.

Installing a Universal Windows driver

Note The SetupAPI component is not part of UWP, so a Universal Windows driver cannot call functions in this API set.

If you want to install a Universal Windows driver on a device that is running Windows 10 for desktop editions, you can still use an INF file, with a few caveats. An INF for a Universal Windows driver cannot include any of the following:

  • Coinstallers
  • Class installers
  • RegisterDLL, DelFile, or DelReg directives
  • Non-HKR AddReg directives

For more information, see Using a Universal INF File.

If you want to install your Universal Windows driver on Windows 10 Mobile, you can use an .spkg file. An .spkg ("package file") is a standalone module that contains your driver package. If you are not deploying to Windows 10 Mobile, you do not need to generate a package file. You can still compile a Universal Windows driver (as defined by the driver source code) without a package file.

WDK 10 includes PkgGen, a tool that generates package files. You run PkgGen in Visual Studio when you build your driver, using the following procedure.

Using PkgGen to generate a package file

  1. Right-click the driver project and choose Add->New Item. Next, under Visual C++->Windows Driver, choose Package Manifest. Click Add.
  2. Visual Studio adds a file called Package.pkg.xml to your driver project. You can right-click the file and choose properties to verify that the item type is PkgGen. (On this same property page, you can set Excluded from Build to Yes if you decide later that you want to build this driver project and not generate a package file.) Click OK.
  3. Right-click the driver project and choose Properties. Under Configuration Properties, open the PackageGen node and change Version to any value you like.
  4. Save your work and restart Visual Studio as administrator.
  5. Build your driver. Visual Studio links against the required libraries and generates a .cat file, an .inf file, a driver binary, and an .spkg file.

To view the contents of the package file, append a .cab suffix to the file name and then open the cab file in Windows Explorer.

To learn about running PkgGen outside of Visual Studio, see Creating packages.

To install a mobile driver package (.spkg file), you have two options.

  • If you are updating an existing package on a target system or adding a new package to the target, use IUTool.exe to install an .spkg driver package.
  • If you are combining packages into a mobile OS image, use ImgGen to add the .spkg driver package to a full flash update (FFU) image that can then be flashed to a mobile device.

Using IUTool to add a mobile driver package (.spkg) to a running device

  1. IUTool.exe is in the \tools\bin\<architecture> subdirectory of WDK 10.

    Attach your mobile device to the PC. Then, from an elevated command prompt, issue the following command:

    IUTool -p MyKmdfDriver.spkg
    
  2. For more information, see IUTool.exe: Update packages on a phone and Adding a driver to a test image.

Using ImgGen to add a driver package (.spkg) to a mobile OS image (.ffu)

  1. After you install Visual Studio, on the Start screen, click the Visual Studio 2015 folder. Right-click Developer Command Prompt for VS2015, and choose Run as Administrator.
  2. For more information about ImgGen, see Building a phone image using ImgGen.cmd.

Flashing a mobile OS image (.ffu)

To flash the image to the device, either use the Microsoft-supplied FFUTool, or develop custom OEM flashing tools. For more information, see Update packages in an .FFU image file.

Debugging a Universal Windows driver

Starting in Windows 10, you can build your KMDF or UMDF driver so that it gets additional driver debugging information through the Inflight Trace Recorder. Universal Windows drivers can take advantage of this feature.

In addition, if you used the Visual Studio KMDF template, your driver uses Windows software trace preprocessor (WPP) to write trace messages. Your driver is an ETW provider with a provider GUID.

To send a trace message from your driver, use this code:

TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, &quot;%!FUNC! Entry&quot;);

You can access the ETW logs either using Tracelog via the TShell tool on a phone, or by using !wmitrace in a debugger session.

To use Tracelog on a phone:

  1. Establish a kernel-mode debugging session between a host computer and the phone.
  2. On the host computer, in TShell, enter this command:

    exec-device tracelog -addautologger MyLogger05 -guid c:\SteveGuid.txt -level 4 -flag 0xF –kd
    
  3. Reboot the phone, and watch for trace messages in the debugger.

All existing kernel mode debug transports continue to work on Windows 10 for desktop editions. However, for both user-mode and kernel-mode drivers, you must use a remote debugger session over KDNET to test Windows 10 Mobile. For more info, see Setting Up Kernel-Mode Debugging over a Network Cable Manually in Visual Studio.

Related topics