1 / 33

Using KMDF in Miniport Drivers

Using KMDF in Miniport Drivers. Vishal Manan SDE 2 Device and Storage Technologies vmanan@microsoft.com. Eliyas Yakub Principal SDE Lead Device and Storage Technologies eliyasy@microsoft.com. Agenda. Basics of framework and miniports — Dispatch table override

otis
Télécharger la présentation

Using KMDF in Miniport Drivers

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Using KMDF in Miniport Drivers Vishal Manan SDE 2 Device and Storage Technologies vmanan@microsoft.com Eliyas Yakub Principal SDE Lead Device and Storage Technologies eliyasy@microsoft.com

  2. Agenda • Basics of framework and miniports — Dispatch table override • Code snippets specific to NDIS miniport and AvStreamminidrivers 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?

  3. How does a WDM driver work? I/O Manager DriverEntry

  4. What happens in a miniport (For eg: NDIS)? I/O Manager Initialize() Halt() Send() Receive() NdisMRegisterMiniportDriver

  5. What happens in the framework? I/O Manager EvtDeviceXxx() EvtIoXxx() WdfDriverCreate

  6. How do you make a miniport and WDF work together? Initialize() Halt() Send() Receive() NdisMRegisterMiniportDriver() WdfDriverCreate (WdfDriverInitNoDispatchOverride)

  7. 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

  8. 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

  9. NDIS Miniport Code Snippets

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

  11. 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); … }

  12. 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

  13. 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()); … }

  14. KMDF NDIS miniport sample in WDK NDIS 802.11 Intermediate Driver • 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 802.11 Miniport Driver KMDF USB Targets Core USB Stack

  15. AvstreamMinidriver Code Snippets

  16. 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, RegistryPathName, &KsDeviceDescriptor ); }

  17. 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); }

  18. 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

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

  20. 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

  21. 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

  22. 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

  23. Code snippet showing USB target usage in a miniport

  24. Creating and Initializing the WDFUSBTARGETDEVICE NDIS Miniport AvStreamMinidriver 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); … }

  25. 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

  26. 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

  27. 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

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

  29. 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

  30. 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

  31. 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 driving) • 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

  32. WDF DDC 2008 Sessions • Ask the Experts Table, • Panel Disccussion

More Related