1. How to Develop a KMDF Driver

2. Outline WDF Object model DDI Organization Object context memory Object lifetime WDF Request Flow Through the Driver Request processing Stages WDFQUEUEs Request forwarding and Servicing Cancellation Power management and I/O PNP and Power management Direction we want to go in A brief design overview WMI WDFIOTARGET In stack Opened by name USB

3. Windows Driver Foundation- Experience

4. Windows Driver Foundation Object Model Expresses WDF concepts and DDIs within an object model Defines a uniform set of behaviors for all objects Scales from simple to complex abstractions Isolates internal implementation details Uses object concepts familiar to WDM driver developers

5. Windows Driver Foundation Object Model Objects are the basis of WDF Represent drivers, devices, queues, etc. Have properties, methods, and events Provide a driver-configurable context memory Are reference counted Organized hierarchically (parent/child relationship) Hierarchy allows for automatic destruction of objects Referenced by handles, not pointers

6. Interacting with WDF Objects The driver interacts with WDF objects through the DDIs Driver actions Creates objects it requires Defines callback routines to handle events for each object Defines type and allocation of any context memory Invokes DDIs on an object in response to events WDF actions: Manages reference counts for objects Manages object parent/child relationships Calls driver-defined callback routines when events occur Takes default action when driver does not specify a callback WDF does the right things by default without any work by the driver

7. Object DDIs Properties Replace direct field access Get and Set Values “Can’t fail”, have no status return Methods Perform operations on the object Have optional return status Events Notify the driver of state changes C functions registered by the driver Invoked by WDF when event occurs

8. DDI Conventions All references to WDF objects are through handles Handle is the first parameter to each WDF DDI Property naming convention: Wdf Get Wdf Set Example: WdfDeviceGetDriver(WDFDEVICE Device) Method naming convention: Wdf Example: WdfObjectDelete(WDFOBJECT Object) Event naming convention: Evt Example: EvtObjectCleanup(WDFOBJECT)

9. Provides storage for a driver’s object-specific information Similar to a device extension Can be associated with any WDF object Allocated from non-paged pool in driver-supplied size and type Exists for the lifetime of the WDF object WDF frees the memory when the object is destroyed Macros assist in defining the type from a standard C structure Accessed through pointer retrieved through the object handle Object’s can have more than one context, if the types differ Optional callbacks assigned per context Each context can be hooked into the destruction of an object EvtObjectCleanup and EvtObjectDestroy: described later Object Context Memory

10. Object Lifetime WDF objects are reference counted WDF maintains a reference on an object until it is deleted Driver typically does not have to maintain references BUT driver may extend an object’s lifetime by taking its own reference: VOID WdfObjectReference(WDFOBJECT Object) VOID WdfObjectDereference(WDFOBJECT Object) Calls to WdfObjectReference and WdfObjectDereference must be balanced to prevent object leaks

11. Object Lifetime Events EvtObjectCleanup event Invoked when an object is being deleted Object may still have references Similar to IRP_MJ_CLEANUP Drivers should release any references added upon this notification Used to resolve circular references EvtObjectDestroy event Invoked when object reference count goes to zero Handle and any associated context memory are destroyed Similar to IRP_MJ_CLOSE

12. Object Parenting Parent/child relationships established at object creation Parent holds reference count on each child When the parent object is deleted, the child objects are deleted automatically Child objects are deleted, then the parent Some objects have pre-defined parents Advantages Helps to automate object cleanup for the device driver Failures in initialization paths, such as EvtDriverDeviceAdd, automatically release any objects associated with the WDFDEVICE

13. Core Windows Driver Foundation Objects Unique types are defined for each WDF object handle Core objects common across most drivers WDFDRIVER WDFDEVICE WDFQUEUE WDFREQUEST Some additional utility object examples WDFDPC WDFWORKITEM WDFTIMER WDFDMAENABLER WDFIOTARGET WDFWMIDATABLOCK WDFMEMORY

14. WDF Request Flow IRP Dispatcher Pnp/Power Package I/O Package Read/Write/Ioctls/ Create/Close/Cleanup WMI Package Hardware Resource Management (DMA, Interrupt, I/O) Parallel Queue Sequential Queue Manual Queue IoTarget WDFREQUEST Next Driver Pnp/Power Events IRP Next Driver Driver

15. Request Processing When a request arrives from WDM, it is dispatched for action: PnP/Power package Handles PnP and power requests Notifies other packages of status changes Windows Management Instrumentation (WMI) package Handles WMI requests, including event tracing I/O package Handles most I/O requests I/O target Issues requests to another driver

16. Request Processing (con’t) Each package operates on the request by one or more of the following: Raising events to the driver Forwarding the request to another package or I/O target for further processing Completing the request based on its own action Completing the request as a result of a driver API call If the request has not been processed when it reaches the end of frameworks processing: Filter drivers forward the request to the next lower driver automatically Other drivers complete the request with STATUS_INVALID_DEVICE_REQUEST

17. IRP Dispatcher Pnp/Power Package I/O Package Read/Write/Ioctls/ Create/Close/Cleanup WMI Package Hardware Resource Management (DMA, Interrupt, I/O) Parallel Queue Sequential Queue Manual Queue IoTarget WDFREQUEST Next Driver Pnp/Power Events IRP I/O Processing Pnp/Power Events Pnp/Power/WMI IRPs

18. I/O Processing Arriving requests are sorted into WDFQUEUEs WDFQUEUEs present requests to the driver Processes two categories of I/O requests Open, cleanup and close Read, write, and device I/O control Interacts with the PnP/Power package Receive notification of Device removal System and device power state Surprise removal Respond to queries based on current I/O operations outstanding Interacts with operating system’s I/O cancellation model

19. Create, Cleanup, Close Handling IRP_MJ_CREATE, IRP_MJ_CLOSE, and IRP_MJ_CLEANUP requests generate events EvtDeviceFileCreate EvtDeviceFileClose EvtDeviceFileCleanup If no callback is registered Allows CREATE by default Automatically handles CLEANUP and CLOSE CREATE requests result in creation of a WDFFILEOBJECT object Driver can configure an exclusive open policy and let the framework handle it

20. Request Object WDFREQUEST is the WDF representation of an IRP Presented by WDF to the driver as the result of an I/O request Can also be created by the driver and presented to WDF to send I/O to another driver Object properties represent IRP fields As with all WDF objects Has a reference count Allows driver context memory Automatically frees child resources on completion Such as associated memory buffers or MDLs

21. WDFQUEUE Object Presents requests from WDF to the device driver Operates as an I/O adapter Enqueues and dequeues requests Controls the concurrency of requests presented to the driver Allows processing to pause and resume Supports request cancellation and cancel-safe queues Synchronizes I/O operations with PnP/Power state transitions Reports outstanding I/O operations to PnP/Power stage Optionally serializes event callbacks Defers event callbacks to comply with PASSIVE_LEVEL constraints Tracks “in-flight” requests currently being serviced by the driver More than just a list of pending requests!

22. WDFQUEUE Events WDFQUEUE objects use callbacks to notify driver of WDFREQUEST events EvtIoRead – Called for IRP_MJ_READ requests EvtIoWrite – Called for IRP_MJ_WRITE requests EvtIoDeviceControl – Called for IRP_MJ_DEVICE_CONTROL requests EvtIoDeviceControlInternal – Called for IRP_MJ_INTERNAL_DEVICE_CONTROL requests EvtIoStop – Called when a power state change has been requested EvtIoDefault – Called for any request that does not have a specific callback registered EvtRequestCancel – Called when a specific WDFREQUEST is cancelled

23. Mapping of Requests to Queues A driver typically creates multiple queues for different request characteristics Power management options Number of requests serviced at a given time Hardware resource mapping The driver controls which requests go to which queue WDF can automatically forward specific requests to a WDFQUEUE with WdfDeviceConfigureRequestDispatching Driver can receive requests on one WDFQUEUE and manually forward them to another with WdfRequestForwardToIoQueue

24. WDFQUEUE Concurrency Control “In-flight” requests Requests that a driver has received from a WDFQUEUE but has not yet completed Driver can control the concurrency of “in-flight” requests WDFQUEUE supports three request concurrency models: Sequential - single request model Similar to current Start I/O model New requests are not delivered until the previous request is completed Parallel model - any number of requests may be active at once Manual model - driver retrieves requests at its own pace A driver can create multiple WDFQUEUES of different types to sort requests based on the device’s concurrency model

25. Request Cancellation And Suspension The operating system may request that the driver stop processing an “in-flight” request WDM I/O cancellation from thread/process exit, or cancel API System PnP/Power events such as hibernation Device removal In some cases the system wants the request Cancelled, or completed with an error code In other cases the system wants request processing to temporarily pause, or Suspend Driver will be notified later to resume processing

26. Framework Handling of Request Cancellation And Suspension Requests that have not been delivered to the driver (still in queue) can be canceled or suspended automatically Any request received by the framework and not yet delivered to the driver is automatically cancelable Request will be completed by the framework on WDM I/O cancellation Requests received by the framework and not yet delivered to the device driver can affect the power state of the device Framework can automatically restore device power before delivering the request to the driver Framework can automatically stop/start the queue in response to PnP/Power events Configurable based on power policy

27. Driver’s Responsibility For Request Cancellation To avoid race conditions, “in-flight” requests cannot be cancelled unless explicitly made cancelable by the driver A request should be made cancelable by the driver if: The request involves a long term operation The request might never succeed (such as waiting for asynchronous input) The driver makes a request cancelable by calling WdfRequestMarkCancelable When a request is cancelled: The framework invokes EvtRequestCancel to notify the driver The driver must eventually complete the request

28. WDFQUEUE Power Management Power management of WDFQUEUEs Enabled by default Configurable on a per WDFQUEUE basis Advantages of power-managed queues Notify PnP/Power package of arriving I/O requests so that device power can be automatically restored Notify PnP/Power package of empty queue so that device can be powered down through its idle timer Notify driver of power-state changes for “in-flight” requests through the EvtIoStop callback A driver can use both power-managed and non- power managed queues Sort requests based on requirements for its power model

29. Driver’s Responsibility For Request Suspension Requests may be suspended due to: A system suspend power event A system hibernation power event In-flight requests are notified of power state transitions by the EvtIoStop event callback for their WDFQUEUE Ignoring EvtIoStop events delays the power state transition until all in-flight I/O requests are complete Drivers should handle EvtIoStop events for Long-running requests Requests that might not complete, such as asynchronous input Handling EvtIoStop provides a good user experience for laptops and other power-managed systems System logs which devices delay power state transitions

30. Request Suspension (con’t) A driver can respond to an EvtIoStop event by: Completing the request Re-queuing the request Acknowledging the event but continuing to hold the request Ignoring the stop event if the current request will complete in a timely manner Some EvtIoStop events require the driver to complete the request immediately Device removal or surprise removal request Signaled by WDF_REQUEST_STOP_ACTION_FLAGS

31. Driver Control of WDFQUEUEs WDFQUEUEs may pause and resume the delivery of requests in response to Power state changes, based on power policy Driver API calls such as WdfIoQueueStop Both the driver and power management must allow processing for requests to be delivered Requests sent while a WDFQUEUE is paused will be delivered when the queue resumes

32. Synchronization of WDFQUEUE Events Outstanding I/O request synchronization I/O requests received from a WDFQUEUE are asynchronous Requests may be completed within an event callback or after return from it Driver controls number of concurrent I/O operations through WDFQUEUE request concurrency type Parallel Sequential Manual (driver control) Constraints on concurrent execution of event callbacks Set in WDF_OBJECT_ATTRIBUTES Control the number of simultaneously executing event callbacks, not actual I/O operations Help manage access to shared data in the WDFQUEUE context memory Callbacks can have PASSIVE_LEVEL constraint WDFQUEUE automatically invokes the callback from a system work item if required So you don’t have to worry if an upper level driver calls you at DISPATCH_LEVEL

33. IRP Dispatcher I/O Package Read/Write/Ioctls/ Create/Close/Cleanup WMI Package Hardware Resource Management (DMA, Interrupt, I/O) Parallel Queue Sequential Queue Manual Queue IoTarget WDFREQUEST Next Driver Pnp/Power Events IRP I/O Processing Pnp/Power Events Pnp/Power/WMI IRPs Pnp/Power Package

34. Motivation for a Deeper Abstraction Around PnP and Power Management WDM drivers are too complicated PnP and Power are separate and unsynchronized concepts Learning all the rules in the DDK takes years There are lots of rules that aren’t easy to find in the DDK What are all the rules? I keep on finding them! Complexity takes time to fully test Bugs remain in even the most mature code Most drivers go through many revisions The fear of unknown side effects makes forward progress difficult Rules + LOC + Test = a minimal implementation

35. Motivation for a Deeper Abstraction Around PnP and Power Management WDM drivers have thousands of lines of code for PnP/PM Code is required for all IRPs, even if the device doesn’t implement them A lot of boilerplate code must be added before you can get started Few understand the boilerplate code Modifying it is very difficult due to unknown side affects The code distracts from what is really going on in the driver Advanced functions and practices were left to drivers and not encapsulated in the OS layer Partly because the burden on driver writers wasn’t well understood

36. Motivation For A Deeper Abstraction Around PnP and Power Management A minimal implementation is not a “good citizen” as defined by the OS Everybody is sensitive to time-to-market “Good citizenship” involves too many things Support PnP Support “Removal” to enable upgrade without a reboot, hot-plug Support “Surprise Removal” to allow a user to yank a plug Support “Rebalance” to enable other devices to be hot-plugged Support Power Management Support S-state IRPs to allow the system to go to sleep Convert them to D-state IRPs to ensure that your device context is preserved Support “Fast Resume” so that the system will be usable more quickly Aggressive Power Management Support Wait/Wake Support idle-time power management to save power while the system is running

37. WDF Design Goals for PnP/PM Remove as much boilerplate as possible Allow driver to provide callbacks only for events that are “interesting” Automatically provide good default PnP behavior Rebalance Removal Surprise Removal Automatically provide good default power behavior Support Sleep, Hibernate Support “Fast Resume” Support idle-time power management Provide clear error-handling paths Some software errors automatically handled Some hardware errors handled by resetting the device

38. WDF Design Goals for PnP/PM Call all PnP/Power-related driver callbacks at PASSIVE_LEVEL, even for non power pageable stacks Reduce the size of the code in a driver The code that is there is the essence of your driver Make all PnP and PM transitions consistent This makes it possible to test all of the PnP/PM code in a driver Remove the need for a driver to track state No need to keep a history of PnP/Power IRPs No need to guess what action is necessary based on target system state Manage device handle lifetime Make ordering guarantees Allow a driver to interact directly with WDM, if necessary Interacting with WDM unnecessary in the common case

39. Integration of PnP and Power WDF treats PnP and Power as a unified model You can’t turn a device on if you don’t know how to configure it You can’t configure a device if you don’t know how to turn it on Most PnP operations also involve turning the device on or off WDM PnP operations modeled as a series of primitive operations WDF callbacks are based around primitive operations Most are neither wholly power or wholly PnP Each primitive is a callback Nearly all callbacks perform one particular operation WDF is internally implemented as a set of interlocking state machines PnP and Power IRPs cause state machines to start passing events back and forth

40. PnP and Power Primitives Primitive software operations correspond to device hardware actions Primitives involve very few (or no) choices Result in straight-line code They don’t require tracking of state history Every primitive is optional When implemented, they augment WDF behavior They tend to be small and very focused Causes callback proliferation Resulting callbacks are simple and maintainable They tend to have fairly simple rules associated with them For every “Do” primitive, there is an “Undo” primitive Order in which the primitives are called is guaranteed From bottom to top when powering up From top to bottom when powering down (exact reverse of power up)

41. Power Up Callbacks EvtDevicePrepareHardware One time initialization, first callback where device is in D0 Map in memory mapped I/O, inspect hw for revision, features, etc. EvtDeviceD0Entry Bring the device into D0, no interrupts connected EvtInterruptEnable (at DIRQL) Enable interrupt generation in the hardware EvtDeviceD0EntryPostInterruptsEnable Further D0 initialization if it requires a connected interrupt DMA EvtDmaEnablerFill EvtDmaEnablerEnable EvtDmaEnablerSelfManagedIoStart Power managed queues are started Self managed IO, EvtDeviceSelfManagedIoInit or Restart Miscellaneous catchall: start watch dog timers, async HW operations

42. WDM Actions Versus WDF Actions IRP_MN_START_DEVICE Process new hardware resources, except if you don’t use them Map hardware, except if it’s already mapped Put your device in D0, except if it’s already there Connect interrupt, except if it’s already connected Start asynchronous hardware operations, except if they were already started etc. EvtDevicePrepareHardware Process new hardware resources Map your hardware EvtDeviceD0Entry Put your device in D0 EvtInterruptEnable Program your hardware to enable interrupts EvtDeviceSelfManagedIoInit Start asynchronous hardware operations

43. Power Down Callbacks EvtDeviceSelfManagedIoSuspend Miscellaneous catch all: stop watch dog timers, async hw operations Power managed queues are stopped DMA EvtDmaEnablerSelfManagedIoStop EvtDmaEnablerDisable EvtDmaEnablerFlush EvtDeviceD0ExitPreInterruptsDisable Move the device into Dx, if it requires a connected interrupt EvtInterruptDisable (at DIRQL) Disable interrupt generation in the HW EvtDeviceD0Exit Move the device into Dx, no interrupts connected EvtDeviceReleaseHardware One time deinitialization, called when the device is in Dx! Unmap in memory mapped I/O, etc.

44. Power Policy Ownership Something has to decide what level of power (D-state) is appropriate for a device That decision isn’t centralized in the kernel It depends on the usage model for the device It should be centralized somewhere Probably in the driver that controls the hardware (FDO) WDF provides a rich set of automatic behaviors Device to low-power when the system goes to sleep/hibernate Device to low-power when the device is idle Device to high-power when there are requests to process Automatic arming for wake while the system is running (device is idle) Automatic arming for wake while the system is sleeping Enabling UI in device manager to control wake behaviors WDF implements correct parent/child power policy interaction If a parent and child are powered down and the child needs to power up, WDF will automatically bring the parent into fully power

45. Bus Drivers Are Trivial To Write WDF can handle most of the details Reporting children to WDM Coordinating scanning for children Maintaining the list of children WDF has two models for bus enumeration Static: child device status rarely, if ever, changes Dynamic: child device status is expected to change at any time Drivers responsible for Identifying children Generating IDs Generating resource requirements WDF encapsulates reporting of resource requirements in a much easier to use interface Identifying capabilities Notification back to WDF that children have been removed

46. IRP Dispatcher I/O Package Read/Write/Ioctls/ Create/Close/Cleanup WMI Package Hardware Resource Management (DMA, Interrupt, I/O) Parallel Queue Sequential Queue Manual Queue IoTarget WDFREQUEST Next Driver Pnp/Power Events IRPWMI Pnp/Power Events Pnp/Power/WMI IRPs Pnp/Power Package

47. Windows Management Interface (WMI) WDF fully handles IRP_MJ_SYSTEM_CONTROL WMI usage pattern Register providers and instances upon device arrival Fire events when necessary Report statistics Update state Unregister upon device removal (graceful or surprise remove) WDF takes care of most of this for you You still have to fire events and implement instance callbacks In WDM, using wmilib.sys allowed for a static registration easily, but made dynamic registration difficult In WDF, both static and dynamic registration of providers and instances is very easy to do Also support for kernel mode ETW / Tracing

48. WMI Objects WDFWMIPROVIDER This schema for the data being reported GUID from the MOF Properties of the data (expensive, event only, tracing) Contains N number of WDFWMIINSTANCEs Once created, cannot be manually deleted Automatically deleted when the parent WDFDEVICE is Has callbacks for enable and disable of event collection WDFWMIINSTANCE Instance of a WDFWMIPROVIDER Can be deleted after creation at any time Can be added or deleted at IRQL <= DISPATCH_LEVEL Can use its context as a source for read only data This allows for very easy data collection with minimal effort Callbacks are not synchronized to PnP/PM state

49. IRP Dispatcher I/O Package Read/Write/Ioctls/ Create/Close/Cleanup WMI Package Hardware Resource Management (DMA, Interrupt, I/O) Parallel Queue Sequential Queue Manual Queue IoTarget WDFREQUEST Next Driver Pnp/Power Events IRP I/O Targets Pnp/Power Events Pnp/Power/WMI IRPs Pnp/Power Package

50. WDFIOTARGET A WDFIOTARGET is a WDF object which encapsulates Opening a device object or stack by name Formatting a request to send to the target Calling IoCallDriver in coordination with PnP state of the target owner and the target state itself Synchronization of sent I/O with target state changes A WDFIOTARGET uses WDF object reference counting to guard against freeing of resources while a WDFREQUEST is pending

51. WDFREQUEST Formatting It is a WDF design goal to allow the driver to send I/O without needing to know the underlying memory description This also applies to incoming I/O The WDFIOTARGET will format the WDFREQUEST based on the request type Convert a provided PVOID to an PMDL Retrieve a buffer from a provided PMDL When using a WDFMEMORY, the target will reference the WDFMEMORY for the duration of the format, which is bound by either A reformat before sending the WDFREQUEST The WDFREQUEST completion

52. WDFREQUEST Formatting A WDFMEMORY can be retrieved from a WDFREQUEST and then used in a subsequent format The WDFMEMORY is based on the current stack location It is a snapshot of the underlying IRP values before formatting the next stack location The underlying IRP fields will be restored when the I/O has completed back to the driver If the current buffer and the target’s desired buffer are PMDLs, WDF will create a partial PMDL to reduce PTE usage

53. Sending of I/O A WDFREQUEST can be sent synchronously or asynchronously Unlike WDM, you do not have to implement your own synchronous send Synchronous I/O You can use any type of memory (PVOID, PMDL, WDFMEMORY) Asynchronous I/O requires the use of WDFMEMORY You can specify a timeout WDF synchronizes request cancellation from the timer and the client driver via WdfRequestCancelSentRequest() with the request completion and cancellation of the timer itself upon completion

54. State Synchronization and Sending of I/O A WDFREQUEST is sent only when the target is in the proper state A request will be queued on a stopped target for sending at a later time Optional timeout will be started when queued State can be ignored and force a send The state of the WDFIOTARGET is not affected by a PnP state change in the owning device For an in stack target, WDF assumes that queues or self managed I/O will control the sending of I/O For an opened (e.g. remote) target, the states are disjoint already The target tracks queued and sent requests and can cancel them when the target state changes The target object itself will not be freed until all sent I/O has completed!

55. Call to Action Work together with us to make WDF successful Consider WDF for any Windows driver development project Join WDF beta program Use the guest account (Guest ID: Guest4WDF) on http://beta.microsoft.com to sign up for beta http://beta.microsoft.com Provide feedback Email windf @ microsoft.com - Kernel Mode Driver Frameworkindf @ microsoft.com umdfdbk @ microsoft.comumdfdbk @ microsoft.com - User Mode Driver Framework drvpft @ microsoft.com - PREfast for Driversrvpft @ microsoft.com sdvfdbk @ microsoft.com - Static Driver Verifierdvfdbk @ microsoft.com Newsgroups microsoft.beta.windows.driverfoundation microsoft.beta.windows.driverfoundation.announcements Web Resources http://www.microsoft.com/whdc/driver/wdf/default.mspx http://www.microsoft.com/whdc/DevTools/ddk/default.mspx

56. © 2005 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.