1. Windows® Driver Model History And Architectural Overview Bob Rinne Director Windows Operating System Base Microsoft Corporation

3. Purpose Of This Talk The WDM reality
Discuss what is covered in WDM
It has taken a long time
Get an overview of its history and versions
Get an overview of the architectures
Basic information for navigating through WDM

4. Technical Outline Goals of WDM History of WDM Current state
Overview of WDM

5. Goals Of WDM
Common development environment for Windows NT® and Windows 9x family products
Method of bringing Plug and Play and Power Management to Windows NT
Binary compatibility between products
Broad coverage of new technology busses

6. What Is WDM NDIS/SCSI System environment Bus support
Pre-WDM, but satisfies goals
System environment
Bus support
Device class support

7. History Of WDM Introduced after Windows 95 launch
First available in Windows 98
Now available in Windows 2000
Is present on Windows ME with enhancements from Windows 98

8. History Of WDM Windows 98 versions
Started from a device oriented Plug and Play operating system
Added portable abstractions and I/O subsystem from Windows NT
Provided definition for Plug and Play and power management mapping to Windows NT
Work done as a mapper between WDM and Windows 95 core

9. Windows 98 And Me Applications System services Virtual Memory Manager
System VM
MS-DOS VM
Applications
MS-DOS VM
MS-DOS VM
System services
Installable
file system
Windows NT I/O Manager
Virtual Memory Manager
FSD
FSD
Device drivers
Windows 95
I/O subsystem
Services
Device drivers
Drivers
HAL

10. History Of WDM Windows NT version
Started from non-Plug and Play, “driver”-oriented operating system
Made WDM interfaces native
Converted to Plug and Play/“device”- oriented operating system

11. Windows NT Daemons Services Environments Applications
Other
Other
Spooler
Replicator
File server
Logon
Security
Alerter
Session manager
Event logger
Windows
LPC
LPC
LPC
LPC
Windows NT System
I/O manager
Security monitor
Executive
Power
Management
Memory Management
Process support
File systems
Object management/executive run time
Device drivers
Kernel
Hardware abstraction layer
Platform interface
I/O
devices
DMA
control
Bus mapping
Clocks/ timers
Cache control
Interrupt dispatch
Privileged architecture

12. Current State WDM is real
There now is a common development environment
Binary compatibility is possible
Unfortunately it is harder than we wanted
Requires extensive testing on all versions of all operating systems

13. Current State Busses covered Still have NDIS and SCSI USB 1394
New ones coming

14. Current State Devices covered Input Cameras/Scanners Audio WinModem
Storage (*)
Many more
New ones coming

15. Current State
What’s not there
Video
Generic storage
Super I/O chip

16. Overview Of WDM Breakdown the components Definition of functionality
What do those first two characters in DDI calls mean?
Definition of functionality

17. Components In WDM wdm.h ks.h Wmi Ke Ob Ex Io Mm Ps Rtl Po Pnp
Hal (platform support)
Zw (magic)
ks.h Ks
Wmi

18. Ke - Kernel Minimal set of items exported here in WDM
Synchronization primitives
Performance counters and timers
Stall and Irq control

19. Ob - Object Manager Very minimal set
Used only for object reference count maintenance

20. Ex - The System Executive
Memory allocations
Interlocked operations
List operations
Work items
There is a better set in the IO manager (Io*)

21. Io - I/O Manager I/O Request Packet (IRP) Handling
The routines that pass Irps
Global locks
Device Object Plumbing
The routines that set device relationships
Work items
Registry access routines
System state notifications
DMA assistance
Interrupt assistance

22. Mm - Memory Manager Virtual to Physical mapping
Physical memory commit/locking
Driver image memory locking
Portable I/O space handling

23. Ps - Process Service
System thread support
Just creation and deletion

24. Rtl - Run-Time Library Bulk memory activity support Unicode support
Conversion support
Unicode to Ansi
Integer to Unicode
Etc.

25. Po - Power Manager Power state change support Power Irp handling
Device idle detection support

26. PnP - Plug And Play Subsystem
There are no Plug and Play decorated routine names
Exists as part of the I/O manager
Actually implemented as an entity in the system

27. Hal - Hardware Abstraction Layer
Device manipulation
I/O port access and usage
Memory mapped device access and usage
Platform abstraction
Component owner of interrupts

28. Zw - Magic Kernel mode map to system APIs Registry access
Open/Close keys
Create/Delete keys
Query values
Minimal file access

29. Ks - Kernel Streaming Separate component on both platforms
Definitions of interfaces located in ks.h
Provides plumbing for streaming data device connections

30. WMI - Windows Management Infrastructure
Similar to Plug and Play as a component of Io
GUID support - wmidata.h
Structure definitions - wmistr.h
Support library definitions - wmilib.h

31. Conclusion Its taken awhile Some of it is simple; Some of it isn’t
Develop driver first under Windows 2000
Test, test, test, on all releases of all supported operating systems

32. WDM Driver Implementation Guide Adrian J
WDM Driver Implementation Guide Adrian J. Oney Software Engineer Windows Core OS Microsoft Corporation

33. Preview
Writing an Windows NT 4.0 skeleton driver required mastery of many concepts
Scheduling
Synchronization
DeviceObjects, DriverObjects
I/O theory (IRP handling, queuing, asynchronous I/O)
Security
Debugging

34. Preview
Writing a WDM driver requires mastery of all of those concepts plus:
Plug and Play
Power Management
WMI (Windows® Management Interface)
Windows 9x/Windows 2000 differences
And don’t forget technology specific issues
Device class specific: Audio, Modem, …
Bus specific: USB, 1394, PCI, …

35. Scheduling Basics WDM presents two types of scheduling
Thread-based scheduling
Kernel support for semaphores, mutexes, event objects
Windows 2000 adds new high-level support for reader/writer operations to WDM
(For instance ExAcquireSharedStarveExclusive)
Interrupt Level-based scheduling
Code running at a higher IRQ Level (IRQL) immediately preempts code running at a lower IRQL
Code runs on same thread, no switching!
The lowest three IRQL’s are scheduling constructs, unrelated to hardware:
PASSIVE_LEVEL, APC_LEVEL, DISPATCH_LEVEL
Multiple processors can each run at a different IRQL!

36. Callbacks PASSIVE_LEVEL (IRQL 0) APC_LEVEL (IRQL 1)
“Work Item”
Queue-able from DISPATCH_LEVEL or lower
Two types, Ex-WorkItems and Io-WorkItems
APC_LEVEL (IRQL 1)
Asynchronous Procedure Call aka “APC”
Thread specific
No WDM function to queue these
I/O Manager queues them to get back into correct process during I/O
DISPATCH_LEVEL (IRQL 2)
Deferred Procedure Call aka “DPC”
Queue-able anytime and anywhere, including ISRs

37. Scheduling Basics PASSIVE_LEVEL (IRQL 0) APC_LEVEL (IRQL 1)
Drivers typically run at this level
Drivers can touch pageable memory
Drivers can do file I/O
Blocking causes a processor to switch threads
APC_LEVEL (IRQL 1)
When switching into a new thread, the processor will run any pending APC’s at APC_LEVEL
Blocking lets other threads run at PASSIVE_LEVEL
Restriction: Drivers cannot use file functions
DISPATCH_LEVEL (IRQL 2)
A processor never switches threads when running driver code at DISPATCH_LEVEL
Restrictions: A driver cannot touch pagable memory, or use file functions

38. IRQs And IRQLs On 8259 PIC CLOCK IDE ISR queues DPC Thread Switches31
Hardware Interrupt 0
Hardware Interrupt 1 …
Hardware Interrupt 14
Hardware Interrupt 15
2 – DISPATCH_LEVEL
1 – APC_LEVEL
0 – PASSIVE_LEVEL
IDE
ISR queues DPC
IRQL 
Thread Switches
DPC executes

39. IO-APIC Example
From an 8-Way server machine down the hall, other machines will be different!
Device IRQ IRQL USB Controller 0xB4 0xA SCSI Controller 0xA3 9 Network Adapter 0xA4 9 SCSI Controller 0x93 8 Network Adapter 0x94 8 SCSI Controller 0x IDE Controller 0x72 6 SCSI Controller 0x73 6 Floppy Controller 0x62 5 Video Controller 0x Com Port 0x51 4 Network Adapter 0x53 4

40. Synchronization PASSIVE_LEVEL (IRQL 0) APC_LEVEL (IRQL 1)
Semaphores
Events
Resources (a kind of Mutex)
APC_LEVEL (IRQL 1)
Fast Mutexes (automatically raises IRQL to APC_LEVEL)
Semaphores, Events, Resources (note: none raise IRQL)
DISPATCH_LEVEL (IRQL 2)
Spinlocks
No reentrant primitives (i.e., mutexes)
Hardware levels (IRQL > 2)
KeSynchronizeExecution

41. Security Attack
A user mode application may choose to “freeze” a thread. User mode does this by queuing an APC to the appropriate thread. Security is compromised if your driver gets frozen holding a sync object
Use synchronization objects that raise to APC_LEVEL or above, or
Move such operations into a system thread, or
Use KeEnterCriticalRegion and KeLeaveCriticalRegion

42. Drivers And Devices Every driver has a DriverObject associated with it
DriverObject(s) represent driver-specific information
Dispatch table
Each driver creates one or more DeviceObject(s) via IoCreateDevice(…)
DeviceObject(s) contain per-device information
DeviceExtension
Name
Flags (e.g., DO_POWER_PAGABLE)
A WDM driver is typically unloaded when all it’s DeviceObject(s) have been deleted

43. Drivers And Devices DRIVER_OBJECT Scanner.sys DRIVER_OBJECT
Toaster.sys
DEVICE_OBJECT
(Scanner #3)
DEVICE_OBJECT
(Toaster #1)
DEVICE_OBJECT
(Scanner #2)
DEVICE_OBJECT
(Scanner #1)

44. Device Stacks Doing an operation often requires multiple drivers
DeviceObjects are arranged into chains called Device Stack
DEVICE_OBJECT
DRIVER_OBJECT
Scanner.sys
DEVICE_OBJECT
(Scanner #2)
DEVICE_OBJECT
DEVICE_OBJECT
(Scanner #1)
DEVICE_OBJECT
DEVICE_OBJECT

45. I/O Request Packets
The OS communicates with drivers by sending I/O Request Packets (IRPs) to a device stack
IRPs are WDM’s solution to asynchronous I/O
IRP
DEVICE_OBJECT
DEVICE_OBJECT
(Scanner #2)
DEVICE_OBJECT
DEVICE_OBJECT

46. Asynchronous I/O
Goal: Let applications queue one or more requests without blocking
Example: Decompressing GIF frames from a CD
Two dedicated application threads is not an optimal solution
Thread switches are expensive
Policy needs to be in the driver stack
Only it knows whether a given request should be handled synchronously or asynchronously

47. Synchronous OS design App Driver A Driver B Driver C Thread Stack
Param for A
Return address to App …
Param for B
Return address to A
Param for C
Return address to B
Thread Stack
App
User Mode
Kernel Mode
Driver A
Driver B
Driver C
Instruction Pointer
Stack Pointer

48. (Contains Status and Stack Pointer)
I/O Request Packets
Param for A
Return address to App …
Param for B
Return address to A
Param for C
Return address to B
Thread Stack
IRP Header
(Contains Status and Stack Pointer)
Param A
Callback for Initator
Param B
Callback for A
Param C
Callback for B

49. I/O Request Packets Thread Stack Concept IRP Stack Concept Stack Frame
Stack Pointer
Subroutine call
Return from subroutine
Return Address/Callback
Return Value
IO_STACK_LOCATION
IoGetCurrentIrpStackLocation (and IoGetNextIrpStackLocation)
IoCallDriver
IoCompleteRequest
Completion routine (IoSetCompletionRoutine)
Irp->IoStatus.Status/Information

50. (Contains Status and Stack Pointer)
I/O Request Packets
Each IRP must be targeted at a specific device stack
IRPs typically have just enough stack locations to traverse the device stack
You must allocate a new IRP if you need to forward the request to another stack
Device A
IRP Header
(Contains Status and Stack Pointer)
Param A
Callback for Initiator
Param B
Callback for A
Param C
Callback for B 3
Device B 2
Device C 1

51. I/O Request Packets IRP Header Thread UserIoStatus UserEvent
Stack Pointer
IoStatus
CancelRoutine
Major Code
Minor Code
Param
Completion Routine
Completion Context
IRP_MJ_
IRP_MN_ …
func(…)
PVOID
IRP_MJ_CREATE
IRP_MJ_CLOSE
IRP_MJ_READ
IRP_MJ_WRITE
IRP_MJ_DEVICE_CONTROL
IRP_MJ_PNP
IRP_MJ_POWER
DRIVER_OBJECT
Dispatch Table
DEVICE_OBJECT

52. Callers completion routine
I/O Request Packets
What do I return from my dispatch routine?
Return same value completion routine would see, else return STATUS_PENDING
Caller on thread stack
Callers completion routine
status = IoCallDriver(...); status = Irp->IoStatus.Status;

53. I/O Request Packets
Correct value returned from dispatch handler: Irp->IoStatus.Status = STATUS_UNSUCCESSFUL; IoCompleteRequest( Irp, IO_NO_INCREMENT ); return STATUS_UNSUCCESSFUL; Irp->IoStatus.Status = STATUS_SUCCESS; IoSkipCurrentIrpStackLocation( Irp ); return IoCallDriver( deviceBeneathMe, Irp );
Incorrect value returned from dispatch handler:
Irp->IoStatus.Status = STATUS_SUCCESS; IoSkipCurrentIrpStackLocation( Irp ); IoCallDriver( deviceBeneathMe, Irp ); return STATUS_SUCCESS; // Be extra careful when changing status in completion routines!

54. The Two Types Of I/O Buffered I/O Direct I/O
Driver writes into Irp->AssociatedIrp.SystemBuffer
OS queues an APC in the requesting process context where it performs a copy
Direct I/O
Doesn’t require a copy
Memory pages are locked during the duration of the operation
Pages are described by the IRPs Memory Descriptor List (Irp->MdlAddress)
Driver use DMA functions or get a kernel address via MmGetSystemAddressForMdlSafe(Irp->MdlAddress)

55. WDM Device Stacks
A WDM driver stack can contain several different kinds of device objects:
Functional Device Object ( “FDO” )
Physical Device Object (“PDO”)
Filters
The stack and the OS data associated with it is called a “DevNode”
Upper Class Filters
Upper Device Filters
FDO Functional Device Object
Lower Class Filters
Lower Device Filters
PDO Physical Device Object
Device Node (“DevNode”)

56. FDO Functional Device Object PDO Physical Device Object
WDM Device Stacks
I/O IRPs are typically handled by the FDO
Create, Close, Read, Write, etc.
Drivers must fail any such IRP explicitly if it’s not handled
PnP and Power IRPs traverse the entire stack except if there is an error
Drivers do not modify these IRPs if they do not implement the request
WMI IRPs are targeted at specific device objects in the stack
Drivers do not modify WMI IRPs if they do not implement WMI
IRP
Upper Class Filters
Upper Device Filters
FDO Functional Device Object
Lower Class Filters
Lower Device Filters
PDO Physical Device Object
DevNode

57. FDO Functional Device Object PDO Physical Device Object
WDM Device Stacks
A PDO is created by the bus driver
This is done in response to an OS enumeration request
Only the PDO has a name!
More on this later
FDO’s and Filters are created in AddDevice routines
Drivers do not find their hardware, rather their hardware finds them
Plug and Play passes the PDO to AddDevice
Drivers attach new device objects to the stack via IoAttachDeviceToDeviceStack
Upper Class Filters
Upper Device Filters
FDO Functional Device Object
Lower Class Filters
Lower Device Filters
PDO Physical Device Object
DevNode

58. PNP Manager Registry Search INF Files4
[Version]
Signature =
Provider
Search INF Files
PNP Manager 3
IRP
Information
IRP_MN_QUERY_ID 2
IRP_MN_QUERY_DEVICE_RELATIONS
IRP
Information 5
Call Class Installers and Co-Installers
USB Floppy DevNode
Upper Filters
FDO
USBFLOP.SYS
Registry
Lower Filters 6
Load drivers
PDO
USBHUB.SYS
FDO
USBHUB.SYS 1
IoInvalidateDeviceRelations
PDO
USB Hub DevNode

59. Plug And Play
The Plug and Play Manager queries the stack to get a list of all possible resource solutions:
The PDO responds to IRP_MN_QUERY_RESOURCE_REQUIREMENTS
The FDO can adjust these requirements by responding to IRP_MN_FILTER_RESOURCE_REQUIREMENTS
The Plug and Play Manager sends the best resource settings in IRP_MN_START_DEVICE
The card is configured to use the “Raw’ resource set
The driver communicates with the card via the “Translated” resource set

60. Plug And Play
FDO’s must respond to the following Plug and Play events:
“Remove” events occur when a device is removed or disabled
IRP_MN_REMOVE_DEVICE
IRP_MN_SURPRISE_REMOVAL
IRP_MN_QUERY_REMOVE_DEVICE
IRP_MN_CANCEL_REMOVE_DEVICE
“Stop” events occur when a device is to be paused for resource rebalancing
IRP_MN_QUERY_STOP_DEVICE
IRP_MN_STOP_DEVICE
IRP_MN_CANCEL_STOP_DEVICE
Other Plug and Play events FDO’s typically respond to:
IRP_MN_START_DEVICE (We hope)
IRP_MN_QUERY_CAPABILITIES

61. Plug And Play PDO’s must respond to even more messages:
“Who” are you, “What” are you?
IRP_MN_QUERY_ID
IRP_MN_QUERY_DEVICE_TEXT
“Where are you, and where can you go today?”
IRP_MN_QUERY_RESOURCES
IRP_MN_QUERY_RESOURCE_REQUIREMENTS
Settings, capabilities, and location:
IRP_MN_QUERY_CAPABILITIES
IRP_MN_QUERY_BUS_INFORMATION
Misc.
IRP_MN_QUERY_DEVICE_RELATIONS (TargetRelations)

62. “Finding” Plug And Play Devices
Applications often need a list of devices to manipulate or display to the user
Printers, Scanners, etc
Using “well known names” (i.e., LptX) doesn’t work well in a Plug and Play environment
Applications often need a list of devices that share a given property, and properties can be hierarchical
(E.g., all storage devices, just CDROMs, just Zip drives, etc.)
WDM drivers expose one or more “Interfaces”, identified via GUID
Note: Only started devices can expose interfaces

63. Interfaces
Drivers register support for a given Interface by calling IoRegisterDeviceInterface
Drivers dynamically enable and disable an interface via IoSetDeviceInterfaceState
IoSetDeviceInterfaceState creates a symbolic link so that user mode applications can communicate with the device
More on this later
Applications enumerate devices by passing an interface GUID to various SetupApi functions

64. FDO Functional Device Object PDO Physical Device Object
Kernel mode security
User mode can attempt to open a device with Read, Write, and Execute privileges
By default, all users get full access to a WDM device stack
Security checks are done at Create/Open time
Access to a device can be restricted via INF
Search DDK for “INF AddReg”, or stay tuned…
Upper Class Filters
Upper Device Filters
FDO Functional Device Object
Lower Class Filters
Lower Device Filters
PDO Physical Device Object

65. Kernel Mode Security Allow All System (Example: System only access)
[MyDevice.NTx86] CopyFiles = ... [MyDevice.NTx86.Services] AddService = ... [MyDevice.NTx86.HW] AddReg = MyDevice.Security [MyDevice.Security] HKR,,DeviceCharacteristics,0x10001,0x100 HKR,,Security,,”security-descriptor-string”
"D:P( ;; ;;; ) (...)"
"D:P(A;;GA;;;SY)"
A: Allow D: Deny
GA: All GR: Read GW: Write
SY: System LA: Local Administrator PU: Power user WD: World
Allow
All
System
(Example: System only access)

66. FDO Functional Device Object PDO Physical Device Object
Security Attacks
Security constraints are applied to named device objects
In a WDM stack, only the PDO should be named
If another device is named, it might compromise system security
A device doesn’t have to expose a symbolic link to be opened!
Be sure to pass in FILE_DEVICE_SECURE_OPEN when creating PDO’s
Upper Class Filters
Upper Device Filters
FDO Functional Device Object
Lower Class Filters
Lower Device Filters
PDO Physical Device Object

67. IOCTL Security
Method
Function
Access
Device Number 31 15 13 2
Drivers encode the security requirements of Device IOCTLs in the 32bit code itself
The Access mask can specify one of four different privilege levels:
Openable
Opened with read access
Opened with write access
Opened with both read and write access
The IO Manager prevents applications from forming IOCTL codes their privileges don’t allow

68. Security Attacks
Method
Function
Access
Device Number 31 15 13 2
Drivers should always check the full 32bit Ioctl code!
Masking out the Access bits lets lower privileged Ioctl’s succeed
Do not use the IoGetFunctionCodeFromCtlCode macro
Drivers should always check the buffer size of incoming Ioctl’s
Malicious applications can attempt to crash the system via malformed requests
Do not implement IOCTLs that allow an application to read or write any piece of virtual or physical memory
Don’t ship with debugging IOCTLs enabled
Don’t pass back “pointers” as handles

69. Power Management
To implement power management, a driver needs code to:
Save and restore the state of its hardware
Disable and enable the device
Queue incoming requests
Convert System states to Device states
A driver must not touch it’s hardware while it’s device is off
Memory and I/O typically return 0xFFFFFFFF when off, fooling badly written ISR’s

70. System States S0: Working S1: Standby S2: Standby S3: Standby
Machine is fully powered and responsive
S1: Standby
Processor and bus clocks are off, recovery time typically two seconds
S2: Standby
Greater power conservation, recovery time more than two seconds
S3: Standby
Typically only memory remains powered
S4: Hibernation
Machine is off, memory is written to persistent storage
S5: Off

71. Device States D0 D1 D2 D3: Off Hardware is fully powered
Less power consumption than D0
Transition to fully powered happens quickly
Driver cannot access device until powered up D2
Less power consumption than D1
Longer power-up time than D1
D3: Off
Device is completely off (inaccessable)

72. Converting S IRPs To D IRPs
The WDM Power Manager sends S IRPs:
IRP_MN_QUERY_POWER
IRP_MN_SET_POWER
Each device stack has a “Power Policy Owner” who converts S IRPs to D IRPs
The Power Policy Owner is typically the FDO
The mapping comes from the S  D array stored in the IRP_MN_QUERY_CAPABILITIES structure
Each entry calls out the lightest possible D state for a given S state
Mappings can be rounded down (deeper)
The Power Policy Owner then uses PoRequestPowerIrp to request the appropriate D IRP
The conversion code is complicated, but most drivers can use the boilerplate code in the WDM DDK

73. System State S0 – Working
Modem
HDD
CDROM
Net Card D3 D3 D3 D3 D2 D2 D2 D2 D1 D1 D1 D1 D0 D0 D0 C0 D0
PCI Bus S0  D0
PCI.SYS
ACPI.SYS
PCIIDE.SYS
SCSI Card
S0  D0
SCSIPORT.SYS
IDE Controller
S0  D0
Net Card
S0  D0
NDIS.SYS
ACPI.SYS
ACPI.SYS
ACPI.SYS
PCI.SYS
PCI.SYS
PCI.SYS
IDE Channel S0  D0
ATAPI.SYS
CDROM
S0  D0
CDROM.SYS
PCIIDE.SYS
SCSIPORT.SYS
HDD
S0  D0
DISK.SYS
S0  D0
ATAPI.SYS

74. System State S1 – Standby
Modem
HDD
CDROM
Net Card D3 D3 D3 D3 D2 D2 D2 D2 D1 D1 D1 D1 D0 D0 D0 C0 D0
PCI Bus S1  D1
PCI.SYS
ACPI.SYS
PCIIDE.SYS
SCSI Card
S1  D3
SCSIPORT.SYS
IDE Controller
S1  D1
Net Card
S1  D3
NDIS.SYS
ACPI.SYS
ACPI.SYS
ACPI.SYS
PCI.SYS
PCI.SYS
PCI.SYS
IDE Channel S1  D1
ATAPI.SYS
CDROM
S1  D3
CDROM.SYS
PCIIDE.SYS
SCSIPORT.SYS
HDD
S1  D1
DISK.SYS
S1  D?
ATAPI.SYS

75. System State S3 – Standby
Modem
HDD
CDROM
Net Card D3 D3 D3 D3 D2 D2 D2 D2 D1 D1 D1 D1 D0 D0 D0 C0 D0
PCI Bus S3  D3
PCI.SYS
ACPI.SYS
PCIIDE.SYS
SCSI Card
S3  D3
SCSIPORT.SYS
IDE Controller
S3  D3
Net Card
S3  D3
NDIS.SYS
ACPI.SYS
ACPI.SYS
ACPI.SYS
PCI.SYS
PCI.SYS
PCI.SYS
IDE Channel S3  D3
ATAPI.SYS
CDROM
S3  D3
CDROM.SYS
PCIIDE.SYS
SCSIPORT.SYS
HDD
S3  D3
DISK.SYS
S3  D?
ATAPI.SYS

76. System State S4 – Hibernate
Modem
HDD
CDROM
Net Card D3 D3 D3 D3 D2 D2 D2 D2 D1 D1 D1 D1 D0 D0 D0 C0 D0
PCI Bus S4  D3
PCI.SYS
ACPI.SYS
PCIIDE.SYS
SCSI Card
S4  D3
SCSIPORT.SYS
IDE Controller
S4  D3
Net Card
S4  D3
NDIS.SYS
ACPI.SYS
ACPI.SYS
ACPI.SYS
PCI.SYS
PCI.SYS
PCI.SYS
IDE Channel S4  D3
ATAPI.SYS
CDROM
S4  D3
CDROM.SYS
PCIIDE.SYS
SCSIPORT.SYS
HDD
S4  D3
DISK.SYS
S4  D3
ATAPI.SYS

77. System State S5 – Off S5  D3 PCI Bus S5  D3 SCSI Card Net Card
Modem
HDD
CDROM
Net Card D3 D3 D3 D3 D2 D2 D2 D2 D1 D1 D1 D1 D0 D0 D0 C0 D0
PCI Bus S5  D3
PCI.SYS
ACPI.SYS
PCIIDE.SYS
SCSI Card
S5  D3
SCSIPORT.SYS
IDE Controller
S5  D3
Net Card
S5  D3
NDIS.SYS
ACPI.SYS
ACPI.SYS
ACPI.SYS
PCI.SYS
PCI.SYS
PCI.SYS
IDE Channel S5  D3
ATAPI.SYS
CDROM
S5  D3
CDROM.SYS
PCIIDE.SYS
SCSIPORT.SYS
HDD
S5  D3
DISK.SYS
S5  D3
ATAPI.SYS

78. Converting S IRPs To D IRPs
( Simplified from Toaster Sample in the WDM DDK )
NTSTATUS
ToasterDispatchPower( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp)
{ PIO_STACK_LOCATION stackLocation; // // Not shown: Are we deleted? If so, fail IRP. // Not shown: Are we started? If not, pass on IRP untouched. //
stackLocation = IoGetCurrentIrpStackLocation( Irp ); switch(stackLocation->MinorFunction) {
case IRP_MN_QUERY_POWER:
return ToasterQueryPowerState( DeviceObject, Irp ); case IRP_MN_SET_POWER:
return ToasterSetPowerState( DeviceObject, Irp );
default:
// Not shown: default logic }

79. Converting S IRPs To D IRPs
NTSTATUS
ToasterQueryPowerState( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp ) {
PIO_STACK_LOCATION stackLocation; if (stackLocation->Parameters.Power.Type == SystemPowerState) {
return HandleSystemPowerIrp( DeviceObject, Irp ); }
return HandleDeviceQueryPower( DeviceObject, Irp ); }
S  D routine

80. Converting S IRPs To D IRPs
NTSTATUS
ToasterSetPowerState( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp ) {
PIO_STACK_LOCATION stackLocation; if (stackLocation->Parameters.Power.Type == SystemPowerState) {
return HandleSystemPowerIrp( DeviceObject, Irp ); }
return HandleDeviceSetPower( DeviceObject, Irp ); }
S  D routine

81. Converting S IRPs To D IRPs
NTSTATUS
HandleSystemPowerIrp( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp ) { //
// Forward IRP *asynchronously*, catch it on way up
IoMarkIrpPending( Irp );
IoCopyCurrentIrpStackLocationToNext( Irp );
IoSetCompletionRoutine( Irp,
(PIO_COMPLETION_ROUTINE) OnFinishSystemPowerUp, NULL, TRUE, TRUE, TRUE);
PoCallDriver( fdoData->NextLowerDriver, Irp );
return STATUS_PENDING; }
S-IRP
PPO

82. Converting S IRPs To D IRPs
NTSTATUS
OnFinishSystemPowerUp(
IN PDEVICE_OBJECT Fdo,
IN PIRP Irp,
IN PVOID NotUsed ) {
NTSTATUS status = Irp->IoStatus.Status;
if (!NT_SUCCESS(status)) {
PoStartNextPowerIrp(Irp);
return STATUS_SUCCESS; }
QueueCorrespondingDeviceIrp( Irp, Fdo );
return STATUS_MORE_PROCESSING_REQUIRED;
PPO
S-IRP

83. Converting S IRPs To D IRPs
VOID
QueueCorrespondingDeviceIrp( IN PIRP SIrp, IN PDEVICE_OBJECT DeviceObject ) {
POWER_STATE dState;
PFDO_DATA fdoData = (PFDO_DATA) DeviceObject->DeviceExtension;
PIO_STACK_LOCATION stack = IoGetCurrentIrpStackLocation(SIrp);
SYSTEM_POWER_STATE sState = stack->Power.State.SystemState;
if ((sState == PowerSystemWorking) || (fdoData->ArmedForWake)) {
dState.DeviceState = fdoData->DeviceCaps.DeviceState[sState];
} else {
dState.DeviceState = PowerDeviceD3; }
status = PoRequestPowerIrp(
fdoData->UnderlyingPDO,
stack->MinorFunction,
dState, OnPowerRequestComplete,
SIrp, NULL);
// Not shown: Handle case where PoRequestPowerIrp fails
D-IRP
PPO
S-IRP

84. Converting S IRPs To D IRPs
VOID
OnPowerRequestComplete(
IN PDEVICE_OBJECT DeviceObject,
IN UCHAR MinorFunction,
IN POWER_STATE State,
IN PVOID PowerContext,
IN PIO_STATUS_BLOCK IoStatus ) {
PIRP sIrp = (PIRP) PowerContext; //
// Copy status from D IRP to S IRP
sIrp->IoStatus.Status = IoStatus->Status;
PoStartNextPowerIrp( sIrp );
IoCompleteRequest( sIrp, IO_NO_INCREMENT ); }
D-IRP
PPO
S-IRP

85. Converting S IRPs To D IRPs
VOID
OnPowerRequestComplete(
IN PDEVICE_OBJECT DeviceObject,
IN UCHAR MinorFunction,
IN POWER_STATE State,
IN PVOID PowerContext,
IN PIO_STATUS_BLOCK IoStatus ) {
PIRP sIrp = (PIRP) PowerContext; //
// Copy status from D IRP to S IRP
sIrp->IoStatus.Status = IoStatus->Status;
PoStartNextPowerIrp( sIrp );
IoCompleteRequest( sIrp, IO_NO_INCREMENT ); }
S-IRP
PPO

86. Power Management Gotcha’s
Drivers cannot block a thread and wait for a power IRP to complete on Windows 2000
S  D state mapping for non-power manageable PCI devices may contain invalid D states on Windows 2000
Drivers cannot safely complete power IRPs at DISPATCH_LEVEL on Windows 9x
Drivers cannot safely do “idle time” power management on Windows 9x
PCI supports two types of D3 which WDM doesn’t distinguish

87. WDM And Hardware – DSP Bad design: Correct design:
OS loads DSP driver against “DSP device”
Driver uploads software into volatile DSP RAM
“DSP device” disappears from bus
New device appears in it’s place
Problem: What happens when the device is turned off?
Correct design:
OS loads DSP bus driver against “DSP device”
DSP bus driver uploads DSP software into volatile DSP RAM
Bus driver exposes new functionality by creating a child device
Bus driver reprograms DSP when appropriate