haihongyuan.com
海量文库 文档专家
全站搜索:
您现在的位置:首页 > 幼儿教育 > 育儿理论经验育儿理论经验

夏天育儿保健小常识

发布时间:2014-02-22 19:32:09  

育儿知识 http://www.pangbaba.cc

How to Port WDM Driver to KMDF

Agenda
Introduction to WDF Why should I convert to KMDF: Case Study Basic object model DriverEntry PnP/Power callbacks Self-Managed I/O callbacks How to configure wait-wake & idle power management Interrupt handling Callbacks specific to FDO and PDO Order of callbacks with respect to PnP/Power actions

Agenda (con’t)
Different types of queues How queue states are managed by WDF Request Cancellation Handling Create, Cleanup & Close requests Handling I/O requests – Read/Write/Ioctl Timers/DPC/Work items Locks: WaitLock, Spinlock Automatic I/O synchronization Sending request to another driver Escaping to WDM

What is WDF?
Windows Driver Foundation consists of
User Mode Driver Framework (UMDF ) Kernel Mode Driver Framework (KMDF) Tools: SDV, Driver PREfast, DIG, etc.

KMDF is built on top of WDM Drivers written using KMDF are compatible from Windows 2000 forward Drivers are written using objects

Why Convert to WDF?
List of things you worry about in WDM Tons of rules on handling PnP and power IRPs When to use remove locks IRP queuing and cancellation When to map and unmap HW resources When to enable/disable device interfaces When to register/deregister with WMI When to connect & disconnect interrupts Timer DPC and device remove/unload synchronization

Why Convert to WDF? (con’t)
Converting S IRPs to D IRPs Supporting wait-wake Supporting selective suspend (S0 Sleep) Fast resume Asynchronous start Child device enumeration Complex rules on deleting a PDO Handling PnP/power IRPs in a filter driver Error handling Backward compatibility

Case Study: PCIDRV Sample
Stats
Line Count LOC devoted to PnP/PM Locks State variables devoted to PnP/PM

WDM
13,147 7,991

WDF

Comments

7,271 Explicit registration of
granular event callbacks adds to the line count 1,795 Almost 6000 lines of code are eliminated

8
30

3 This is the most important
statistic. This explains the complexity. 0 There are fewer paths in the driver and thus less testing and complexity.

This sample is written for the Intel E100B NIC Card It?s a WDM version of network driver with NDIS interfaces separated out in an upper filter driver (ndisedge) Both samples are in the DDK and are functionally equivalent

Case Study: Serial Sample
Stats
Line Count LOC devoted to PnP/PM Locks State variables devoted to PnP/PM

WDM
24,000 5,000

WDF

Comments
granular event callbacks adds to the line count

17,000 Explicit registration of 2,500

10
53

0 This is the most important
statistic. This explains the complexity. 0 There are fewer paths in the driver and thus less testing and complexity.

WDF sample does not support multi-port serial (WDM sample supports it) WDM statistics exclude multi-port support serial code

Case Study: OSRUSBFX2 Sample
Stats
Line Count LOC devoted to PnP/PM Locks State variables devoted to PnP/PM

WDM
16,350 6,700

WDF

Comments

2,300 Explicit registration of
granular event callbacks adds to the lin

e count 742 742 includes code to initialize the USB

9
21

0 This is the most important
statistic. This explains the complexity 0 There are fewer paths in the driver and thus less testing and complexity

The WDM version of OSRUSBFx2 sample (available on osronline.com) and the WDF version provided in the DDK are functionally equivalent

Object Model
Objects are the basis of WDF
Everything in framework is represented by objects (Driver, Device, Request, etc.) Objects have properties, methods, and events
WDFOBJECT Methods Events Properties WDF functions that operate on object Calls made by WDF into the driver to notify something Methods that get or set a single value

Have one or more driver owned context memory areas Lifetime of the object is controlled by reference counts Organized hierarchically for controlling object life time
Not an inheritance based hierarchy

Driver references objects as handles, not pointers

Creating an Object (Abc)
Header File:
Struct _ABC_CONTEXT { … } ABC_CONTEXT *PABC_CONTEXT WDF_DECLARE_CONTEXT_TYPE_WITH_NAME( ABC_CONTEXT, GetAbcContext )
WDF_OBJECT_ATTRIBUTES Size

EvtCleanupCallback
EvtDestroyCallback ExecutionLevel SynchronizationScope ParentObject ContextSizeOverride ContextTypeInfo InheritParen tPassive Dispatch InheritPare ntDevice Object None

Source File:
WDF_OBJECT_ATTRIBUTES_INIT(&Attributes); WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE( &Attributes, ABC_CONTEXT ); Attributes.EvtCleanupCallback = AbcEvtCleanup; Attributes.EvtDestroyCallback = AbcEvtDestroy; WDF_ABC_CONFIG_INIT( &Config ); WdfAbcCreate( &Attributes, &Config, &Handle ) Context = GetAbcContext( Handle );

WDF_ABC_CONFIG Size EvtCallback

Period


Object Relationship
Predefined WDFDRIVER

WDFCOLLECTION WDFLOOKASIDE WDFKEY WDFWAITLOCK WDFSPINLOCK WDFSTRING WDFREQUEST – Driver created
WDFUSBDEVICE

Default, but can be parented to any object
WDFDEVICE

WDFQUEUE
WDFDPC WDFTIMER WDFWORKITEM

WDFUSBPIPE

WDFDMAENABLER
WDFINTERRUPT WDFIOTARGET WDFCHILDLIST WDFFILEOBJECT WDFREQUEST – queue delivered

WDFWMIINSTANCE

WDFTRANSACTION WDFCOMMONBUFFER

WDFWMIPROVIDER

Deleting an Object
WdfObjectDelete() - single delete function to delete all types of objects Child objects will be deleted when their parent is deleted Some objects cannot be deleted by the driver because the lifetime is controlled by WDF
WDFDRIVER WDFDEVICE for FDO and PDO WDFFILEOBJECT WDFREQUEST Etc.

Mapping – WDF Objects to WDM
WDFDRIVER WDFDEVICE WDFQUEUE WDFREQUEST WDFINTERRUPT WDFDPC WDFWORKITEM WDFDMAENABLER WDFIOTARGET WDFWAITLOCK WDFSPINLOCK WDFMEMORY WDFKEY
Driver object Device object Cancel-safe queue/Dispatching /Serialization/Autolocking/Synch with PnP IRP Interrupt DPC Work item DMA adapter object Sending I/O to another driver - IoCallDriver Event dispatcher object – passive level lock Spinlock Kernel pool - refcounted Registry access

Naming Pattern
Methods:
Status = WdfDeviceCreate();
Object Operation

Properties:
Cannot fail
WdfInterruptGetDevice(); WdfInterruptS

etPolicy();

Can fail:
Status = WdfRegistryAssignValue(); Status = WdfRegistryQueryValue(); Status = WdfRequestRetrieveInputBuffer();

Callbacks:
PFN_WDF_INTERRUPT_ENABLE EvtInterruptEnable

Init Macros:
WDF_XXX_CONFIG_INIT WDF_XXX_EVENT_CALLBACKS_INIT

DriverEntry – WDM
Called when the driver is first loaded in memory Sets Dispatch routines and returns
NTSTATUS DriverEntry( IN PDRIVER_OBJECT DriverObject IN PUNICODE_STRING RegistryPath ) { DriverObject->DriverExtension->AddDevice = AddDevice; DriverObject->MajorFunction[IRP_MJ_PNP] = DispatchPnp; DriverObject->MajorFunction[IRP_MJ_POWER] = DispatchPower; DriverObject->MajorFunction[IRP_MJ_SYSTEM_CONTROL] = DispatchSysControl; …. return STATUS_SUCCESS; }

DriverEntry – WDF
DriverEntry is called when the driver is first loaded in memory FxDriverEntry initializes the framework and calls DriverEntryv
NTSTATUS DriverEntry( IN PDRIVER_OBJECT DriverObject IN PUNICODE_STRING RegistryPath ) { WDF_DRIVER_CONFIG_INIT( &config ToasterEvtDeviceAdd );
WDF_DRIVER_CONFIG

Size EvtDriverDeviceAdd EvtDriverUnload DriverInitFlags

status = WdfDriverCreate( DriverObject RegistryPath WDF_NO_OBJECT_ATTRIBUTES &config WDF_NO_HANDLE ); return STATUS_SUCCESS; }

WdfDriverInitNonPnpDriver WdfDriverInitNoDispatchOverride

PnP/Power Stage
WDFREQUEST Parallel Queue I/O Package Read/Write/Ioctls/ Create/Close/Cleanup Manual Queue Pnp/Power Events I R P IRP Dispatcher Pnp/Power Package Pnp/Power Events IoTarget Serial Queue

Driver
Next Driver

Pnp/Power Events Next Driver WMI Package Hardware Resource Management (DMA, Interrupt, I/O)

AddDevice – WDM
ToasterAddDevice(
IN PDRIVER_OBJECT DriverObject, IN PDEVICE_OBJECT PhysicalDeviceObject

{ status = IoCreateDevice (... &deviceObject); fdoData = (PFDO_DATA) deviceObject->DeviceExtension;

fdoData->UnderlyingPDO = PhysicalDeviceObject;
deviceObject->Flags |= (DO_POWER_PAGABLE | DO_BUFFERED_IO); fdoData->NextLowerDriver = IoAttachDeviceToDeviceStack ( ); IoRegisterDeviceInterface ( &GUID_DEVINTERFACE_TOASTER); deviceObject->Flags &= ~DO_DEVICE_INITIALIZING; return status;

}

PnP/Power Boilerplate – WDM
DispatchPnp ( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp ) { status = IoAcquireRemoveLock (, Irp); switch (irpStack->MinorFunction) { case IRP_MN_START_DEVICE: status = IoForwardIrpSynchronously(, Irp); Irp->IoStatus.Status = status; IoCompleteRequest (Irp, IO_NO_INCREMENT); IoReleaseRemoveLock(, Irp); return status; case IRP_MN_REMOVE_DEVICE: IoReleaseRemoveLockAndWait(, Irp); IoSkipCurrentIrpStackLocation(Irp); status = IoCallDriver(, Irp); IoDetachDevice(); IoDeleteDevice(DeviceObject); return status; case IRP_MN_QUERY_STOP_DEVICE: status = STATUS_SUCCESS; break; case IRP_MN_CANCEL_STOP_DEVICE: status = STATUS_SUCCESS; break; case IRP_MN_STOP_DEVICE: status = STATUS_SUCCESS; break; case IRP_MN_QUERY_REMOVE_DEVICE: status = STATUS_SUCCESS; break; case IRP_MN_SURPRISE_REMOVAL: status = STATUS_SUCCESS; break; case IRP_MN_CANCEL_REMOVE_DEVICE: status = STATUS_SUCC

ESS; break; default: status = Irp->IoStatus.Status; break; } Irp->IoStatus.Status = status; status = ForwardIrp(NextLowerDriver, Irp); return status; } NTSTATUS DispatchPower( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp ) { status = IoAcquireRemoveLock (, ); PoStartNextPowerIrp(Irp); IoSkipCurrentIrpStackLocation(Irp); status = PoCallDriver(, Irp); IoReleaseRemoveLock(, ); return status; }

PnP/Power – WDF
WDF requires that you register zero or more of these callback events, depending on the device, to support pnp/power management Rest of this talk is about how and when to register these events, and how they map to WDM irps
EvtDeviceD0Entry EvtDeviceD0Exit EvtDevicePrepareHardware EvtDeviceReleaseHardware EvtInterruptEnable EvtInterruptDisable EvtDeviceD0EntryPostInterruptsDisabled EvtDeviceD0ExitPreInterrutpsDisabled EvtDmaEnablerFill EvtDmaEnablerFlush EvtDmaEnablerEnable EvtDmaEnablerDisable EvtDmaEnablerSelfManagedIoStart EvtDmaEnablerSelfManagedIoStop EvtDeviceArmWakeFromS0 EvtDeviceDisarmWakeFromS0 EvtDeviceArmWakeFromSx EvtDeviceDisarmWakeFromSx EvtDeviceWakeFromSxTriggered EvtDeviceWakeFromS0Triggered EvtDeviceSelfManagedIoInit EvtDeviceSelfManagedIoCleanup EvtDeviceSelfManagedIoSuspend EvtDeviceSelfManagedIoRestart EvtIoStop EvtIoResume EvtDeviceQueryRemove EvtDeviceQueryStop EvtDeviceSurpriseRemoval

EvtDeviceAdd – Software Driver
WdfDeviceInitSetIoType WdfDeviceInitSetExclusive WdfDeviceInitSetPowerNotPageable WdfDeviceInitSetPowerPageable WdfDeviceInitSetPowerInrush WdfDeviceInitSetDeviceType WdfDeviceInitAssignName WdfDeviceInitAssignSDDLString WdfDeviceInitSetDeviceClass WdfDeviceInitSetCharacteristics

NTSTATUS ToasterEvtDeviceAdd( IN WDFDRIVER Driver IN PWDFDEVICE_INIT DeviceInit ) { WdfDeviceInitSetIoType(DevcieInit WdfIoTypeBuffered);

WDF_OBJECT_ATTRIBUTES_INIT(&fdoAttributes); WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(&fdoAttributes FDO_DATA); status = WdfDeviceCreate(&DeviceInit &fdoAttributes &device); fdoData = ToasterFdoGetData(device);

status = WdfDeviceCreateDeviceInterface(&GUID_DEVINTERFACE_TOASTER );
return status; }

EvtDeviceAdd – Filter Driver
NTSTATUS FilterEvtDeviceAdd( IN WDFDRIVER Driver IN PWDFDEVICE_INIT DeviceInit ) { WdfFdoInitSetFilter(DeviceInit); WDF_OBJECT_ATTRIBUTES_INIT(&attributes); WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(&attributes FILTER_DATA); status = WdfDeviceCreate(&DeviceInit &attributes &device); fdoData = FilterGetDeviceContext(device); return status; }

EvtDeviceAdd – Hardware Driver
NTSTATUS EvtDeviceAdd( IN WDFDRIVER Driver, IN PWDFDEVICE_INIT DeviceInit ) { WdfDeviceInitSetIoType(DeviceInit, WdfDeviceIoDirect); WdfDeviceInitSetPnpPowerEventCallbacks WdfDeviceInitSetPowerPolicyEventCallbacks WdfDeviceInitSetPowerPolicyOwnership WdfDeviceInitSetIgnoreQueryStopRemove WdfDeviceInitRegisterPnpStateChangeCallback WdfDeviceInitRegisterPowerStateChangeCallback WdfDeviceInitRegisterPowerPolicyStateChangeCallback

WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks); pnpPowerCallbacks.E

vtDevicePrepareHardware = EvtPrepareHardware; pnpPowerCallbacks.EvtDeviceReleaseHardware = EvtReleaseHardware; pnpPowerCallbacks.EvtDeviceD0Entry = EvtDeviceD0Entry; pnpPowerCallbacks.EvtDeviceD0Exit = EvtDeviceD0Exit; WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, &pnpPowerCallbacks); WDF_OBJECT_ATTRIBUTES_INIT(&fdoAttributes); WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(&fdoAttributes, FDO_DATA); fdoAttributes.EvtCleanupCallback = EvtDeviceContextCleanup; status = WdfDeviceCreate(&DeviceInit, &fdoAttributes, &device); status = NICAllocateSoftwareResources(fdoData); …. return status; }

PnP/Power Callbacks
EvtDevicePrepareHardware
One time initialization, first callback where device is in D0 Map in memory mapped I/O, inspect hw for revision, features, etc.

EvtDeviceReleaseHardware
One time deinitialization, called when the device is in Dx! Unmap in memory mapped I/O, etc.

EvtDeviceD0Entry
Bring the device into D0, no interrupts connected

EvtDeviceD0Exit
Move the device into Dx, no interrupts connected

Mapping – WDF Callbacks to WDM IRPs
↑IRP_MN_START_DEVICE ↓IRP_MN_STOP_DEVICE ↓IRP_MN_SURPRISE_REMOVAL ↓IRP_MN_REMOVE_DEVICE EvtDeviceD0Entry ↑IRP_MN_START_DEVICE ↑ IRP_MN_SET_POWER – D0 Irp EvtDeviceD0Exit ↓ IRP_MN_SET_POWER – Dx Irp ↓IRP_MN_SURPRISE_REMOVAL ↓IRP_MN_REMOVE_DEVICE ↓IRP_MN_STOP_DEVICE EvtDeviceContextCleanup ↓IRP_MN_REMOVE_DEVICE EvtPrepareHardware EvtReleaseHardware Up arrow means callback is invoked when the IRP is completed by the lower driver. Down arrow means callback is invoked before forwarding the IRP

Self Managed I/O
Drivers may want to override automatic WDF queuing behavior by using non-power managed queues Drivers may have I/O paths that don?t pass through WDFQUEUEs (timers, DPC, etc.) WDF provides a set of callbacks that correspond to state changes
EvtDeviceSelfManagedIoInit EvtDeviceSelfManagedIoCleanup EvtDeviceSelfManagedIoSuspend EvtDeviceSelfManagedIoRestart EvtDeviceSelfManagedIoFlush

Self Managed I/O – Mapping
EvtDeviceSelfManagedIoInit EvtDeviceSelfManagedIoSuspend EvtDeviceSelfManagedIoRestart EvtDeviceSelfManagedIoFlush EvtDeviceSelfManagedIoCleanup START_DEVICE SURPRISE_REMOVAL or REMOVE, Power-Dx Power – D0, START after STOP REMOVE – For PDO it?s called when the PDO is present REMOVE - For PDO it?s called when the PDO is about to be deleted (SurpriseRemove)

PCIDRV sample uses Self Managed I/O callbacks to start and stop a watchdog timer DPC

Power Policy Owner
Default rules on power policy ownership Device Type
FDO Filter
PDO

Policy Owner
Yes No
No

Raw-PDO

Yes

Override the default by calling WdfDeviceInitSetPowerPolicyOwnership

Enabling Wake from Sx
WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS wakeSettings; WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT( &wakeSettings); status = WdfDeviceAssignSxWakeSettings(Device, &wakeSettings);

Interaction with WMI to present the power management tab in device manager is automatically handled Can be called multiple times to

change the settings at run-time Default is to allow user control

WDF_DEVICE_POWER_ POLICY_WAKE_SETTINGS Size DxState UserControlOfIdleSettings Enabled

Idle-Time Power Management – S0
WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS idleSettings; WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_ INIT( &idleSettings,IdleCanWakeFromS0 );

WDF_DEVICE_POWER_ POLICY_IDLE_SETTINGS Size

IdleCaps
DxState

IdleCannotWakeFromS0 IdleCanWakeFromS0 IdleUsbSelectiveSuspend

idleSettings.IdleTimeout = 10000; // 10-sec

UserControlOfIdleSettings IdleTimeout Enabled

status = WdfDeviceAssignS0IdleSettings( WdfDevice, &idleSettings );

You can manually stop and resume the IdleTimer by calling WdfDeviceStopIdle or WdDeviceResumeIdle WMI interaction is handled automatically Can be called multiple times to change the settings

Power Policy Event Callbacks
WDF_POWER_POLICY_EVENT_CALLBACKS powerPolicyCallbacks; WDF_POWER_POLICY_EVENT_CALLBACKS_INIT(&ppc); ppc.EvtDeviceArmWakeFromS0 = PciDrvEvtDeviceWakeArmS0; ppc.EvtDeviceDisarmWakeFromS0 = PciDrvEvtDeviceWakeDisarmS0; ppc.EvtDeviceWakeFromS0Triggered = PciDrvEvtDeviceWakeTriggeredS0; ppc.EvtDeviceArmWakeFromSx = PciDrvEvtDeviceWakeArmSx; ppc.EvtDeviceDisarmWakeFromSx = PciDrvEvtDeviceWakeDisarmSx; ppc.EvtDeviceWakeFromSxTriggered = PciDrvEvtDeviceWakeTriggeredSx;

WdfDeviceInitSetPowerPolicyEventCallbacks(Device, &powerPolicyCallbacks);

Mapping – Wake Callbacks to Power IRPs
Suspend or hibernate goto Sx
WDF receives IRP_MN_QUERY_POWER Sx WDF receives IRP_MN_SET_POWER Sx WDF sends IRP_MN_SET_POWER Dx WDF sends IRP_MN_WAIT_WAKE EvtDeviceArmWakeFromSx EvtDeviceD0Exit IRP_MN_WAIT_WAKE (completed by bus) Receives IRP_MN_SET_POWER S0 – fast resume Sends IRP_MN_SET_POWER D0 EvtDeviceD0 Entry EvtDeviceWakeFromSxTriggered EvtDeviceDisarmWakeFromSx Sends IRP_MN_SET_POWER Dx Sends IRP_MN_WAIT_WAKE EvtDeviceArmWakeFromS0 EvtDeviceD0Exit IRP_MN_WAIT_WAKE (completed by bus) Sends IRP_MN_SET_POWER - D0 EvtDeviceD0Entry EvtDeviceWakeFromS0Triggered EvtDeviceDisarmWakeFromS0

Resume from Sx due to wake event

Idle-out - goto Dx in S0

Resume from Dx in S0 due to wake event

Interrupts
NTSTATUS EvtDeviceAdd( ) { … WDF_INTERRUPT_CONFIG_INIT(&Config, NICInterruptHandler, NICDpcForIsr);

WDF_INTERRUPT_CONFIG Size SpinLock ShareVector FloatingSave QueueDpcOnIsrSuccess AutomaticSerialization EvtInterruptIsr EvtInterruptDpc EvtInterruptEnable EvtInterruptDisable

Config.EvtInterruptEnable = NICEvtInterruptEnable; Config.EvtInterruptDisable = NICEvtInterruptDisable;
status = WdfInterruptCreate(Device, &Config, WDF_NO_OBJECT_ATTRIBUTES, &Interrupt); }

WdfInterruptQueueDpcForIsr – to manually queue DpcForIsr Register EvtDeviceD0EntryPostInterruptsEnabled and EvtDeviceD0ExitPreInterruptsDisabled to be called at PASSIVE_LEVEL

FDO and PDO-Specific Callbacks
Register FDO-specific events by calling WdfFdoInitSetEventCallbacks
EvtDeviceFilterAddResourceRequirements ↓IRP_MN_FILTER_RESOURCE_R EQUIREMENTS

EvtDeviceFilterRemoveResourceRequirements ↑I

RP_MN_IRP_MN_FILTER_RES OURCE_REQUIREMENTS EvtDeviceRemoveAddedResources ↓ IRP_MN_START_DEVICE

Register PDO-specific events by calling WdfPdoInitSetEventCallbacks
EvtDeviceResourcesQuery ↓ IRP_MN_QUERY_RESOURCE

EvtDeviceResourceRequirementsQuery ↓IRP_MN_QUERY_RESOURCE_REQUIR EMENTS
EvtDeviceEject EvtDeviceSetLock EvtDeviceEnableWakeAtBus EvtDeviceDisableWakeAtBus ↓ IRP_MN_EJECT ↓ IRP_MN_SET_LOCK ↓ IRP_MN_WAIT_WAKE ↑ IRP_MN_WAIT_WAKE

Summary - Callback Order
? ? ? ? WDF treats PnP and Power as a unified model WDF callbacks are based around primitive operations Order in which the primitives are called is guaranteed Next two slides show the order in which these callback are invoked for start/power-up and remove/suspend
EvtDeviceD0Entry EvtDeviceD0Exit EvtDevicePrepareHardware EvtDeviceReleaseHardware EvtDeviceQueryRemove EvtDeviceQueryStop EvtDeviceSurpriseRemoval EvtDeviceSelfManagedIoInit EvtDeviceSelfManagedIoCleanup EvtDeviceSelfManagedIoSuspend EvtDeviceSelfManagedIoRestart EvtIoStop EvtIoResume EvtInterruptEnable EvtInterruptDisable EvtDeviceD0EntryPostInterruptsDisabled EvtDeviceD0ExitPreInterrutpsDisabled EvtDeviceArmWakeFromS0 EvtDeviceDisarmWakeFromS0 EvtDeviceArmWakeFromSx EvtDeviceDisarmWakeFromSx EvtDeviceWakeFromSxTriggered EvtDeviceWakeFromS0Triggered EvtDmaEnablerFill/Flush EvtDmaEnablerEnable/Disable EvtDmaEnablerSelfManagedIoStart/Stop

– You can see the commonalities between pnp & power operation

Start/Power Up Path
DState = D3Final

1

STOPPED

AddDevice

2

EvtDeviceRemoveAddedResources EvtPrepareHardware

This flow chart shows the order Device, I/O, Interrupt and DMA callbacks are invoked when the device is first started, started from stopped state due to resource rebalance or from a suspended state
WDF
Were you armed for wake? NO

SUSPENDED
DState = DX

EvtDeviceD0Entry(DState) EvtInterruptEnable EvtDeviceD0EntryPostInterruptsEnabled EvtDmaEnablerFill/Enable EvtDmaEnablerSelfManagedIoStart EvtDeviceWakeDisarmSx or S0 YES

EvtIoResume - on in-flight request EvtDeviceSelfManagedIoRestart

First power up?

NO

EvtDeviceSelfManagedIoInit
YES

STARTED

Remove/Surprise-Remove/Stop/ Power-Down Path
WDF
YES Stopping or removing? NO YES Arm for wake? NO

STARTED

EvtDeviceSelfManagedIoSuspend EvtIoStop (Suspend) - on every inflight request

EvtDeviceArmWakeFromSx or S0 EvtDmaEnablerSelfManagedIoStop EvtDmaEnablerDisable EvtDmaEnablerFlush EvtDeviceD0ExitPreInterruptsDisabled EvtInterruptDisable EvtDeviceD0Exit(DState)

YES

2

SUSPENDED

Power down?

NO EvtReleaseHardware

YES

1

NO STOPPED Remove?

EvtIoStop (Purge) - on every inflight request EvtDeviceSelfManagedIoFlush EvtDeviceSelfManagedIoCleanup EvtObjectCleanup(Device)

REMOVED

I/O Stage
WDFREQUEST I/O Package Read/Write/IOCTLs/ Create/Close/Cleanup Manual Queue PnP/Power Events I R P PnP/Power Events Sequential Queue Parallel Queue

IRP Dispatcher

PnP/Power Package

IoTarget Next Driver
PnP/Power/WMI IRPs

PnP/Power Events

Hardware Resource M

anagement (DMA, Interrupt, I/O)

WMI Package

Queues
Queue object is used to present WDFREQUEST to the driver Only create, read, write, and IOCTL IRPs are converted to WDFREQUEST and presented by queues Delivery of requests is based on the queue type
Sequential: Requests are delivered one at a time Parallel: Requests are delivered to the driver as they arrive Manual: Driver retrieves requests from the WDQUEUE at its own pace

WDF_EXECUTION_LEVEL and WDF_SYNCHRONIZATION_SCOPE can be used to control serialization and IRQL level of those callbacks WDFQUEUE is more than a list of pending requests!

Creating a Queue
WDF_IO_QUEUE_CONFIG
NTSTATUS EvtDeviceAdd( IN WDFDRIVER Driver, IN PWDFDEVICE_INIT DeviceInit ) { ….
WDF_IO_QUEUE_CONFIG_INIT_DEFUALT_QUEUE(

Size
DispatchType PowerManaged DefaultQueue AllowZeroLengthRequests EvtIoDefault EvtIoRead EvtIoWrite EvtIoDeviceControl EvtIoInternalDeviceControl EvtIoStop EvtIoResume
typedef enum _WDF_IO_QUEUE_DISPATCH_TYPE { WdfIoQueueDispatchSequential = 1, WdfIoQueueDispatchParallel, WdfIoQueueDispatchManual, WdfIoQueueDispatchMax } WDF_IO_QUEUE_DISPATCH_TYPE;

&Config, WdfIoQueueDispatchParallel );
Config.EvtIoStart = PciDrvEvtIoStart; Config.AllowZeroLengthRequests = TRUE;

status = WdfIoQueueCreate( WdfDevice, &Config, WDF_NO_OBJECT_ATTRIBUTES, &Queue // queue handle );
return status; }

WDFQUEUE Events
EvtIoDefault – Called for any request that does not have a specific callback registered EvtIoRead – Called for IRP_MJ_READ requests EvtIoWrite – Called for IRP_MJ_WRITE requests EvtIoDeviceControl – Called for IRP_MJ_DEVICE_CONTROL EvtIoInternalDeviceControl – Called for IRP_MJ_INTERNAL_DEVICE_CONTROL requests EvtIoStop – Called for all inflight requests when a power down transition occurs EvtIoResume - Called for all inflight requests when a power up transition occurs

Default Queue
Default queue receives all requests that are not configured to go to other queues There can be only one default queue per device
Read/W rite/ IOCTLs IRPS

EvtIoDefault Default
I/O Package

Parallel Queue

EvtIoDeviceControl

Pnp/Power Events

PnP/Power

Preconfigured Queue
Preconfigure the queue by calling WdfDeviceConfigureRequestDispatching to automatically forward requests based on the I/O type
Read/ Write/ IOCTLs IRPS Write & Read WDFREQUESTS

Default
I/O Package

EvtIoDefault

Parallel Queue

PnP/Power Events

EvtIoDeviceControl

IOCTL
Parallel Queue

PnP/Power

Multiple queues
Manually forward requests by calling
WdfRequestForwardToIoQueue
WDFREQUEST Parallel - Read

Read/ Write/ IOCTL

I/O Package Sequential - Write

PnP/Power Events Parallel - IOCTL Manual Queue

PnP/Power

Queue State
Queue state is determined by whether it?s accepting and dispatching requests to the driver
Started Accept Queue Draining Purging Accepting – N Accepting – N Dispatching - Y Dispatching - N Dispatch Stopped Accepting – Y Accepting – Y Dispatching - Y Dispatching - N

For non-power managed queue, driver control

s the state of the queue
Queue can be moved to any state from any state

For power managed queue, state change happens due to PnP/Power events

DDIs for Changing Queue States
WdfIoQueueStart WdfIoQueueStop WdfIoQueueStopSynchronously WdfIoQueueDrain WdfIoQueueDrainSynchronously WdfIoQueuePurge WdfIoQueuePurgeSynchronously
Accept and dispatch requests Accept and queue requests

Accept and queue requests, and wait for the driver-owned request to complete before returning to the caller
Fail new requests and dispatch queued requests

Fail new requests, dispatch queued requests and wait for all the requests to complete before returning to the caller
Fail new requests, cancel queued requests, cancel in-flight requests (if marked cancelable) Fail new requests, cancel queued requests, cancel in-flight requests (if they are marked cancelable), and wait for all the requests to complete before returning to the caller

Power Managed Queue
Power State Accept Dispatch

AddDevice - Created
ON/OFF

Accepting - Yes Power State - OFF Dispatching - Yes

START_DEVICE
SET_POWER (D0) SET_POWER (Dx) STOP_DEVICE
Accepting - Yes Power State - ON Dispatching - Yes

REMOVE_DEVICE
Purge power managed and unmanaged queues
Accepting - No Power State - OFF Dispatching - Yes

Deleted

REMOVE_DEVICE

SURPRISE_REMOVAL

Create/Cleanup/Close
Register during device initialization if you are interested in handling Create, Close and Cleanup requests WDF by default succeeds these requests if you don?t register a callback
Size

WDF_DEVICE_FILE_OBJECT_INIT( &fileObjConfig, FileIoEvtDeviceFileCreate, FileIoEvtDeviceClose, WDF_NO_EVENT_CALLBACK); WdfDeviceInitSetFileObjectConfig(DeviceInit, &fileObjConfig, WDF_NO_OBJECT_ATTRIBUTES);

AutoForwardCleanupClose

EvtDeviceFileCreate
EvtFileClose EvtFileCleanup FileObjectClass

EvtDeviceFileCreate( WDFDEVICE Device, EvtFileCleanup(WDFFILEOBJECT FileObject) WDFREQUEST Request, WDFFILEOBJECT FileObject EvtFileClose(WDFFILEOBJECT FileObject); )

Create/Close/Cleanup Create request
You can pend, forward it another queue, send it to an IoTarget You can configure to auto-dispatch create to a specific queue EvtIoDefault callback is invoked when a create request is dispatched by a queue

Cleanup/Close
WDF doesn?t provide a request for these events If you send create requests down the stack, you must set the AutoForwardCleanupClose property so that WDF can forward Cleanup and Close requests

For filters, if the callbacks are not registered, WDF will auto-forward Create, Close and Cleanup

Request Cancellation
Requests waiting in the queue to be delivered to the driver are automatically cancelable In-flight requests cannot be canceled unless explicitly made cancelable by calling
WdfRequestMarkCancelable(Request, EvtRequestCancel)

A request should be made cancelable by the driver if:
The I/O is going to take long time to complete The I/O operation on the hardware can be stopped in mid-operation

A cancelable request must be unmarked (WdfRequestUn

markCancelable) before completion unless it?s completed by the cancel routine These rules are similar to WDM

Read/Write/IOCTL Callbacks
VOID VOID EvtIoRead( EvtIoWrite( IN WDFQUEUE IN WDFQUEUE Queue, IN WDFREQUEST Request, IN WDFREQUEST IN size_t IN size_t Length ) ) VOID EvtIoDeviceControl( IN WDFQUEUE Queue, IN WDFREQUEST Request, IN size_t OutputBufferLength, IN size_t InputBufferLength, IN ULONG IoControlCode )

Queue, Request, Length

Request Buffers Getting input buffer
WdfRequestRetrieveInputBuffer WdfRequestRetrieveInputMemory WdfRequestRetrieveInputWdmMdl

Getting output buffer
WdfRequestRetrieveOutputBuffer WdfRequestRetrieveOutputMemory WdfRequestRetrieveOutputWdmMdl

?Input? or ?Output? denotes the direction of memory access
Input: read from memory and write to device Output: read from device and write to memory

Retrieve Buffer of Read Request
Function
WdfRequestRetrieveO utputBuffer
WdfRequestRetrieveO utputWdmMdl WdfRequestRetrieveO uputMemory

Read - Buffered
Return Irp->AssociatedIrp.
SystemBuffer

Read - Direct
Return SystemAddressForMdl( Irp->MdlAddress)
Return Irp->MdlAddress

Build an MDL for
Irp->AssociatedIrp.SystemBuffer

and return the MDL.
WdfMemoryBufferGetBuffer on the returned WDFMEMORY will give you Irp>AssociatedIrp.SystemBuffer

WdfMemoryBufferGetBuffer on the returned WDFMEMORY will give you SystemAddressFor( Irp->MdlAddress).

Calling WdfRequestRetrieveInputXxx functions on Read request will return STATUS_INVALID_DEVICE_REQUEST error.

Retrieve Buffer of Write Request
Function
WdfRequestRetrieve InputBuffer
WdfRequestRetrieve InputWdmMdl WdfRequestRetrieve InputMemory

Read - Buffered
Return Irp->AssociatedIrp.
SystemBuffer

Read - Direct
Return SystemAddressForMdl( Irp->MdlAddress)
Return Irp->MdlAddress

Build an MDL for
Irp->AssociatedIrp.SystemBuffer

and return the MDL.
WdfMemoryBufferGetBuffer on the returned WDFMEMORY will give you Irp>AssociatedIrp.SystemBuffer

WdfMemoryBufferGetBuffer on the returned WDFMEMORY will give you SystemAddressFor( Irp->MdlAddress).

Calling WdfRequestRetrieveOutputXxx functions on Write request will return STATUS_INVALID_DEVICE_REQUEST error

Retrieve Buffers of IOCTL Request
Function
WdfRequestRetrieveInputBuffer WdfRequestRetrieveInputWdmMdl WdfRequestRetrieveInputMemory

Buffered - IOCTL
Return Irp->AssociatedIrp. SystemBuffer Build an MDL for Irp->AssociatedIrp. SystemBuffer and return the MDL WdfMemoryBufferGetBuffer on the returned WDFMEMORY will give you Irp->AssociatedIrp.SystemBuffer Return Irp->AssociatedIrp. SystemBuffer Build an MDL for Irp->AssociatedIrp. SystemBuffer and return the MDL WdfMemoryBufferGetBuffer on the returned WDFMEMORY will give you Irp->AssociatedIrp.SystemBuffer

WdfRequestRetrieveOutputBuffer
WdfRequestRetrieveOutputWdmMdl WdfRequestRetrieveOutputMemory

Retrieve Buffers of IOCTL Request (con’t)
Function
WdfRequestRetrieveInputBuffer WdfRequestRetrieveInputWdmMdl WdfRequestRetrieveInputMemory

Buffered - IOCTL
Return Irp->A

ssociatedIrp. SystemBuffer Build an mdl for Irp->AssociatedIrp. SystemBuffer and return the MDL WdfMemoryBufferGetBuffer on the returned WDFMEMORY will give you Irp->AssociatedIrp.SystemBuffer Return SystemAddressForMdl(Irp>MdlAddress ) Return Irp->MdlAddress WdfMemoryBufferGetBuffer on the returned WDFMEMORY will give SystemAddressFor( Irp->MdlAddress)

WdfRequestRetrieveOutputBuffer WdfRequestRetrieveOutputWdmMdl WdfRequestRetrieveOutputMemory

METHOD_NEITHER Requests
To handle this type of request, you must register EvtIoInCallerContext callback by calling WdfDeviceInitSetIoInCallerContextCallback Callback is invoked in the calling thread context Retrieve buffers using
WdfRequestRetrieveUnsafeUserInputBuffer WdfRequestRetrieveUnsafeUserOutputBuffer Lock using WdfRequestProbeAndLockUserBufferForRead/Write
Read Write InputBuffer Error Irp->UserBuffer OutputBuffer Irp->UserBuffer Error Irp->UserBuffer

IOCTL irpStack->Parameters. DeviceIoControl.Type3InputBuffer

Timer/DPC/Work Item
WDFTIMER
WDFDPC

WDFWORKITEM

KTIMER (KeInitializeTimerEx) KDPC (KeInitializeDpc) IO_WORKITEM (IoAllocateWorkItem)

Value add
Allows you to synchronize execution with the callback events of a specific queue (by parenting to WDFQUEUE) or all queues (by parenting to WDFDEVICE) Ensures callbacks events are not invoked after the object is deleted – rundown protection Ensures that object is not deleted until the callback has run to completion Enables you to have private context

DPC
WDF_DPC_CONFIG NTSTATUS EvtDeviceAdd( ) { … WDF_DPC_CONFIG_INIT(&config, EvtDpc); config.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

Size EvtDpcFunc DriverWdmDpc AutomaticSerialization

attributes.ParentObject = device;

WdfDpcCreate() WdfDpcEnqueue() WdfDpcCancel(Wait) WdfDpcGetParentObject() WdfDpcWdmGetDpc() WdfObjectDelete()

status = WdfDpcCreate(&Config, &attributes, &hDpc); }

Timer
WDF_TIMER_CONFIG NTSTATUS EvtDeviceAdd( ) { … WDF_TIMER_CONFIG_INIT(&config, EvtTimer); config.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

Size EvtTimerFunc Period AutomaticSerialization

attributes.ParentObject = device; status = WdfTimerCreate(&Config, &attributes, &hTimer); }

WdfTimerCreate() WdfTimerStart() WdfTimerStop(Wait) WdfTimerGetParentObject() WdfObjectDelete()

Work Item
WDF_TIMER_CONFIG NTSTATUS EvtDeviceAdd( ) { … WDF_WORKITEM_CONFIG_INIT(&config, EvtWorkItem); config.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

Size EvtWorkItemFunc AutomaticSerialization

WdfWorkItemCreate() attributes.ParentObject = device; status = WdfWorkItemCreate(&Config, &attributes, &hWorkItem); } WdfWorkItemEnqueue() WdfWorkItemFlush() WdfWorkItemGetParentObject() WdfObjectDelete()

Locks
Framework provides two kinds of locks:
WDFWAITLOCK
Synchronize access to resources at IRQL <
DISPATCH_LEVEL WDF WdfWaitLockCreate WdfWaitLockAcquire (Optional - TimeOut) WdfWaitLockRelease

Mapping
WDM KeInitializeEvent (Sychronization

Event) KeEnterCriticalRegion KeWaitForSingleObject KeSetEvent KeLeaveCriticalRegion

WDFSPINLOCK –
Synchronize access to resources at IRQL <=
DISPATCH_LEVEL

Value add
Has its own deadlock detection support Tracks acquisition history WaitLock protects against thread suspension You can have private context specific to lock
WDF WdfSpinLockCreate WdfSpinLockAcquire WDM KeInitializeSpinLock KeAcquireSpinLock

WdfSpinLockRelease KeReleaseSpinLock

Synchronization Scope & Execution Level
WDF_EXECUTION_LEVEL WDF_SYNCHRONIZATION_SCOPE WdfSynchronizationScopeInheritFromParent WdfSynchronizationScopeDevice WdfSynchronizationScopeObject WdfSynchronizationScopeNone

WdfExecutionLevelInheritFromParent
WdfExecutionLevelPassive WdfExecutionLevelDispatch

WdfExecutionLevelPassive
Callbacks will be invoked at PASSIVE_LEVEL Can be set only on device, queue and fileobject Creation of timer and DPC with AutomaticSerialization won?t be allowed if this attribute is set on its parent which could be device or queue

WdfSynchronizationScopeDevice
Callback events of queue, fileobject, timer, dpc, & workitem will be synchronized by a common lock Choice of lock depends on the execution level (fast mutex or spinlock)

WdfSynchronizationScopeObject
Can be set only on queue if you want all the callbacks of a queue to be serialized with its own lock

Sample Scenario – Serial
DriverEntry() { WDF_OBJECT_ATTRIBUTES_INIT(&attributes); attributes.SynchronizationScope = WdfSynchronizationScopeDevice; status = WdfDriverCreate(,,&attributes,,); } EvtDeviceAdd() { WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&queueConfig, Parallel); queueConfig.EvtIoRead = SerialEvtIoRead; queueConfig.EvtIoWrite = SerialEvtIoWrite; WDF_OBJECT_ATTRIBUTES_INIT(&attributes); attributes.SynchronizationScope = WdfSynchronizationScopeDevice; status = WdfIoQueueCreate(, queueConfig,&attributes, );

WDF_OBJECT_ATTRIBUTES_INIT(&attributes); attributes.ParentObject = Device; WDF_TIMER_CONFIG_INIT(&timerConfig, SerialTimeoutXoff); timerConfig.AutomaticSerialization = TRUE;
status = WdfTimerCreate(&timerConfig, &attributes,);

}

Synchronization Scope & Execution Level - Summary
Object
WDFDRIVER

Locks: what kind and who provides it?
If you specify SynchScopeObject, framework acquires fast mutex when it calls EvtDeviceAdd. Since there is no parent for WDFDRIVER, the SynchScopeInheritFromParent is same as SynchScopeNone. If SynchScopeDevice is used, all the devices will be created with SynchScopeDevice attributes. Depending on the ExecutionLevel, this object provides a spin lock or fast mutex as the presentation lock to other objects such as WDFQUEUE WDFDPC, WDFTIMER, WDFWORKITEM, WDFFILEOBJECT. PnP/Power events do not use this presentation lock. If you specify SynchScopeDevice or InheritFromParent, lock is provided by the device. If you specify SynchScopeObject, lock is provided by the queue. Depending on the execution level, the lock is either a spin lock or fast mutex. SynchScopeObject is not allowed on this o

bject. If you specify ExecLevelPassive and SynchScopeDevice or InheritFromParent then the parent device ExecLevel should also be Passive.

WDFDEVICE

WDFQUEUE

WDFFILEOBJECT

WDFTIMER/DPC/ WORKITEM

By setting AutomaticSerialization property, you can synchronize its events with the parent object?s events

I/O Target
I/O Package

WDFREQUEST Parallel Queue
Read/Write/IOCTLs/ Create/Close/Cleanup

Sequential Queue Manual Queue

I R P

PnP/Power Events PnP/Power Events Next Driver

IRP Dispatcher

PnP/Power Package

IoTarget

PnP/Power Events Hardware Resource Management WMI Package (DMA, Interrupt, I/O)

Sending Request - I/O Target
What is an IoTarget?
A “target” device object to which you want to send requests This “target” device object can be the next attached device (default target) or can be a device object outside your device stack (remote target)

Where would I use it?
Instead of IoCallDriver() – either for forwarding request that you received from driver above or when you are rolling your own request and sending to another driver
IoTarget sends I/O in coordination with PnP state of the target owner and the target state itself IoTarget provides synchronization of sent I/O with target state changes

Default I/O Target
WdfDeviceGetIoTarget returns WDFIOTARGET for the next lower device object
ForwardRequest( WDFDEVICE Device, WDFREQUEST Request) { BOOLEAN ret; WDFIOTARGET ioTarget = WdfDeviceGetIoTarget(Device); WdfRequestCopyCurrentStackLocationToNext ( Request ); WdfRequestSetCompletionRoutine (Request, CompletionRoutine, NULL); ret = WdfRequestSend (Request, ioTarget, NULL); if (!ret) { status = WdfRequestGetStatus (Request); DebugPrint( ("WdfRequestSend failed: 0x%x\n", status)); WdfRequestComplete(Request, status); } }

Remote I/O Target
Remote I/O target represents a device object: either part of your driver or created by some other driver Replacement for IoGetDeviceObjectPointer, ZwCreateFile & IoRegisterPlugPlayNotification( EventCategoryTa rgetDeviceChange ) status = WdfIoTargetCreate(Device, INIT_OPEN_BY_NAME
WDF_NO_OBJECT_ATTRIBUTES, &IoTarget);
INIT_CREATE_BY_NAME

WDF_IO_TARGET_OPEN_PARAMS_INIT_EXISTING_DEVICE(

&openParams, WdfTrue, DeviceObject); status = WdfIoTargetOpen(IoTarget, &openParams);

Send Your Own Request - Synchronous IoBuildSynchronousFsdRequest maps to:
WdfIoTargetSendReadSynchronously WdfIoTargetSendWriteSynchronously

IoBuildDeviceIoControlRequest maps to:
WdfIoTargetSendIoctlSynchronously WdfIoTargetSendInternalIoctlSynchronously WdfIoTargetSendInternalIoctlOthersSynchronously

Send Your Own Request - Synchronous
Buffers used in synchronous requests can be a PVOID, MDL or WDFMEMORY handle INIT_MDL
INIT_HANDLE

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&inputBufDesc, &inBuf, inLen); WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&outputBufDesc, outBuf,outLen); status = WdfIoTargetSendIoctlSynchronously(ioTarget, NULL, // let framework allocate IRP IOCTL_ACPI_ASYNC_EVAL_METHOD, &inputBufDesc, &outputBufDesc, NULL, //

Option NULL); // bytesReturned

Requests may be sent with a combination of the following options
Timeout Force Send (override I/O Target?s Dispatching state)

Roll Your Own Request- Asynchronous
IoBuildAsynchronousFsdRequest maps to WdfIoTargetFormatRequestForWrite WdfIoTargetFormatRequestForRead WdfIoTargetFormatRequestForIoctl WdfIoTargetFormatRequestForInternalIoctl followed by - WdfRequestSend I/O targets exclusively use reference counted memory handles for asynchronous IO The driver cannot use raw pointers!

Send Your Own Request - Asynchronous
status = WdfRequestCreate(WDF_NO_OBJECT_ATTRIBUTES, IoTarget, &Request); status = WdfMemoryCreate(WDF_NO_OBJECT_ATTRIBUTES, NonPagedPool, POOL_TAG, sizeof(struct ABC), &Memory, (PVOID*) &buffer); status = WdfIoTargetFormatRequestForRead(IoTarget, Request, Memory, //InputBuffer NULL, // BufferOffset NULL); // DeviceOffset WdfRequestSetCompletionRoutine(Request, ReadRequestCompletion, WDF_NO_CONTEXT);
if( WdfRequestSend(Request, IoTarget, NULL) == FALSE) { status = WdfRequestGetStatus(Request); }

Escape to WDM
Converting to WDF is an iterative process Do the conversion stage by stage
PNP/POWER – escape to WDM for other things Request handling I/O Target

WDF allows you to get all the underlying WDM objects easily
WdfRequestWdmGetIrp WdfDeviceWdmGetAttachedDevice WdfDeviceWdmGetPhysicalDevice WdfDeviceWdmGetDeviceObject

Great Escape
I/O Package Complete IRP

WDFREQUEST Parallel Queue Sequential Queue Manual Queue PnP/Power Events

Read/Write/IOCTLs

IRP
Dispatcher

Preprocessor

PnP/Power Package

IoTarget

Forward to Next Driver

PnP/Power Events

Hardware Resource Management (DMA, Interrupt, I/O)

WMI Package

Great Escape – Sample Code
EvtDeviceAdd() { status = WdfDeviceInitAssignWdmIrpPreprocessCallback( DeviceInit, PowerDispatchHandler, IRP_MJ_POWER, NULL, 0); } NTSTATUS PowerDispatchHandler(WDFDEVICE Device, PIRP Irp) { irpStack = IoGetCurrentIrpStackLocation(Irp); irpString = (irpStack->Parameters.Power.Type == SystemPowerState) ? "S-IRP" : "D-IRP"; state = irpStack->Parameters.Power.State; extensionHeader = GetDeviceContext(Device); DebugPrint((0, "%s: %s %s %s:0x%x \n", (extensionHeader->IsFdo? "FDO":"PDO"), irpString, PowerMinorFunctionString(irpStack->MinorFunction), powerStateString, Irp)); return WdfDeviceWdmDispatchPreprocessedIrp(Device, Irp); }

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 special guest account (Guest ID: Guest4WDF) on http://beta.microsoft.com

Provide feedback
Email
windf @ microsoft.com umdfdbk @ microsoft.com drvpft @ microsoft.com sdvfdbk @ microsoft.com Kernel Mode Driver Framework User Mode Driver Framework PREfast for Drivers Static Driver Verifier

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

Reference Slides

Sample Scenarios – Callback Order
Following slides show in what order all the events of device, queue, interrupt and DMA enabler object are triggered by the PnP/Power stage for the following scenarios
Start device Disable or uninstall the device Surprise-Removal Resource rebalance Failed query-remove or failed query-stop System suspend System resume

Slides also show the PnP/Power IRP context in which these events are invoked

Start Device
AddDevice
EvtDeviceAdd

IRP_MN_START_DEVICE
EvtDevicePrepareHardware EvtDeviceD0Entry EvtInterruptEnable EvtDeviceD0EntryPostInterruptsEnabled EvtDmaEnablerEnable EvtDmaEnablerFill EvtDmaEnablerSelfManagedIoStart EvtDeviceSelfManagedIoInit

Disable or Uninstall Device
IRP_MN_QUERY_REMOVE_DEVICE
EvtDeviceQueryRemove

IRP_MN_REMOVE_DEVICE
EvtDeviceSelfManagedIoSuspend EvtIoStop – Suspend EvtDmaEnablerSelfManagedIoStop EvtDmaEnablerDisable EvtDmaEnablerFlush EvtInterruptDisable EvtDeviceD0Exit - D3Final EvtDeviceReleaseHardware EvtIoStop - Purge EvtDeviceSelfManagedIoFlush EvtDeviceSelfManagedIoCleanup EvtDeviceContextCleanup

_WDF_POWER_DEVICE_STATE { WdfPowerDeviceUnspecified = 0, WdfPowerDeviceD0, WdfPowerDeviceD1, WdfPowerDeviceD2, WdfPowerDeviceD3, WdfPowerDeviceD3Final, WdfPowerDevicePrepareForHiber, WdfPowerDeviceMaximum, } WDF_POWER_DEVICE_STATE,

Surprise Remove Device
IRP_MN_SURPRISE_REMOVAL
EvtDeviceSurpriseRemoval EvtDeviceSelfManagedIoSuspend EvtIoStop – Suspend EvtDmaEnablerSelfManagedIoStop EvtDmaEnablerDisable EvtDmaEnablerFlush EvtInterruptDisable EvtDeviceD0Exit - D3Final EvtDeviceReleaseHardware EvtIoStop - Purge EvtDeviceSelfManagedIoFlush EvtDeviceSelfManagedIoCleanup

IRP_MN_REMOVE_DEVICE
EvtDeviceContextCleanup

Resource Rebalance
IRP_MN_QUERY_STOP_DEVICE
EvtDeviceQueryStop

IRP_MN_STOP_DEVICE
EvtDeviceSelfManagedIoSuspend EvtIoStop – Suspend EvtDmaEnablerSelfManagedIoStop EvtDmaEnablerDisable/Flush EvtInterruptDisable EvtDeviceD0Exit - D3Final EvtDeviceReleaseHardware

IRP_MN_START_DEVICE
EvtDevicePrepareHardware EvtDeviceD0Entry EvtInterruptEnable EvtIoResume EvtDmaEnablerEnable/Fill EvtDmaEnablerSelfManagedIoStart EvtDeviceSelfManagedIoRestart

Failed Remove or Stop
Failed Remove
IRP_MN_QUERY_REMOVE_DEVICE
EvtDeviceQueryRemove

IRP_MN_CANCEL_REMOVE_DEVICE

Failed Stop:
IRP_MN_QUERY_STOP_DEVICE
EvtDeviceQueryStop

IRP_MN_CANCEL_STOP_DEVICE

System Suspend
IRP_MN_QUERY_POWER Sx
(WDF doesn?t send IRP_MN_QUERY_POWER Dx)

IRP_MN_SET_POWER Sx IRP_MN_SET_POWER Dx
EvtDeviceSelfManagedIoSuspend EvtIoStop - Suspend on every in-flight request WDF sends IRP_MN_WAIT_WAKE EvtDeviceArmWakeFromSx EvtDmaEnablerSelfManagedIoStop EvtDmaEnablerDisable/Flush EvtInterruptDisable EvtDeviceD0Exit

System Resume
System sends IRP_MN_SET_POWER S0
WDF completes it first to allow fast resume Then WDF sends IRP_MN_SET_POWER D0

WDF cancels IRP_MN_WAIT_WAKE IRP_MN_SET_POWER D0
EvtDeviceD0Entry EvtInterruptEnable EvtDmaEnablerFill EvtDmaEnablerEnable EvtDma

EnablerSelfManagedIoStart EvtIoResume EvtDeviceSelfManagedIoRestart EvtDeviceDisarmWakeFromSx

Parsing HW Resources
NTSTATUS PciDrvEvtDevicePrepareHardware ( WDFDEVICE Device, WDFCMRESLIST Resources, WDFCMRESLIST ResourcesTranslated ) { PCM_PARTIAL_RESOURCE_DESCRIPTOR desc; for (i=0; i<WdfCmResourceListGetCount(ResourcesTranslated); i++) desc = WdfCmResourceListGetDescriptor(ResourcesTranslated, i); switch (desc->Type) { case CmResourceTypePort: break; case CmResourceTypeMemory: break; } } } {

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


网站首页网站地图 站长统计
All rights reserved Powered by 海文库
copyright ©right 2010-2011。
文档资料库内容来自网络,如有侵犯请联系客服。zhit326@126.com