User-Mode Driver Framework

The User-Mode Driver Framework is a device-driver development platform first introduced with Microsoft's Windows Vista operating system, and is also available for Windows XP. It facilitates the creation of drivers for certain classes of devices.

Overview

Badly written drivers can cause severe damage to a system since all drivers have high privileges when accessing the kernel directly. The User-Mode Driver Framework is not able to access the kernel directly but instead accesses it through a dedicated application programming interface. If an error occurs, the new framework allows for an immediate restart of the driver without impacting the system. Typically, devices are connected to the computer through a bus technology such as USB or Firewire.

The first version of the UMDF was shipped as part of Windows Media Player version 10. Code-named "Crescent", it was designed to support the Media Transfer Protocol driver, and no public interfaces or documentation were provided for it. Later, Microsoft decided to turn UMDF into a device driver development platform.

The current version of the User-Mode Driver Framework is 1.7, which shipped as part of Windows Vista Service Pack 1 and Windows Server 2008, and is available for Windows XP Service Pack 2 and later, and Windows Server 2003 Service Pack 1 and later.

Architecture

A UMDF Driver is a DLL based on Microsoft's Component Object Model (COM), but UMDF doesn't use the COM runtime library, using COM only as a programming pattern. UMDF does not use COM for loading, unloading, or controlling concurrency (that is, apartment-based concurrency mechanism).

UMDF calls DllGetClassObject to get a pointer to an IClassFactory interface in the driver and then uses the CreateInstance method of the IClassFactory interface to create an instance of the driver object. The DLL provides routines that COM uses to get the IWDFDriver-based object:

• DllCanUnloadNow
• DllGetClassObject
• DllRegisterServer
• DllUnregisterServer

DllMain

UMDF driver is a Dynamic Link Library (DLL) that runs as an in-process COM server and contains the code for DllMain, which is a well-known entry point for a DLL.

BOOL WINAPI DllMain(HINSTANCE ModuleHandle, DWORD Reason, PVOID /* Reserved */)
{
    if (DLL_PROCESS_ATTACH == Reason) 
    {
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);
        g_ModuleHandle = ModuleHandle;
    }
    else if (DLL_PROCESS_DETACH == Reason) 
    {
 
        WPP_CLEANUP();
    }
 
    return TRUE;
};

UMDF supports IXX abstract classes with which any KMDF developer as following:

• IWDFDriver
• IWDFDevice
• IWDFFile
• IWDFIoQueue
• IWDFIoRequest
• IWDFIoTarget
• IWDFMemory
• IWDFObject

IUnknown interface

COM interfaces are C++ abstract base classes. These UMDF objects provide signatures for the routines (callback functions) they support in the form of abstract classes (interfaces), that are pure virtual functions. Any UMDF driver which support an interface must implement all the functions in that callback interface. And all COM objects support the interface IUnknown.

IUnknown interface supports three methods:

interface IUnknown
{
 virtual ULONG AddRef(void) = 0; 
 virtual HRESULT QueryInterface(REFIID riid, void **ppvObject) = 0;
 virtual ULONG Release(void) = 0; 
};

IDriverEntry interface

UMDF drivers must support the IDriverEntry interface, and need to implement OnAddDevice callbacks.

 class CMyDriver : public IDriverEntry, public CUnknown
 {
   virtual ULONG STDMETHODCALLTYPE AddRef(VOID){
       return __super::AddRef();
   }
 
   virtual ULONG STDMETHODCALLTYPE Release(VOID){
       return __super::Release();
   }
 
   virtual HRESULT STDMETHODCALLTYPE QueryInterface(__in REFIID InterfaceId, __out PVOID *Object){
       return __super::Release(InterfaceId, Object);
   }  
   
   virtual HRESULT Initialize(__in IWDFDriver* FxDriver,__in IWDFDeviceInitialize * FxDeviceInit){...}
   
   virtual HRESULT STDMETHODCALLTYPE OnDeviceAdd( __in IWDFDriver *FxWdfDriver, __in IWDFDeviceInitialize *FxDeviceInit){
     ...
   }    
   
   virtual VOID STDMETHODCALLTYPE OnDeinitialize(__in IWDFDriver *FxWdfDriver) {
       return;
   }
   ...
};

IDevicePnpHardware interface

Create CMyDevice class that inherits from IIDevicePnpHardware and CUnknown class.

class CMyDevice : public CUnknown, public IDevicePnpHardware
{
    private:
        IWDFDevice *m_FxDevice;
    public:
        HRESULT Initialize(__in IWDFDriver* FxDriver,__in IWDFDeviceInitialize* FxDeviceInit)
        {
            return S_OK;
        }
 
        HRESULT OnPrepareHardware(__in IWDFDevice* /* FxDevice */)
        {
            return S_OK;
        }
 //...
};

References

• UMDF 101 - Understanding User Mode Driver Frameworks, OSR Online (registration required).

See also

• Windows Driver Foundation
• Kernel-Mode Driver Framework

External links

• User-Mode Driver Framework Homepage
• Peter Wieland's blog – developer lead on the UMDF team at Microsoft