How to Develop a UMDF Driver Part 1 Outline Architectural Goals Architectural Description Core components Driver Manager, Reflector, Host Process, and Drivers Driver startup and teardown I/O flow Layered drivers Driver Programming Model WDF object model COM-lite UMDF DDIs Goals An understanding of UMDF infrastructure An understanding of the UMDF DDIs and how they are structured Architectural Goals Stability Driver failures should NOT bring down the system Build on Windows NT I/O model Applications are transparent to driver runtime environment вЂ“ User or Kernel mode Asynchronous, layered drivers, and packet based Integrate into PnP for device installs, driver load/unload Security Driver failures should NOT compromise the system Driver runs in вЂњLocalServiceвЂќ account Shared model between KMDF and UMDF Shared model != same DDIs or data structures Architectural Block Diagram Application(s) Driver Manager Host Process Host Process UM Driver UM Driver WinSock User Kernel Reflector Windows Kernel (I/O Mgr, PnP) Reflector Kernel Driver (e.g., WinUSB) Provided by: Microsoft ISV IHV Kernel Driver 2 Device Stack Device Stack UMDF Components Driver manager Global, system-wide Windows Service Responsible for host process lifetime Responds to messages from reflector Always running Started during installation of the first UMDF device Host Process Driver Manager UM Driver Reflector UMDF Components Reflector Nucleus of UMDF Installed with each device stack Proxy for UM device stack in kernel Forwards I/O, Power, and PnP messages from kernel to host process Ties the UM device stack to KM side Ensures вЂњgood behaviorвЂќ of UM drivers Proper responses to messages Timely completion of critical system messages Tracks all outstanding kernel resources Host Process Driver Manager UM Driver Reflector UMDF Components : Host Process Child process of the UM Driver Manager Unit of isolation for the device stack Driver crash will not affect other device stacks Container for Framework and UM driver(s) Runtime environment for framework and driver I/O dispatching, driver loading, driver layering, thread pool Handles messages from reflector and driver manager Driver Manager Runtime Reflector Framework DDI UM Driver Host Process - Framework Implements all of the WDF model Queues, Request, I/O target, etc Implements default behavior Reduces vendor written code Exposes DDI Implemented as DLL Runtime Framework DDI UM Driver IPC : Message Passing Requirements Packet-based and asynchronous Cancelable Fail-safe Efficient data transfer Secure Several potential solution Pending I/O, synchronous message passing Windows codenamed вЂњLonghornвЂќ solution: ALPC Standard Windows OS Component Processing Messages KM drivers handle I/O in callerвЂ™s thread Obviously not a option for UMDF Host has a thread pool processing messages Dedicated thread for вЂњcriticalвЂќ operations To ensure I/O doesnвЂ™t block them e.g., PnP/PM, Cancellation, Cleanup, and Close Shared threads for non-critical operations like I/O Pool could grow or shrink as load changes Fixed at 2 threads for Beta 1 For long operations the driver should consider using work-items Driver Loading 5 Driver Manager 3 Host Runtime 2 Windows Kernel (I/O Mgr, PnP) Provided by: Microsoft IHV 1 Add Device 6 Framework 4 UM Driver IPC Channel Reflector Kernel Driver Driver Loading (Layered UM Drivers) 7 Driver Manager 3 Host Runtime 8 5 6 2 Windows Kernel (I/O Mgr, PnP) Provided by: Microsoft IHV 1 Add Device UM Filter Driver Framework Framework 4 UM Driver IPC Channel Reflector Kernel Driver Driver Loading (Host Process) Add Device Host Runtime Add Device Driver creates WDF Device Framework UM Driver Driver creates WDF Queue Driver creates WDF Queue Add Device Provided by: Microsoft IHV I/O Data Flow UM Filter Driver Framework UM I/O Mgr 1 5 Host Process Application 4 Device Stack 6 7 9 8 Win32 I/O API Framework 10 11 3 UM Driver 12 IPC Message Windows Kernel 2 IRP вЂњUpвЂќ Device Object вЂњDownвЂќ Device Object Reflector Provided by: Microsoft ISV IHV Kernel driver I/O in Host Process Invoke driver callback passing in I/O request Run-time Host File Object UM IRP UM Irp Framework Device Stack IPC Message Host File Object returned as context to the reflector. Provided by: Microsoft ISV IHV Driver can return without completing i/o (asynch) Driver eventually completes i/o. UM Driver Device Removal and Cleanup Run-time Framework UM Driver Device Remove Message path similar to вЂњadd deviceвЂќ path Driver gets several PnP notifications for remove UM driver may unload when remove finishes Host process may exit when all drivers are unloaded Host lifetime controlled by the driver manager When Driver or Application Crashes When the UM driver crashes: Reflector gets notification from OS Reflector tracks outstanding I/O in the host. Completed with STATUS_DRIVER_PROCESS_TERMINATED Win32 apps will see ERROR_DRIVER_PROCESS_TERMINATED The kernel drivers for the device stack are unloaded Device is disabled (yellow bang in device manager) When the application crashes: Reflectors gets IRP_MJ_CLEANUP Sent to host on the вЂњcancelвЂќ IPC channel Host/UM driver complete pending I/O requests Timeout Policy UMDF enforces timeouts on вЂњcriticalвЂќ operations Operations that run under system wide locks Operations that affect user experience If operations do not complete on time Host is forcibly terminated and error report is generated Critical operations include PnP and PM operations These run under a system-wide PnP lock Blocks other PnP operations I/O Cancellation Long term operations must be cancelable Adversely affects user experience (application hangs) In WinHEC release, time out = 1 minute Will adjust based on feedback & failure report data for RTM Impersonation Driver runs in LocalService security context Drivers can impersonate the client process Only for I/O requests Not for PnP or other system messages typedef enum _SECURITY_IMPERSONATION_LEVEL { SecurityAnonymous, SecurityIdentification, SecurityImpersonation, SecurityDelegation } SECURITY_IMPERSONATION_LEVEL; Using Impersonation Application controls the allowed level Specified in QOS settings in CreateFile API See dwFlagsAndAttributes parameter in MSDN INF sets the driverвЂ™s maximum desired level Stored in registry during device installation Set this as low as possible for your driver Reduces chance of вЂњelevation of privilegeвЂќ attack Driver requests impersonation for given request Specifies desired level and a callback Isolate impersonated code Do minimal work to reduce the attack surface UMDF Verifier Built-in verification Checks for problems in framework code Checks for problems in device driver code Always enabled & always fatal Unless you have a debugger attached DDI misusage result in verifier failure Passing incorrect parameters, including NULL, in DDI Incorrect DDI call sequence More aggressive checks planned for Beta 2 Verifier failure causes a UMDF вЂњBugcheckвЂќ Generates Memory Dump Generates Error Report Sends Error Report to Microsoft (opt-in) UMDF Verifier Failures Driver failures will вЂњBugcheckвЂќ the host Bugcheck is NOT the вЂњBlue Screen of DeathвЂќ We will pick a less scary name in Beta 2 Bugcheck will: Save memory dump to log file directory %windir%\System32\LogFiles\WUDF\xxx.dmp Create an error report to report to Microsoft (opt-in) Break into debugger if present Prints out error message Developer can continueвЂ¦but that may lead to another crash Terminate the host process and disable the device UMDF Error Reporting Current driver failure reports are hard to analyze Too much information in the running kernel Not enough fits into a minidump User-Mode Drivers reports can be better Compartmentalized вЂ“ less information to collect Specialized вЂ“ not mixed with irrelevant state Better collection вЂ“ weвЂ™re not limited by crash dump UMDF reports problems through Windows Error Reporting (WER) UMDF queues reports for later approval and upload WER provides for a global вЂњopt-inвЂќ to upload quicker No modal crash dialogs Bubble on the task bar indicating an incident has occurred Please upload error reports for Beta 1 Even if you think itвЂ™s your driver We need data to refine what weвЂ™re collecting Types of Error Reports UMDF will report the following problems : UM Driver Verifier failure Unhandled Exception in host process Unexpected Host Termination Failure or Timeout of вЂњCriticalвЂќ Operation Error Report may contain: Memory dump of the host process Copy of UMDFвЂ™s internal trace log Configuration information about the device Device name, manufacturer, drivers installed Driver binary versions Internal analysis of the problem Address of the last driver to framework call (or vice versa) Problem code, exception info, etc... Report contents depend on the problem detected Device Driver Interfaces (DDI) and Programming Patterns Framework Object Model Framework objects have a hierarchical relationship WDF Driver is the root object Child lifetime scoped by parent Every WDF object is defined by Methods: actions on objects Properties: are object attributes Events: notifications from Framework objects to the driver WDF Driver WDF Device WDF Queue WDF Queue Key Framework Objects Object Driver Device I/O Request I/O Queue File I/O Target Description Supports one or more devices One per driver per host process Tracks PnP/PM state changes and notifies driver Represents applicationвЂ™s I/O request Controls I/O request flow into driver Provides per-handle context for driver Represents next lower device in stack Encapsulates driver to driver communication Parent-Child Object Hierarchy Applies to lifetime management Lifetime of child is scoped within that of the parent Child is cleaned up when the parent goes away Driver Device I/O Queue File I/O Request I/O Target Framework Object Model Framework Driver WDF Driver MyDriver MyDevice WDF Device WDF Queue WDF Queue WDF Objects Provided by: Microsoft IHV MyRead Queue MyWrite Queue Driver implemented Callback Objects Framework Object Model Framework Driver 1 MyDriver1 WDF Driver MyDevice1 WDF Device WDF Queue WDF Queue WDF Driver Device Stack WDF Device WDF Queue WDF Queue MyWrite Queue1 MyDevice2 MyRead Queue2 MyRead Queue1 MyDriver2 MyWrite Queue2 Driver 2 Each driver in the stack has its own set of framework objects DDI Design Common object model with KMDF Driver writers familiar with KMDF can quickly come up to speed with UMDF Interface based programming model UM developers are familiar with C++ and OOP Interfaces allow logical grouping of functions making it easy to navigate through the DDI Facilitates opt-in programming Built-in extensibility C++ is the supported language in the first version Uses a small subset of COM (COM-Lite) COM complexity is in COM RTL features Threading Model, Automation, etc... UMDF doesnвЂ™t depend on COM RTL DDI : COM Interfaces Problems solved by Interfaces Allows us to evolve the DDI without changing exported functions Older drivers do not need to be rebuilt No C++ name mangling No C++ fragile base class problem COM facilitates this Well understood Existing tools like ATL We donвЂ™t want to invent another model C++ facilitates this Interfaces are just abstract base classes With only pure virtual functions Compiler implements interface as function pointer table (V-Table) All You Need to Know about COM вЂ¦ COM interfaces, by convention, start with вЂњIвЂќ e.g., IUnknown All COM interfaces are derived from IUknown QueryInterface, AddRef, Release Lifetime management of COM objects AddRef: takes a reference on Framework object WDF object model simplifies ref-counting Release: drops ref-count on Framework object Driver should release interfaces retrieved from Fx when done Query Interface (QI): allows discovery of вЂњinterfacesвЂќ supported by the driver Device Driver Interfaces (DDI) UMDF DDI is in wudfddi.idl interface IWDFObject : IUnknown { HRESULT DeleteWdfObject(); ... VOID AcquireLock(); VOID ReleaseLock(); }; Simplified C++ equivalent generated by MIDL struct IWDFObject : public IUnknown { virtual HRESULT DeleteWdfObject() = 0; ... virtual VOID AcquireLock() = 0; virtual VOID ReleaseLock() = 0; }; IWDFObject is base interface for all WDF objects Device Driver Interfaces (DDI) DDIs are grouped into 2 types of interfaces Functionality exported by Framework By convention these begin with IWDF E.g., IWDFDriver, IWDFDevice, IWDFIoQueue Callbacks exported by Driver These are of the form I<WdfObject><Function> e.g., IQueueCallbackRead, IRequestCallbackCancel Methods on callback interfaces begin with вЂњOnвЂќ interface IQueueCallbackRead : IUnknown { void OnRead ( IWDFIoQueue* pWdfQueue, IWDFIoRequest* pWdfRequest, SIZE_T NumOfBytesToRead ); }; Device Driver Interfaces (DDI) KMDF and UMDF DDI are similar Tuned to language and runtime environment KMDF NTSTATUS WdfDeviceConfigureRequestDispatching( WDFDEVICE Device, WDFQUEUE Queue, WDF_REQUEST_TYPE RequestType, BOOLEAN Forward ); UMDF HRESULT IWDFDevice::ConfigureRequestDispatching( IWDFIoQueue * pQueue, WDF_REQUEST_TYPE RequestType, BOOL Forward ); Device parameter is implicit in C++ Driver Entry IDriverEntry is the top driver-exported interface interface IDriverEntry::IUnknown { HRESULT OnInitialize( IWDFDriver* pWdfDriver ); HRESULT OnDeviceAdd( IWDFDriver* pWdfDriver, IWDFDeviceInitialize* pWdfDeviceInit ); VOID OnDeinitialize(); }; OnInitialize and OnDeinitialize Do driver-wide initialization and cleanup OnDeviceAdd Invoked once for each new device detected by Windows Callback Objects Callback objects = Callbacks + Context Example: Creating Device Object HRESULT CMyDriver::OnDeviceAdd( IWDFDriver* pDriver, IWDFDeviceInitialize* pDeviceInit ) { IUnknown *pDeviceCallback = NULL; ... // Create callback object hr = CMyDevice::CreateInstance( &pDeviceCallback, 1 pDeviceInit, completionPort ); ... // Create WDF Device hr = pDriver->CreateDevice( pDeviceInit, pDeviceCallback, 2 &pIWDFDevice ); ... } Callback Objects (conвЂ™t) class CMyDevice : public IDevicePnpHardware { private: HANDLE WINUSB_INTERFACE HANDLE UCHAR ULONG ... public: virtual HRESULT stdcall // Callback interface exposed to // framework. m_CompletionPort; m_UsbHandle; m_BulkOutPipe; m_BulkOutMaxPacket; OnPrepareHardware( IWDFDevice* pDevice ); STDMETHOD( OnReleaseHardware )( IWDFDevice *pDevice ); // Factory method static HRESULT CreateInstance( IUnknown *pUnknown, IWDFDeviceInitialize *pDeviceInit, HANDLE CompletionPort ); ... }; Context Callback Callback Objects (conвЂ™t) static HRESULT CreateInstance( IUnknown **ppUnknown, IWDFDeviceInitialize *pDeviceInit, HANDLE CompletionPort ) { ... // Allocate our callback context 1 CMyDevice *pMyDevice = new CMyDevice(); ... // Get our callback interface 2 hr = pMyDevice->QueryInterface( __uuidof(IUnknown), (void **) ppUnknown ); ... return hr; } Callback Objects (conвЂ™t) 1 OnDeviceAdd IDriverEntry Callback Object WDF Driver 2 IWDFDriver::CreateDevice( вЂ¦ ) 3 WDF Device 5 Framework Provided by: Microsoft IHV IUnknown MyDevice 4 QueryInterface for вЂў IDevicePnP вЂў IDevicePnPHardware ---- IDevicePnpHardware Driver Summary Discussed driver loading/unloading, I/O data flow Driver installation and setup are same as WDM drivers Keep in the mind the вЂњtimeoutвЂќ polices in reflector Built-in verifier checks Error reporting via WER Discussed driver programming model KMDF and UMDF share same model UMDF DDI is based on C++ and COM-lite Callback objects = Context + Callbacks How to Develop a UMDF Driver Part 2 Outline Goals Getting Started Writing your Driver Installing your Driver Debugging the Driver Plug and Play / Power Management Design goals Design overview Device Driver Interface (DDI) PnP/PM driver callback example Goals How to start writing and debugging a UMDF driver How to interact with UMDFвЂ™s Plug And Play and Power Management support The basics of creating and configuring a device driver Writing Your Driver What is a User-Mode Driver? User-Mode (UM) Drivers are DLLs Provide driverвЂ™s вЂњcallback objectвЂќ classes Use COM programming pattern, not runtime At least, not very much of the runtime Expose standard COM entry points DllGetClassObject, DllRegisterServer, DllUnregisterServer Can write UM Drivers in C or C++ Implementing COM objects is easier in C++ Can use ATL with C++ for additional COM support WDF Supplement CD contains several examples This talk references the вЂњSkeletonвЂќ driver UMDF Driver DLL Exports DllMain Called when DLL loads (and unloads) Construct global objects, initialize tracing Dll[Un]RegisterServer Called by CoInstaller during device installation Skeleton sample uses ATL Rather than write another implementation DllGetClassObject Called on device arrival by COM to get вЂњclass factoryвЂќ DllCanUnloadNow Just return S_FALSE Common Driver Classes COM objects must implement IUnknown Independently, or with help from CUnknown base class UMDF driver implements these classes CClassFactory Instantiates your driver event handler CMyDriver Your Driver-Callback Class Must implement IDriverEntry Paired with an IWDFDriver object CMyDevice Your Device-Callback Class May implement IDevicePnpHardware and/or IDevicePnp Paired with an IWDFDevice object UMDF Skeleton Driver Example code based on UMDF Skeleton sample Code in slides should not be used as-is UMDF Skeleton does just enough to get loaded Boilerplate code found in all UM Drivers Minimal callback objects for driver and device Description of files ComSup.h & ComSup.cpp COM Support code вЂ“ provides classes for IUnknown & IClassFactory DllSup.h & DllSup.cpp DLL Support code вЂ“ provides implementation of required exports Depends on COM support code Driver.h & Driver.cpp Driver-Callback Class Device.h & Device.cpp Device-Callback Class вЂњTODOвЂќ comments mark where to add your driver code COM and DLL support files require no changes The driver and device files youвЂ™ll need to modify for your driver Example: CMyDriver Definition (Driver.h) class CMyDriver: public CUnknown, public IDriverEntry { IDriverEntry *QueryIDriverEntry(); HRESULT Initialize(); public: static HRESULT CreateInstance( PCMyDriver *Driver ); HRESULT OnInitialize( IWDFDriver *FxDriver ){ return S_OK; } HRESULT OnDeviceAdd(IWDFDriver *FxDriver, IWDFDeviceInitialize *FxDeviceInit); HRESULT OnDeinitialize( IWDFDriver *FxDriver ) { return S_OK; } ... // IUnknown methods, etc... }; Example: CMyDriver Implementation (Driver.cpp) HRESULT CMyDriver::CreateInstance( CMyDriver **Driver ) { CMyDriver *driver = new CMyDriver(); if (driver == NULL) { return E_OUTOFMEMORY; } HRESULT hr = driver->Initialize(); if (S_OK == hr) { *Driver = driver; } else { driver->Release(); } return hr; } HRESULT CMyDriver::Initialize() { HRESULT hr = S_OK; ... // Do any initialization that could fail here return hr; } Example: CMyDriver Implementation (conвЂ™t) HRESULT CMyDriver::OnDeviceAdd(...) { CMyDevice *deviceCallback; IWDFDevice *fxDevice; HRESULT hr = CMyDevice::CreateInstance( FxDeviceInit, &device ); if (S_OK == hr) { ... // Call SetLockingModel(), SetFilter(), etc... hr = FxWdfDevice->CreateDevice( FxDeviceInit, deviceCallback->QueryIUnknown(), &fxDevice ); // Release Reference from QueryIUnknown() deviceCallback->Release(); } if (S_OK == hr) {fxDevice->Release();} if (NULL != deviceCallback) {deviceCallback->Release();} return hr; } Example: CMyDevice Definition (Device.h) class CMyDevice : public CUnknown { HRESULT Initialize( IWDFDeviceInitialize *DeviceInit ) { return S_OK; } static HRESULT CreateInstance( IWdfDeviceInitialize *FxDeviceInit, CMyDevice **Device ); // Add IUnknown methods here } Writing Your Driver (Summary) Create the common code Required DLL Exports COM support classes Copy from skeleton, use existing ones (ATL), or write your own Implement CMyDriver class Including the OnDeviceAdd() method Allocate and initialize a CMyDevice object Create IWDFDevice object & connect to CMyDevice callbacks Implement CMyDevice class Add Device-Callback interfaces later Your driver should now load But canвЂ™t talk to your device or do I/O Next two talks will address that Installing Your Driver INF Based Installation Just like WDM and kernel-mode WDF drivers Device Matching, Driver Signing, etc... work normally User-Mode DriverвЂ™s INF does extra work Use UMDF CoInstaller Register Driver DLLs Configure the Driver List Setup UM Driver Key Add the Reflector driver We plan to simplify the installation for Beta 2 Still INF based, but more support from CoInstaller Registry Locations UMDF keeps information in several registry keys WeвЂ™ll refer to them using these names as we go Defined in the [Strings] section of the Skeleton INF Key Name Location %UMDF_Software% HKLM \ Software \ Microsoft \ Windows NT \ CurrentVersion \ WUDF %UMDF_Services% %UMDF_Software% \ Services %UMDF_Host% %UMDF_Services% \ {193a1820-d9ac-4997-8c55-be817523f6aa} Use UMDF CoInstaller System provided CoInstaller Sets Driver Manager to start automatically WUDFCoInstaller.dll is already installed No need to copy the file DriverвЂ™s INF must reference this CoInstaller [Skeleton.CoInstallers] AddReg = Skeleton.CoInstallers_AddReg [Skeleton.CoInstallers_AddReg] HKR,,CoInstallers32,0x00010000,вЂњWUDFCoInstaller.dllвЂќ Without the CoInstaller your driver may not start Driver canвЂ™t start if the Driver Manager isnвЂ™t running Problem code 37 in device manager Register Driver DLLs UMDF uses CoCreateInstance to load drivers This requires the driver to be вЂњregisteredвЂќ INF must register any user-mode drivers it copies Do this in the [DDInstall] section [Skeleton] CopyFiles=DriverCopy RegisterDlls=Skeleton.RegisterDlls [Skeleton.RegisterDlls] 11,,WUDFSkeleton.dll,1 Unregistered drivers will not load Problem code 43 in the device manager Configure the Driver List UMDF loads drivers by вЂњDriver NameвЂќ We recommend the binary name (without extension) UMDF Maintains its own driver list Lists drivers in order of attachment to the stack Drivers are listed by вЂњDriver NameвЂќ User-Mode drivers load above kernel-mode drivers MultiString stored under the device nodeвЂ™s key [Skeleton_AddReg] HKR, вЂњWUDFвЂќ, вЂњDriverListвЂќ, 0x00010000, вЂњWUDFSkeletonвЂќ If this is missing Problem 43 in device manager Setup UM Driver Key Create an entry under UMDF Services Key One for each driver installed Key name is the Device Name Contains UMDF-Specific Driver Information: The DriverвЂ™s CLSID Configure this in the INF Replace CLSID with your driverвЂ™s class ID. [Skeleton_AddReg] HKLM, %WUDF_Services%\WUDFSkeleton, вЂњComCLSIDвЂќ, 0, вЂњ{CLSID}вЂќ Without this: Problem 43 in device manager Adding the Reflector Driver Reflector driver is WUDFRd.sys Already installed on the system Your INF must make this the top-most kernel driver If youвЂ™re writing a UM function driver Assign reflector as service with AddService directive YouвЂ™ll need a service install section too If youвЂ™re writing a UM Upper-Level filter driver Assign reflector as top-most Upper Device Filter Without this UMDF is never loaded Device may start, but no host process Installing Your Driver (Summary) Use the UMDF CoInstaller Register your Driver DLLs with COM Configure the Driver List Setup UM Driver Key Record your driverвЂ™s CLSID Add Reflector driver to the kernel drivers If it doesnвЂ™t work: Is Driver Manager started? Does device manager show a problem code? Is WUDFHost.exe (host process) running ? Debugging Your Driver Debugging Overview Similar to service debugging UM Drivers cannot be started by the debugger No Just-In-Time debugging Host process starts when device is installed Plug & Replug the device to restart Or disable & re-enable in device manager Each device stack runs in host process WUDFHost.exe Child of Driver Manager service One stack per host-process for now Debugger Options WinDbg GUI Debugger Source and/or Assembly level debugging UMDF debugger extension available Can work as user-mode or kernel-mode debugger See resources slide to find download location Visual Studio Debugger WDK and Visual Studio arenвЂ™t currently integrated UMDF Debugger extension not available Must copy mspdb71.dll from WDK to use it WeвЂ™re concentrating support on WinDbg CDB & KD If you prefer command line debugging, these work User-Mode or Kernel-Mode Debugging Can debug UMDF with UM or KM debugger You can use WinDbg to debug either way UM Debugger Simpler and more familiar Have to attach to each host process when it starts KM Debugging Requires a second computer to run debugger More complex, but quite powerful Stops entire computer вЂ“ no UMDF timeouts Can be always running Catch UMDF Verifier problems like JIT debugger Can debug and set breakpoints in host process Use вЂњ.process /i <process object address>вЂќ to break into running host See additional slides for KM Debugging tips Enabling the Debugger Host process started by Driver Manager service You canвЂ™t attach debugger until after initialization Host Process supports an вЂњinitial breakpointвЂќ (IB) Host waits N seconds for debugger to attach Breaks into debugger once detected Continues running once N seconds elapse Timeout (in seconds) configured under UMDF_Host key HostProcessDbgBreakOnStart = N Enabling IB disables other UMDF timeouts Like those on PnP operations Initial Breakpoint is for UM Debugger (by default) Can be configured to watch for both UM & KM debugger Set high-bit in the timeout value 0x8000000 attempts once to break into either debugger Attaching the UM Debugger Cannot connect UM Debugger until host starts Enable the Initial Breakpoint Attach the device to the system Or enable it in the device manager If you have a single device attached Run вЂњwindbg вЂ“pn WUDFHost.exeвЂќ Repeat until it finds a host process to debug If you have multiple devices attached Find out process ID (PID) of the new host Use tasklist.exe before & after to find new host process Run вЂњwindbg вЂ“p PIDвЂќ UMDF Debugger Extension WudfExt.dll Copy into your path вЂњ!load WudfExt.dllвЂќ debugger command loads the extension Names are case sensitive Command !devstack !dumpirps !umirp !wdfdriverinfo !wdfdevicequeue !wdfqueue !wdfrequest !wdfitf2obj Description Shows device stacks in the host process Shows UM IRPs in the host process Shows a host IRP Shows info about a UM driver Shows the I/O queues for a device Shows an IoQueue Shows an IoRequest Converts an interface pointer to an object address for above extensions. Interesting UMDF Breakpoints (BP) Hopefully, this will get you started Event to debug Host attempts to load driver Driver Load Breakpoint (BP) OLE32!CoCreateInstance Watch for your CLSID MyDriver!DllMain Invoked first time when your DLL is loaded Called after that too, so clear the BP once it hits Creation of CMyDriver Driver attaches device to stack MyDriver!DllGetClassObject Invoked to get your class factory MyDriver!CMyDriver::CMyDriver Invoked when the factory calls new MyDriver!CMyDriver::OnDeviceAdd Driver creates a device to attach to the stack Tracing in Your UM Driver Recommend using WPP tracing for debug output Lightweight & always available, printf-style tracing Easily captured to disk, screen or (kernel) debugger Skeleton contains some basic tracing code See MSDN documentation on Event Tracing Collect output with tracelog.exe or traceview.exe Tracelog comes with Windows Traceview comes with WDK For more information see: вЂњCollecting & Viewing TracesвЂќ in additional slides MSDN & DDK documentation What Do I Do When It Crashes? (Summary) Check for configuration problems Is there a PNP problem code? Is there a host process running? Is there a .dmp file WUDF log file directory? %SystemRoot%\LogFiles\WUDF\*.dmp Attach a debugger to the host as it starts Or always enable the kernel debugger Watch for UMDF Verifier failures Walk through initialization Use list of interesting breakpoints Get debug output with WPP tracing Plug and Play / Power Management UMDF Design Goals for PnP/PM Coordinate I/O delivery to driver with PnP/PM events The framework handles complexities of PnP/PM Allow drivers to participate with optional callbacks Support FDO and filter driver scenarios No bus driver support for version 1 Same design as kernel mode WDF PnP/PM UMDF PnP/PM Design Implemented with a state machine Consumes PnP/Power messages from the reflector Suspends and resumes I/O queues as needed Calls the driver if desired through a set of driver provided callback functions Driver callbacks are logically grouped into interfaces IDevicePnpHardware IDevicePnp IDevicePnpSelfManagedIo Driver вЂњopts-inвЂќ by implementing one or more callback interfaces Software-only drivers generally donвЂ™t need any of these interfaces Most drivers will only need IDevicePnpHardware UMDF PnP/PM Interfaces IDevicePnpHardware First time hardware initialization / de-initialization OnPrepareHardware() OnReleaseHardware() IDevicePnp Device state change notifications OnD0Entry() OnD0Exit() OnSurpriseRemoval() OnQueryRemove() OnQueryStop() IDevicePnpSelfManagedIo Custom I/O processing notifications OnSelfManagedIoCleanup() OnSelfManagedIoFlush() OnSelfManagedIoInit() OnSelfManagedIoSuspend() OnSelfManagedIoRestart() Device Driver Interface (DDI) IDriverEntry::OnDeviceAdd Driver must implement this interface Called when framework receives вЂњAdd DeviceвЂќ message Driver should perform initialization that does not require access to hardware or lower level drivers Driver also creates a device object and device callback object (beyond the scope of this talk) HRESULT CMyDriver::OnDeviceAdd( IWDFDriver* pDriver, IWDFDeviceInitialize* pDeviceInit ) { // Read in driver properties INamedPropertyStore * pPropStore = NULL; hr = pDeviceInit->GetDevicePropertyStore( &pPropStore ); ... } IDevicePnpHardware OnPrepareHardware Called when device is first started Driver establishes connection to the device and performs one-time initialization HRESULT CMyDevice::OnPrepareHardware( IWDFDevice* pDevice ) { ... // Open the device hr = pDevice->GetDeviceName( pDeviceName, вЂ¦ ) m_Handle = CreateFile( pDeviceName, вЂ¦ ) ... // Initialize the device and look for endpoints if (WinUsb_Initialize( m_Handle, &m_UsbHandle )) { return DiscoverBulkEndpoints(); } IDevicePnpHardware OnReleaseHardware Called when device is removed or stopped Driver should essentially undo anything it did in OnPrepareHardware HRESULT CDevice::OnReleaseHardware( IWDFDevice* pDevice ) { // Close the USB handle and the deviceвЂ™s file // handle if ( m_UsbHandle ) { WinUsb_Free( m_UsbHandle ); } if ( m_Handle ) { CloseHandle( m_Handle ); } return S_OK; } IDevicePnp OnD0Exit Called each time device should power down Also called before the device is removed Stop deviceвЂ™s I/O target with вЂњleave pending I/OвЂќ flag hr = m_pIoTarget-> Stop( WdfIoTargetLeaveSentIoPending ); Save device state Set the device into low power state OnD0Entry Called each time device should power up Also called when the device starts up Set the device into working power state Restore any previously saved state Restart deviceвЂ™s I/O target hr = m_pIoTarget->Start(); IDevicePnp OnSurpriseRemoval Called when the device has unexpectedly detached from the PC Stop deviceвЂ™s I/O target with cancel flag hr = m_pIoTarget->Stop( WdfIoTargetCancelSentIo ) OnQueryRemove Allows driver to veto a device removal request HRESULT CDevice::OnQueryRemove( IWDFDevice* pDevice ) { return S_OK; // Allow device removal } OnQueryStop Allows driver to veto a device stop request HRESULT CDevice::OnQueryStop( IWDFDevice* pDevice ) { return E_FAIL; // Disallow device stop } IDevicePnpSelfManagedIo Notifications to drivers that perform I/O dispatching unmanaged by the framework OnSelfManagedIoInit() Start I/O dispatching OnSelfManagedIoSuspend() Pause I/O dispatching OnSelfManagedIoRestart() Resume I/O dispatching OnSelfManagedIoFlush() Cancel or complete all pending I/O OnSelfManagedIoCleanup() Free I/O dispatching mechanisms PnP/PM Driver Callback Example Start Device OnPrepareHardware() Device Driver Framework Start Device Off On Off Start Device OnD0Entry() Device Driver Framework Start Device Off On Off Device Operational Device Driver Framework On On Off Suspend Device OnD0Exit() Device Driver Framework Power Down On On Off Resume Device OnD0Entry() Device Driver Framework Power Up On On Off Remove Device OnD0Exit() Device Driver Framework Remove Device On On Off Remove Device OnReleaseHardware() Device Driver Framework Remove Device On On Off WDM Message to UMDF Callback Mapping Start -> Query Remove -> Remove IRP_MN_START_DEVICE: OnPrepareHardware() OnD0Entry() OnSelfManagedIoInit() IRP_MN_QUERY_REMOVE_DEVICE: OnQueryRemove() IRP_MN_REMOVE_DEVICE: OnSelfManagedIoSuspend() OnD0Exit() OnSelfManagedIoFlush() OnReleaseHardware() OnSelfManagedIoCleanup() WDM Message to UMDF Callback Mapping Start -> Surprise Removal -> Remove IRP_MN_START_DEVICE: OnPrepareHardware() OnD0Entry() OnSelfManagedIoInit() IRP_MN_SURPRISE_REMOVAL: OnSurpriseRemoval() OnSelfManagedIoSuspend() OnReleaseHardware() OnSelfManagedIoFlush() IRP_MN_REMOVE_DEVICE: OnSelfManagedIoCleanup() PnP/PM Timeouts Each WDM PnP/PM message has a timeout Currently, this timeout is set to 1 minute The reflector will abort the host process if this timeout is exceeded Each WDM Pnp/PM message can produce multiple driver callbacks, for example: вЂњAddDeviceвЂќ results in: OnInitialize OnDeviceAdd 1 minute IRP_MN_START results in: OnPrepareHardware OnD0Entry OnSelfManagedIoInit 1 minute Supplemental Slides Example: DllMain BOOL DllMain( HINSTANCE ModuleHandle, DWORD Reason, PVOID Reserved ) { if (DLL_PROCESS_ATTACH == Reason) { WPP_INIT_TRACING(вЂњMicrosoft\\UMDF\\UMDFSkeletonвЂќ); g_ModuleHandle = ModuleHandle; } else if (DLL_PROCESS_DETACH) == Reason) { WPP_CLEANUP(); } return TRUE; } See Skeleton\Host.cpp Example: DllGetClassObject HRESULT DllGetClassObject( REFCLSID ClassId, REFIID InterfaceId, PVOID *Interface ) { PCClassFactory factory; HRESULT hr; *Interface = NULL; if (!IsEqualCLSID( ClassId, __uuidof(MyDriverCoClass) )) { return CLASS_E_NOTAVAILABLE; } hr = CClassFactory::CreateInstance(&factory); if (S_OK == hr) { hr = factory->QueryInterface(InterfaceId, Interface); factory->Release(); } return hr; } Example: DllRegisterServer & DllCanUnloadNow HRESULT DllRegisterServer() { return UpdateCOMRegistration( g_ModuleHandle, IDR_MYDRIVER_CLASSINFO, true, __uuidof( MyDriverCoClass ), LвЂњUMDF Skeleton Sample DriverвЂќ ); } HRESULT DllUnregisterServer() { return UpdateCOMRegistration(..., false, ...) } HRESULT DllCanUnloadNow() { return S_FALSE; } Example: CUnknown Definition class CUnknown : public IUnknown { LONG m_RefCount; public: CUnknown() { m_RefCount = 1; } virtual ~CUnknown() { return; } IUnknown *QueryIUnknown(){ AddRef(); return (IUnknown *)this; } ULONG AddRef(); ULONG Release(); HRESULT QueryInterface( REFIID InterfaceId, PVOID *Interface ); }; Example: CUnknown Implementation ULONG CUnknown::AddRef(){ return InterlockedIncrement(&m_RefCount); } ULONG CUnknown::Release() { ULONG count = InterlockedIncrement(&m_RefCount); if (count == 0) { delete this; } return count; } HRESULT CUnknown:QueryInterface(...) { if (IsEqualIID(InterfaceId, __uuidof(IUnknown)) { *Interface = QueryIUnknown(); return S_OK; } *Interface = NULL; return E_NOINTERFACE; } Example: CClassFactory Definition class CClassFactory : public CUnknown, public IClassFactory { public: IClassFactory *QueryIClassFactory() {...} // IUnknown AddRef() {return __super::AddRef()} Release() {return __super::Release()} QueryInterface(...); // IClassFactory HRESULT CreateInstance( IUnknown *Outer, REFIID InterfaceId, PVOID *Object ); HRESULT LockServer(BOOL Lock) { return S_OK; } }; Example: CClassFactory Implementation HRESULT CClassFactory::QueryInterface(...) { if(IsEqualIID(Interface, __uuidof(IClassFactory)) { *Object = QueryIClassFactory(); return S_OK; } else { return CUnknown::QueryInterface(...); } } HRESULT CClassFactory::CreateInstance(...) { PCMyDriver driver; HRESULT hr = CMyDriver::CreateInstance(&driver); if (S_OK == hr) { hr = driver->QueryInterface(InterfaceId, Object); driver->Release(); } return hr; } Debugging with WinDbg Source Level GUI debugger (Most) commands work on addresses or symbols ModuleName!FunctionName ModuleName!ClassName::MethodName Best to always use fully resolved names Setting Breakpoints вЂњbp <addr>вЂќ sets an excution breakpoint Use bu if the functionвЂ™s module isnвЂ™t loaded yet вЂ�ba [w|r] [1|2|4|8] <addr>вЂ™ sets a watchpoint ba r 4 MyDriver!g_MyArrayLength Dumping Memory d<type> [address] [L<length>] type = byte, word, char, unicode, dword, quadword, string dd MyMyDriver!g_MyArrayLength L1 dv dumps local variable names Dumping Types dt <variable name> dumps a specific local dt <addr> <typename> dumps an address or symbol as a type dt ??? MyDriver!CMyDevice See the WinDbg help for more details Debugging with a Kernel Debugger WinDbg can be used as a kernel debugger Must point Kernel debugger to host process Automatic if the process requests a kernel break-in Manually through the .process command вЂњ!process 0 0вЂќ will list all process object addresses Must reload user-mode symbols after attaching вЂњ.reload /userвЂќ Or the stack trace wonвЂ™t have any symbols Can set breakpoints on user-mode addresses Must load user symbols first Cannot break into a running host process Must wait for a breakpoint UMDF вЂњVerifierвЂќ will break into KD if attached Last chance to debug before process termination Collecting & Viewing Traces TraceLog.exe lets you control trace sessions To start a session Tracelog.exe -start MyLogger -guid MyDriver.ctl -level 255 -flag 65535 -f MyLogFile.etl To end a session Tracelog.exe -stop MyLogger To print a session TraceFmt вЂ“o MyLogFile.txt -p symbols.pri/TraceFormat MyLogFile.etl Or use the GUI вЂњTraceViewвЂќ tool Use in place of TraceLog or TraceFmt Resources: вЂњWPP Software TracingвЂќ page in DDK documentation MSDN online page for these tools: http://msdn.microsoft.com/library/default.asp?url=/library/enus/ddtools/hh/ddtools/tracetools_8eccb8f7-6f29-4683-87bdfa83618c32eb.xml.asp How to Develop a UMDF Driver: Part 3 Outline I/O Processing Overview I/O Queues File Objects Driver Layering I/O Targets Cancellation Goals A better understanding of: How to incorporate I/O processing in a UMDF driver Framework objects involved with I/O Request processing Knowledge of where to find resources for UMDF I/O Request Processing Overview I/O Request Processing in UMDF YouвЂ™ve seen WDF Driver and Device objects These are used to configure a device stack I/O processing involves many more objects for: Flow control and internal request routing Per request context and callbacks Connections to other drivers in the stack and/or system And some concepts that span across objects: Driver Layering Cancellation Framework Objects Driver Device Request Memory (Input) Memory (Output) Queue File I/O Target Framework Objects These objects are associated with request processing All derive from IWDFObject Object Description Device The information associated with a single layer in a device stack Request An I/O operation Either sent to the driver or initiated by the driver to a lower device A flow control mechanism for Requests An open handle to the device and any context the driver needs to store with it Another driver to which the Driver can send Requests Either another user-mode layer in the device stack, the kernel-mode portion of the device stack, or the top of another device stack entirely. Queue File I/O Target Memory A buffer associated with a request I/O Request Processing вЂ“ A BirdвЂ™s Eye view Request I/O Queue Driver I/O Target Complete I/O Request Object Request I/O Queue Driver I/O Target Complete I/O Request Object Represents a request Sent to the driver by a client An application or another UM driver Generated by a driver Types of Requests presented to driver Create Read / Write / DeviceIoControl Cleanup Close Request Parameters can be obtained from IWDFIoRequest interface I/O Queues I/O Queues Request I/O Queue Driver I/O Target Complete I/O Queues Queues provide flow control for I/O Requests All requests dispatched to driver through I/O Queues Driver can configure I/O routing for a device Create one or more queues for a device Configure routing for a type of I/O to a particular queue вЂњDefault queueвЂќ handles any remaining I/O types I/O Queue Dispatch Types Dispatch Type controls how requests are presented to driver Queues allow following modes of dispatching: Automatic: Queue presents requests via callbacks (Push Model) Manual: Requests are retrieved by driver (Pull Model) Dispatch type is set at Queue creation time It is a per-Queue property Automatic Dispatch Queue presents request through driver implemented callback interfaces IQueueCallbackCreateClose IQueueCallback[Read | Write | DeviceIoControl] Automatic Dispatch Types Sequential: allows at most one outstanding request at a time New Request not presented until current request is completed Parallel: allows multiple outstanding requests New Request can be presented even when previously presented requests are not completed The number of parallel requests presented is bounded Driver should minimize blocking in presentation callbacks Manual Dispatch Driver pulls requests from the queue Typically starts in response to Queue callback IQueueCallbackStateChange Empty to non-empty transition Continues to pump I/O until вЂњdoneвЂќ No more I/O, bookmark request retrieved, error, etc... Starts again on next Queue state change HRESULT RetrieveNextRequest( OUT IWDFIoRequest** ppRequest ); It is possible for driver to pull requests from an Automatic Queue Callback Constraints Callback constraints specify locking model for Queue callbacks Callback constraints options Device Level: Callbacks invoked with device level lock held None: Callbacks invoked with no lock held Specified at device creation time via IWDFDeviceInitialize::SetLockingConstraint Set before creating the WDF Device object Per device property вЂ“ applies to all queues Callback Constraints (conвЂ™t) Constraints apply only to Queue Callbacks Queue callbacks include Automatic Dispatch Callbacks Queue state change callback Request cancellation callback If Device Level locking is used: The above callbacks are synchronized Request Completion is a not a Queue Callback вЂ“ not synchronized Unsynchronized code can call IWDFObject::AcquireLock Call on object that matches your synchronization scope Dispatch Type vs. Locking Model Combining Dispatch Type and Locking Model provides several modes of operation For example: Sequential Queue Device Level Locking Parallel Queue Device Level Locking Request1 Request1 Req1 Complete Request2 Request2 Req2 Complete Req1 Complete Req2 Complete Parallel Queue No Locking Request1 Request2 Req1 Complete Req2 Complete UMDF OSR USB Sample Walk-through Requests and Queue Usage in the sample driver (src\umdf\usb\driver) Callback locking constraint used (CMyDevice::Initialize in Device.cpp) Dispatch type used (CMyQueue::Initialize in Queue.cpp) Queue callbacks used (CMyQueue in Queue.h and Queue.cpp) File Objects File Object File Object represents open connection to device It is the session context for I/O All requests associated with a File Object in UMDF KMDF and WDM requests sometimes donвЂ™t have one File object for a request obtained using IWDFIoRequest::GetFileObject Trailing name used by client while opening connection is available via IWDFFile::GetFileName File Object (conвЂ™t) Device File1 Request1 Request2 File2 Request1 Request2 File Object Lifetime File ObjectвЂ™s lifetime spans Create: File Object gets created in response to a connection being opened Cleanup: Notification of connection being torn down and that Close is pending Close: All I/O pertaining to this File Object has now ceased. File Object is now disposed. File Object is created and destroyed by the Framework All I/O operations happen in the context of File object i.e., they happen between Create and Close These operations are: Read / Write / DeviceIoControl File Object Lifetime Illustrated Example of I/O sequence between App and Driver Application hFile = CreateFile(вЂ¦ вЂ¦ Async/Sync Read/Write/IoCtl вЂ¦ CloseHandle(hFile); Driver Create Request вЂ¦ Read/Write/IoCtl Requests вЂ¦ Cleanup вЂ¦ Any remaining Requests drain вЂ¦ Close Cleanup Handling in Driver Cleanup received when client closes connection Notification for driver to flush I/O for File Object Cancel or complete outstanding I/O as soon as possible Close will not come until all I/O is finished Cleanup is a вЂњcriticalвЂќ operation in UMDF Cannot fail, subject to timeout Cleanup is not the end of I/O operations ThatвЂ™s the Close Request I/O received after a Cleanup should be cancelled/completed immediately UMDF OSR USB Sample Walk-through File usage in the sample driver (src\umdf\usb\driver) (Queue.cpp) CMyQueue::OnRead CMyQueue::OnCreateFile CMyQueue::OnCleanupFile CMyQueue::OnCloseFile Driver Layering Driver Layering UMDF supports driver layering Multiple drivers build a device stack вЂњFunctionвЂќ driver provides core device behavior вЂњFilterвЂќ drivers modify aspects of device behavior Filter is a property set at device creation time All Framework Objects are per layer Each layer works only with its own objects e.g., each layer gets a Request object to complete Driver sends request to next layer using I/O Target Represents the next driver in the stack That driver may be in user mode or kernel mode Driver Layering Diagram Framework Device Queue File Request Framework Device Queue File Request Framework Device Device Stack Queue File Request Request Completion When Driver receives a Request it can Complete the Request synchronously Forward it to an I/O Target or an I/O Queue Hold on to it to complete later Driver must complete a Request it receives e.g., while forwarding request to I/O Target Driver must register request-completion-callback object Framework invokes callback when target completes request Callback must complete request or arrange for completion UM IRP not complete until all layers complete their Request objects Completion callback is not a device level event Runs outside driverвЂ™s callback locking constraints Request Completion Illustrated Request Completion Routine Request Completion Routine Request I/O Target I/O Target Request I/O Queue Driver I/O Target Complete I/O Target Framework Object Provides a way to send requests to another device Local I/O Target represents: The next device in the stack Another UM Driver, or the KM portion of the stack Driver doesnвЂ™t need to care which it is Remote I/O Target represents Some other UM or KM device stack Need feedback to prioritize this for Longhorn I/O Target is responsible for Sending I/O request to lower device Detecting completion and invoking callback interface Local I/O Target Application Device I/O Target Device I/O Target Device I/O Target User Mode Kernel Mode Up Device Down Device Device Device Device Stack Reflector I/O Target Functionality State based I/O handling Driver can start and stop the I/O target In Response to a PnP Transition For any driver specific reason (e.g., reconfigure after reset) Supports two I/O modes: Synchronous for short-term operations Asynchronous with callback for long-term operations Supports request timeout Outstanding request is cancelled when timeout expires Tracks sent requests for the driver Allows automatic purge or flush on I/O target stop Coordinates completion and cancellation Bridging UM and KM stacks I/O Target provides bridge between KM and UM drivers Bottom-most I/O Target sends requests to kernel-mode stack Driver could also вЂњescapeвЂќ to the Platform API Send I/O using Win32 File I/O API directly Advantages of using I/O Target Handles complexity of coordinating completion, cancellation and cleanup Allows for filtering and layered stacks transparently Allows routing of request to kernel mode in mode neutral way Offers rich functionality In Beta 1 Bottom-most I/O Target uses Win32 File I/O API internally No way to use specific API (e.g., WinUSB) Makes the escape necessary in such cases UMDF OSR USB Sample Walk-through I/O Target usage in the sample filter (src\umdf\usb\filter) Obtaining default I/O Target (CMyQueue::Initialize in Queue.cpp) Forwarding request down the stack (CMyQueue::OnWrite in Queue.cpp) (CMyQueue::ForwardRequest in Queue.cpp) Request Cancellation Request Cancellation Application can cancel a request at any time by Using CancelIo[Ex] API Exiting application, etc. Higher layer driver can cancel sent requests Cancel tells driver to complete request soon But not necessarily immediately Driver should abort any long operations Short synchronous requests can just be allowed to complete normally Cancel is a critical operation Cannot be failed, subject to timeout, etcвЂ¦ Cancellation is part of good user experience Cancellation Overview Request Owner can register a cancel callback Cancel callback follows locking constraints On Cancel: RequestвЂ™s internal state is marked as cancelled Any callback registered after this will run immediately Registered cancel callback is cleared then invoked In the cancellation callback Owner arranges to cancel and complete request Remove callback before transferring ownership e.g., when forwarding or completing the Request Request Ownership Request ownership starts with I/O Queue Request ownership moves from: Queue to Driver вЂ“ Driver receives the Request Driver to Queue вЂ“ Driver forwards Request to Queue Driver to I/O Target вЂ“ Driver forwards Request to I/O Target Queue or I/O Target handle cancellation when they own request I/O Target notifies you through completion callback Driver must handle cancel when it owns request If it holds on to the request for a long time Cancellation Handling in Driver When driver receives a Request, it may: Complete it soon Shortly send it to I/O Target Queue it back to Framework I/O Queue Hold on to it (not using Framework I/O Queue) Do (potentially) lengthy sync/asynch processing Driver needs to handle cancellation only in the last two cases Cancellation Handling in Driver (conвЂ™t) Driver may register a cancel notification callback void IWDFIoRequest::MarkCancelable( IRequestCallbackCancel* pCancelCallback ); In callback it should cancel/complete the request As soon as possible Unregister callback when transferring ownership Before sending request to I/O target or completing it HRESULT IWdfIoRequest::UnmarkCancelable(); Failure return value indicates request has been canceled Cancel routine has run or will run soon Owner must ensure Request is completed only once Cancellation Illustrated Let us take the example of OSR USB Driver This driver uses device level locking It submits I/O requests to WinUSB The internal completion routine manually uses device level lock Request state is stored in Request context There are the following possibilities: 1. Request completes without cancellation 2. Request is cancelled 2a. Cancel callback runs before completion callback 2b. Cancel callback runs after completion callback The driver makes sure that: Request is completed only once Request is not completed until both completion and cancellation callback are done with it Cancellation Illustrated (1) OnRead* вЂ¦ Req->MarkCancelable вЂ¦ WinUSB_ReadPipe вЂ¦ OnCancel* вЂ¦ if (ctx->state == RequestCompleted) { CompleteRequest } else { CancelIoEx ctx->state = CancelInvoked; } * Invoked under DeviceLock OnUSBReadComplete вЂ¦ DeviceLock->AcquireLock(); if (Req->UnmarkCancelable()) { DeviceLock->ReleaseLock(); CompleteRequest } else { if (ctx->state == CancelInvoked) { DeviceLock->ReleaseLock(); CompleteRequest } else { ctx->state = RequestCompleted; DeviceLock->ReleaseLock(); } } Cancellation Illustrated (2a) OnRead* вЂ¦ Req->MarkCancelable вЂ¦ WinUSB_ReadPipe вЂ¦ OnCancel* вЂ¦ if (ctx->state == RequestCompleted) { CompleteRequest } else { CancelIoEx ctx->state = CancelInvoked; } * Invoked under DeviceLock OnUSBReadComplete вЂ¦ DeviceLock->AcquireLock(); if (Req->UnmarkCancelable()) { DeviceLock->ReleaseLock(); CompleteRequest } else { if (ctx->state == CancelInvoked) { DeviceLock->ReleaseLock(); CompleteRequest } else { ctx->state = RequestCompleted; DeviceLock->ReleaseLock(); } } Cancellation Illustrated (2b) OnRead* вЂ¦ Req->MarkCancelable вЂ¦ WinUSB_ReadPipe вЂ¦ OnCancel* вЂ¦ if (ctx->state == RequestCompleted) { CompleteRequest } else { CancelIoEx ctx->state = CancelInvoked; } * Invoked under DeviceLock OnUSBReadComplete вЂ¦ DeviceLock->AcquireLock(); if (Req->UnmarkCancelable()) { DeviceLock->ReleaseLock(); CompleteRequest } else { if (ctx->state == CancelInvoked) { DeviceLock->ReleaseLock(); CompleteRequest } else { ctx->state = RequestCompleted; DeviceLock->ReleaseLock(); } } UMDF OSR USB Sample Walk-through Cancellation walk-through in the sample driver (src\umdf\usb\driver) (Queue.cpp) CMyQueue::OnRead CMyQueue::OnCancel CMyQueue::CompletionThread Putting It Together YouвЂ™ve seen the following portions of the sample: Driver (Driver.cpp) CMyDriver::OnDeviceAdd Device (Device.cpp) CMyDevice::OnPrepareHardware CMyDevice::OnReleaseHardware Queue (Queue.cpp) CMyQueue::OnCreateFile CMyQueue::OnCleanupFile CMyQueue::OnRead / CQueue::OnWrite CMyQueue::OnCancel CMyQueue::CompletionThread Call to Action Install the Windows Driver Kit Join the WDF Beta Program At http://beta.microsoft.com Guest ID: Guest4WDF Evaluate UMDF for your driver projects Consider development time, customer support for system crashes, etc. Send Us Feedback вЂ“ We want to know If UMDF will meet your needs What stops you from writing your drivers with UMDF Additional Resources Email umdffdbk @ microsoft.com Web Resources: WDF Information: http://www.microsoft.com/whdc/driver/wdf/default.mspx Windows Debugger: http://www.microsoft.com/whdc/devtools/debugging/default.mspx External Resources вЂњIntroduction to the Windows Driver Foundation: How To Develop Device Drivers Using the Kernel Mode Driver FrameworkвЂќ from OSR Press Release date is September 2005 Focuses on KMDF but provides general WDF information as well В© 2005 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.