Using KMDF in Miniport Drivers

Eliyas YakubPrincipal SDE LeadDevice and Storage Technologies

eliyasy@microsoft.com

Vishal MananSDE 2Device and Storage Technologies

vmanan@microsoft.com

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?

DriverObject

IRP_MJ_xxx IopInvalidDeviceRequest

AddDevice NULL

DriverUnload NULL

DriverObject

IRP_MJ_xxx DriverDispatchxxx()

AddDevice DeviceAdd()

DriverUnload Unload()

DriverEntry

I/O Manager

How does a WDM driver work?

DriverObject

IRP_MJ_xxx IopInvalidDeviceRequest

AddDevice NULL

DriverUnload NULL

DriverObject

IRP_MJ_xxx ndisDummyIrpHandler

AddDevice ndisPnPAddDevice()

DriverUnload ndisMUnloadEx()

I/O Manager

What happens in a miniport (For eg: NDIS)?

Initialize()Halt()Send()Receive()

NdisMRegisterMiniportDriver

DriverObject

IRP_MJ_xxx IopInvalidDeviceRequest

AddDevice NULL

DriverUnload NULL

DriverObject

IRP_MJ_xxx FxDevice::Dispatch()

AddDevice FxDriver::AddDevice()

DriverUnload FxStubDriverUnload()

I/O Manager

What happens in the framework?

EvtDeviceXxx()EvtIoXxx()

WdfDriverCreate

DriverObject

IRP_MJ_xxx IopInvalidDeviceRequest

AddDevice NULL

DriverUnload NULL

DriverObject

IRP_MJ_xxx ndisIrpHandler

AddDevice ndisPnPAddDevice()

DriverUnload ndisMUnloadEx()

How do you make a miniport and WDF work together?

Initialize()Halt()Send()Receive()

NdisMRegisterMiniportDriver()WdfDriverCreate (WdfDriverInitNoDispatchOverride)

Framework

IRP flow in NDIS miniport

IRP

I/O Manager

NDIS Port Library

NdisPowerDispatch

NdisMUnloadEx

NdisCreateIrpHandler

Miniport Driver USB

target

Timer

IO target

WorkItems

Utility Objects

NdisDeviceControlIrpHandler

NdisCloseIrpHandler

NdisPnPDispatch

NdisWMIDispatch

MpDriverUnload

MpOIDRequest

MpDevicePnpEvent

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

NDIS Miniport Code Snippets

Overriding the dispatch table

NTSTATUSDriverEntry( 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, RegistryPath, PNDIS_HANDLE)GlobalDriverContext, &MPChar, &NdisMiniportDriverHandle);}

Creating the miniport device objectNDIS_STATUSMPInitialize( 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);…}

Deleting the miniport device object

VOIDMPHalt( 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

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.

VOIDMpDriverUnload( IN PDRIVER_OBJECT DriverObject ) {

… WdfDriverMiniportUnload(WdfGetDriver());

…}

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

802.11 Intermediate Driver

802.11 Miniport Driver

KMDF USB Targets

Core USB Stack

Avstream Minidriver Code Snippets

Overriding the dispatch tableKSDEVICE_DISPATCH KsDeviceDispatchTable = { DeviceCreate, DeviceStart, DeviceStop, DeviceRemove, DeviceQueryCapabilities, DeviceSurpriseRemoval, DeviceSetPowerState};KSDEVICE_DESCRIPTOR KsDeviceDescriptor = {&KsDeviceDispatchTable, 0, NULL, KSDEVICE_DESCRIPTOR_VERSION};

NTSTATUSDriverEntry( IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPathName ){ config.DriverInitFlags |= WdfDriverInitNoDispatchOverride; ntStatus = WdfDriverCreate(DriverObject, RegistryPathName, WDF_NO_OBJECT_ATTRIBUTES, &config, NULL); ntStatus = KsInitializeDriver( DriverObject, RegistryPathName, &KsDeviceDescriptor );}

Creating the miniport device object

NTSTATUSDeviceCreate( 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);}

Deleting the miniport device object

VOIDDeviceRemove( 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

Unbinding and freeing the framework driver resources

voidMiniDriverUnload( IN PDRIVER_OBJECT DriverObject ){ … WdfDriverMiniportUnload(WdfGetDriver()); …}

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

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

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

Code snippet showing USB target usage in a miniport

Creating and Initializing the WDFUSBTARGETDEVICE

NDIS Miniport

NDIS_STATUS MPInitialize( NDIS_HANDLE

MiniportDriverContext,

… ) { ntStatus =

WdfUsbTargetDeviceCreate(Adapter-

>WdfDevice, &attributes, &Nic->UsbDevice);

//SelectConfig(Nic->UsbDevice); //GetFrameworkPipeHandles(Nic-

>UsbDevice); …}

AvStream Minidriver

NTSTATUSDeviceStart( IN PKSDEVICE pKsDevice, … ){PEXTBUS_DEVICE_EXTENSION pEBHwExt =

pKsDevice->Context;

ntStatus = WdfUsbTargetDeviceCreate( pEBHwExt->WdfDevice,

&attributes, &pEBHwExt->UsbDevice); //SelectConfig( pEBHwExt->UsbDevice);

//GetFrameworkPipeHandles(pEBHwExt->UsbDevice);

…}

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

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

Utility objects

• Framework general Object • 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

• Trace logs• WDF verifier• Framework Debug extensions

Diagnosing and debugging support

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

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:• wdfinfo@microsoft.com

Additional Resources• Web Resources

• White papers: http://go.microsoft.com/fwlink/?LinkID=79335• Presentations: Writing KMDF HID Minidrivers• Blogs

• http://blogs.msdn.com/doronh/default.aspx (A Hole In My Head)• http://blogs.msdn.com/peterwie/default.aspx (Pointless Blathering)• http://blogs.msdn.com/iliast/default.aspx (driver writing != bus dri

ving)• Newsgroups and Lists

• Microsoft.public.device.development.drivers• OSR NTDev Mailing List

• Book: Developing Drivers with the Windows Driver Foundation• http://www.microsoft.com/MSPress/books/10512.aspx

WDF DDC 2008 Sessions

• Ask the Experts Table,• Panel Disccussion

Session Day / Time

Shared Secrets about Windows Driver Framework: Part 1 Mon. 11-12 and Wed. 8:30-9:30

Shared Secrets about Windows Driver Framework: Part 2 Mon. 4-5 andWed. 9:45-10:45

Getting a Logo for your Windows Driver Foundation Driver Mon. 4-5Tues. 2:45-3:45

Using WinDBG to Debug Kernel-Mode Windows Driver Framework Drivers Mon. 2:45-3:45Wed. 11-12

Packaging and Deploying KMDF and UMDF Drivers Tues. 4-5Wed. 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:30Wed. 9:45-10:45

Discussion: Windows Driver Framework Wed. 1:30-2:30

Ask the Experts Table Tues. evening