2. Using KMDF in Miniport Drivers
Eliyas Yakub
Principal SDE Lead
Device and Storage Technologies
Vishal Manan
SDE 2
Device and Storage Technologies

3. Agenda Basics of framework and miniports — Dispatch table override
Code snippets specific to NDIS miniport and AvStream minidrivers using the framework
Why should you use KMDF for writing your miniport drivers?
What features of KMDF can’t you use in your miniport drivers?

4. How does a WDM driver work?
DriverObject
IRP_MJ_xxx
DriverDispatchxxx()
AddDevice
DeviceAdd()
DriverUnload
Unload()
DriverObject
IRP_MJ_xxx
IopInvalidDeviceRequest
AddDevice
NULL
DriverUnload
I/O Manager
DriverEntry

5. What happens in a miniport (For eg: NDIS)?
DriverObject
IRP_MJ_xxx
IopInvalidDeviceRequest
AddDevice
NULL
DriverUnload
DriverObject
IRP_MJ_xxx
ndisDummyIrpHandler
AddDevice
ndisPnPAddDevice()
DriverUnload
ndisMUnloadEx()
I/O Manager
Initialize()
Halt()
Send()
Receive()
NdisMRegisterMiniportDriver

6. What happens in the framework?
DriverObject
IRP_MJ_xxx
IopInvalidDeviceRequest
AddDevice
NULL
DriverUnload
DriverObject
IRP_MJ_xxx
FxDevice::Dispatch()
AddDevice
FxDriver::AddDevice()
DriverUnload
FxStubDriverUnload()
I/O Manager
EvtDeviceXxx()
EvtIoXxx()
WdfDriverCreate

7. How do you make a miniport and WDF work together?
DriverObject
IRP_MJ_xxx
IopInvalidDeviceRequest
AddDevice
NULL
DriverUnload
DriverObject
IRP_MJ_xxx
ndisIrpHandler
AddDevice
ndisPnPAddDevice()
DriverUnload
ndisMUnloadEx()
Initialize()
Halt()
Send()
Receive()
NdisMRegisterMiniportDriver()
WdfDriverCreate (WdfDriverInitNoDispatchOverride)

8. IRP flow in NDIS miniport
Framework
Miniport Driver
NDIS Port Library
USB target
I/O Manager
NdisCloseIrpHandler
MpDriverUnload
NdisCreateIrpHandler
IO target
IRP
MpOIDRequest
NdisDeviceControlIrpHandler
WorkItems
NdisPnPDispatch
MpDevicePnpEvent
NdisWMIDispatch
Timer
NdisPowerDispatch
Utility Objects
NdisMUnloadEx

9. How does the framework communicate with the lower device stack?
Driver calls WdfDeviceMiniportCreate (…,FDO, AttachedDeviceObject, PDO …)
Frameworks creates an I/O target object to communicate with the lower device stack using the passed-in AttachedDeviceObject

10. NDIS Miniport Code Snippets

11. Overriding the dispatch table
NTSTATUS DriverEntry( PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath ) { WDFDRIVER hDriver; //vm control WDF_DRIVER_CONFIG_INIT(&config, WDF_NO_EVENT_CALLBACK); config.DriverInitFlags |= WdfDriverInitNoDispatchOverride; ntStatus = WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, &config, &hDriver); Status = NdisMRegisterMiniportDriver(DriverObject, PNDIS_HANDLE)GlobalDriverContext, &MPChar, &NdisMiniportDriverHandle); }

12. Creating the miniport device object
NDIS_STATUS MPInitialize( IN NDIS_HANDLE MiniportAdapterHandle, … ) { PADAPTER pAdapter; NdisMGetDeviceProperty(MiniportAdapterHandle, &pAdapter->Pdo, &pAdapter->Fdo, &pAdapter->NextDeviceObject, NULL, NULL); WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, WDF_DEVICE_INFO); ntStatus = WdfDeviceMiniportCreate(WdfGetDriver(), &attributes, pAdapter->Fdo, pAdapter->NextDeviceObject, pAdapter->Pdo, &pAdapter->WdfDevice); }

13. Deleting the miniport device object
VOID
MPHalt(
IN NDIS_HANDLE MiniportAdapterContext,
IN NDIS_HALT_ACTION HaltAction ) {
PADAPTER pAdapter = (PADAPTER)MiniportAdapterContext;
if (pAdapter->WdfDevice != NULL){
WdfObjectDelete(pAdapter->WdfDevice); } …
NOTE: Don’t forget to free the WdfDeviceObject allocated in WdfDeviceMiniportCreate

14. Unbinding and freeing the framework driver resources
The framework does not override the driver’s unload routine, so WdfDriverMiniportUnload allows the miniport driver to unbind as a client driver from the framework.
As a result the framework can free resources that it allocated for the miniport driver.
VOID
MpDriverUnload(
IN PDRIVER_OBJECT DriverObject ) { …
WdfDriverMiniportUnload(WdfGetDriver()); }

15. KMDF NDIS miniport sample in WDK
NDIS 6.0 sample for USB Wi-Fi device
Based on the current RTLNWiFi PCI sample
Takes advantage of NDIS-WDM
Conforms to the Microsoft Native Wi-Fi miniport driver specification
Abstracts bus dependent and independent parts
Easily adaptable for other buses
Uses KMDF USB I/O target
Continuous reader reads packets from input endpoint and indicates packets to NDIS
Location in WDK: src\network\ndis\usbnwifi
NDIS
Intermediate Driver
Miniport Driver
KMDF USB Targets
Core USB Stack

16. Avstream Minidriver Code Snippets

17. Overriding the dispatch table
KSDEVICE_DISPATCH
KsDeviceDispatchTable = {
DeviceCreate,
DeviceStart,
DeviceStop,
DeviceRemove,
DeviceQueryCapabilities,
DeviceSurpriseRemoval,
DeviceSetPowerState };
KSDEVICE_DESCRIPTOR KsDeviceDescriptor = {&KsDeviceDispatchTable, 0, NULL, KSDEVICE_DESCRIPTOR_VERSION};
NTSTATUS
DriverEntry(
IN PDRIVER_OBJECT DriverObject,
IN PUNICODE_STRING RegistryPathName ) {
config.DriverInitFlags |= WdfDriverInitNoDispatchOverride;
ntStatus = WdfDriverCreate(DriverObject,
RegistryPathName,
WDF_NO_OBJECT_ATTRIBUTES,
&config,
NULL);
ntStatus = KsInitializeDriver( DriverObject,
&KsDeviceDescriptor ); }

18. Creating the miniport device object
NTSTATUS DeviceCreate( IN PKSDEVICE pKsDevice ) { PEXTBUS_DEVICE_EXTENSION pEBHwExt = pKsDevice->Context; WDF_OBJECT_ATTRIBUTES_INIT(&attributes); ntStatus = WdfDeviceMiniportCreate(WdfGetDriver(), &attributes, pKsDevice->FunctionalDeviceObject, pKsDevice->NextDeviceObject, pKsDevice->PhysicalDeviceObject , &pEBHwExt->WdfDevice); }

19. Deleting the miniport device object
VOID
DeviceRemove(
IN PKSDEVICE pKsDevice,
IN PIRP pIrp ) {
PEXTBUS_DEVICE_EXTENSION pEBHwExt = pKsDevice->Context;
if (pEBHwExt->WdfDeviceObject != NULL) {
WdfObjectDelete(pEBHwExt->WdfDeviceObject) } …
NOTE: Don’t forget to free the WdfDeviceObject allocated in WdfDeviceMiniportCreate

20. Unbinding and freeing the framework driver resources
void
MiniDriverUnload(
IN PDRIVER_OBJECT DriverObject ) { …
WdfDriverMiniportUnload(WdfGetDriver()); }

21. Framework features that miniport drivers can use
Framework objects benefit from lifetime management -- parenting, reference counts, context and cleanup in a race free manner
IoTargets / USB Targets
DMA
Deferred Processing Objects
Timers / Workitems / DPC’s
Utility Objects
Framework General Object (a.k.a WDFOBJECT )
Memory
Collections
Registry
WaitLocks
Debugging/Diagnosing
Tracing / WDF Verifier/ Debug extensions

22. Benefits of Framework I/O Targets
Coordinate and synchronize the cancellation of sent requests with the request completion at the same time
Format requests before they are sent
Track and free I/O packets and associated memory only after they have been completed back to the sending device
Provide state management for I/O target objects
Stop can either cancel all sent I/O or leave it
Will pend incoming requests (as cancellable) when stopped
Will resend pended requests when restarted
Time out sent requests asynchronously
Support for both synchronous and asynchronous communications

23. Benefits of Framework USB Targets
All the benefits of I/O targets described earlier, plus more
Ease of configuring a USB device
USB bus-specific formatting DDI
Continuous reader
Ping-pong model for having outstanding USB URB’s, allocation of memory, error handling, event callback to driver to indicate success or failure

24. Code snippet showing USB target usage in a miniport

25. Creating and Initializing the WDFUSBTARGETDEVICE
AvStream Minidriver
NDIS Miniport
NTSTATUS DeviceStart( IN PKSDEVICE pKsDevice, … ) { PEXTBUS_DEVICE_EXTENSION pEBHwExt = pKsDevice->Context; ntStatus = WdfUsbTargetDeviceCreate( pEBHwExt->WdfDevice, &attributes, &pEBHwExt->UsbDevice); //SelectConfig( pEBHwExt->UsbDevice); //GetFrameworkPipeHandles(pEBHwExt->UsbDevice); … }
NDIS_STATUS MPInitialize( NDIS_HANDLE MiniportDriverContext, … ) { ntStatus = WdfUsbTargetDeviceCreate( Adapter->WdfDevice, &attributes, &Nic->UsbDevice); //SelectConfig(Nic->UsbDevice); //GetFrameworkPipeHandles(Nic->UsbDevice); }

26. Benefits of using Framework DMA
Transaction-based model
Simple to use – Driver specifies DMA profile based on the capabilities of PCI device(32 vs 64, common buffer vs packet based, SG supported)
Framework uses the profile to manage mixed-mode DMA addressing (ex. 32-bit DMA engine on 64-bit platform without special code in driver)
Drivers don’t need to know bus addressing capability(64-bit capable or not)
Framework insures that drivers receive data buffer physical addresses that are within the addressing capabilities of their device irrespective of total memory on the system
Extension of IO Request processing into the DMA domain.
NOTE: Some port libraries provide their own DMA model and the driver needs to abide by that. For eg: NDIS

27. Benefits of using framework deferred processing objects – Workitems, Timers, DPC’s
Can reference a parent object to ensure that reference counts are properly maintained as long as the callback is outstanding
Workitems
Can flush them to make sure no callback is outstanding after the call returns
Passive Timer support (added in version 1.9)– Allows timer callbacks at IRQL PASSIVE_LEVEL
Timers
Coalescable Timers in Windows 7
This feature allows to set a timer whose expiration is coalescable with other timers in the system.
It uses the tolerable delay parameter to adjust the timer’s due time so that the timer expires at a point convenient to the system.
Has start /stop semantics
The Stop can be synchronous (only callable at IRQL PASSIVE_LEVEL) to make sure that the Timer callback has been delivered if the Wait flag passed in is set to TRUE

28. Utility objects Framework general Object Memory Collection
Useful to represent any abstraction in the driver which can be modeled as an object
Lifetime management -- Benefits from framework parenting, reference counts, context and cleanup
Memory
Self describing, length is embedded
Provides consistent interface to different types of memory (MDL, buffers)
Referenced memory handle(can be parented to WDFREQUEST) allows driver writers to mitigate the common mistake of freeing memory before async. I/O has completed
Collection
Insert /Delete/ Retrieve semantics
Convenient for storing heterogeneous framework objects
Registry / Wait Lock
Simplified parameter passing

29. Diagnosing and debugging support
Trace logs
WDF verifier
Framework Debug extensions

30. Framework features which miniport drivers can’t use
Since the port library takes over the dispatch table of the driver, the following framework features can’t be used
Pnp
Interrupts – Closely tied to the framework Pnp state machine
Power
IoQueues
WMI
Framework doesn’t support partial override of dispatch table

31. Call to Action Read the WDF Book.
Test your UMDF and KMDF drivers with 1.9 immediately.
Start using the new samples and debugging tools.
Write your next driver with UMDF or KMDF.
Keep telling us what stops you from doing that.
Your input does affect our future plans.
Send us your feedback:

32. Additional Resources Web Resources
White papers:
Presentations: Writing KMDF HID Minidrivers
Blogs
(A Hole In My Head)
(Pointless Blathering)
(driver writing != bus driving)
Newsgroups and Lists
Microsoft.public.device.development.drivers
OSR NTDev Mailing List
Book: Developing Drivers with the Windows Driver Foundation

33. WDF DDC 2008 Sessions Ask the Experts Table, Panel Disccussion Session
Day / Time
Shared Secrets about Windows Driver Framework: Part 1
Mon and Wed. 8:30-9:30
Shared Secrets about Windows Driver Framework: Part 2
Mon. 4-5 and Wed. 9:45-10:45
Getting a Logo for your Windows Driver Foundation Driver
Mon. 4-5 Tues. 2:45-3:45
Using WinDBG to Debug Kernel-Mode Windows Driver Framework Drivers
Mon. 2:45-3:45 Wed
Packaging and Deploying KMDF and UMDF Drivers
Tues. 4-5 Wed. 8:30-9:30
Exploring a KMDF Storage Driver: Parts 1 and 2
Tues. 9:45-12:00
What’s New in Windows Driver Framework
Mon. 8:30-9:30 Wed. 9:45-10:45
Discussion: Windows Driver Framework
Wed. 1:30-2:30
Ask the Experts Table
Tues. evening
Ask the Experts Table,
Panel Disccussion