|
|
 |
|
|
|
Programming the Microsoft® Windows® Driver Model, Second Edition
|
|
|
Author
|
|
Walter Oney
|
|
|
Pages
|
880
|
|
Disk
|
1 Companion CD(s)
|
|
Level
|
All Levels
|
|
Published
|
12/16/2002
|
|
ISBN
|
9780735618039
|
|
Price
|
$59.99
To see this book's discounted price, select a reseller below.
|
|
|
|
|
|
|
|
|
Index
Symbols and Numbers
\?? directory, 64, 65
1394 devices, device identifiers for, 731-32
A
AbortRequests function, 322, 341-42
access control lists, 69
accessing files, 147-51
ACLs. See access control lists
ACPI. See Advanced Configuration and Power Interface specification
ACPI Source Language (ASL), 444
ACPI.SYS driver, 776
AcquireLock routine, 267
adapter objects, 398
AdapterControl routine, 21, 407-8, 411-13
Add Hardware Wizard, 712, 713
AddDevice routine
callback in HIDCLASS minidrivers, 648-49
complete example, 86
creating device objects, 51, 60, 61-63, 708, 780, 781
device initialization, 80-85
driver loading order, 40-41
for filter drivers, 780-83
flags for managing power, 460-61
for function drivers, 60-86
IoAttachDeviceToDeviceStack function, 60, 81, 84-85, 708, 780, 781, 782
IoCreateDevice function, 51, 60, 61-63, 708, 780, 781
overview, 21, 22, 25, 60
PnP Manager and, 34, 313
AddReg directive, 718-20, 723
address space. See virtual address space
ADDRESS_AND_SIZE_TO_SPAN_PAGES macro, 110
addressing data buffers, 367-73
AdjustDeviceCapabilities function, 443
Advanced Configuration and Power Interface (ACPI) specification, 427, 444
AlignmentRequirement field, 54, 82-83
AllocateAdapterChannel routine, 404-6, 415
AllocateFrom functions, 132-33
AllowRequests function, 322, 342
ANSI_STRING structure, 134, 135, 137-38
APC_LEVEL IRQL, 167, 168, 199, 204, 282, 305
APCs. See asynchronous procedure calls
application collections, 641
applications
vs. device drivers, 22-24
launching using RunOnce, 755-56
arbitrary thread context, 26, 109, 178
AreRequestsBeingAborted function, 322, 341, 395
ASSERT macro, 153-54, 157, 171, 185, 623
AssociatedIrp field, 217
asynchronous IOCTLs, 501-2
asynchronous IRPs
cancellation and completion routines, 637-38
cancelling, 284-86
creating, 225-26
asynchronous procedure calls (APCs). See also APC_LEVEL IRQL
I/O requests and, 199-200
kernel mode, 198-99
overview, 198
thread alerts and, 198-201
user mode, 198, 199
ATAPI.SYS driver, 775
AttachedDevice field, 42
AUTOLAUNCH example, 755
B
bandwidth, reserving, 618-22
BASETSD.H file, 49
batteries, writing minidrivers for, 14
binary portability, 15
blue screen of death, 106
buffer alignment mask, 82-83
buffered method, for accessing data buffers, 367, 368-69, 487
buffers. See data buffers
bug checks, 106-7
BUGCHECK example, 107
bulk pipes
LOOPBACK example, 605-13
managing pipes, 604-13
USB42 example, 604-5
bulk transfers
defined, 566
endpoint maximum values, 567
managing pipes, 604-13
overview, 575-77
bus, defined, 31
bus drivers
child devices and, 32-33, 536
configuration, 593-604
defined, 30, 31
vs. filter drivers, 30
as function drivers, 774
vs. function drivers, 30
HIDUSB.SYS drivers as, 776
initiating requests, 590-93
IRP routing and, 41
managing bulk transfer pipes, 604-13
managing interrupt pipes, 613-14
overview, 589-90
PDOs and, 30, 32-33, 42, 43, 44, 45
Plug and Play devices and, 31, 32-33
as power policy owner, 426
role in power management, 427
role in reserving bandwidth, 618-22
sending IRPs to, 32-34
bus filters, 795-96
bus transactions, 568-70
bus-master device example, 421-23
BusRelations queries, 796, 799
BYTE_OFFSET macro, 109
BYTES_TO_PAGES macro, 109
C
CacheControlRequest routine, 501-2
callbacks
AddDevice, 648-49
cancel-safe queues in, 266-68
DispatchPnP, 649-51
DriverUnload, 649
HIDCLASS minidrivers, 647-55
queuing work items, 689-91
CancelIo function, 269
CancelIrql field, 218
cancelling I/O requests
IRP cancellation process, 272-88
main vs. subsidiary, 628-34
overview, 269-70
role of DEVQUEUE, 273-80
synchronization issues, 270-72
cancelling WAIT_WAKE requests, 465-67
CancelRequest function, 322. See also cancelling I/O requests
CancelRoutine field, 218
cancel-safe queues
in callback routines, 266-68
as cleanup tool, 293
in dispatch routines, 265-66
initializing, 265
overview, 263-65
parking IRPs on, 268-69
CCoinstaller class, 749
CCoinstallerDialog class, 750
CDeviceList class, 77, 78-79
CDROM.SYS driver, 774, 775, 776
changers (device type), standard data blocks, 533
CheckBusyAndStall function, 322, 324, 338
checked build environment, 153, 154
child devices
bus drivers and, 32-33, 536
creating PDOs for, 536-38
handling resources, 558
MULTIFUNC example, 538
PnP Manager and, 32-33, 541-42
system wake-up feature, 556-57
CHKINF tool, 734-35, 761
class drivers
defined, 11, 774
as filter drivers, 774, 775
minidrivers and, 13
relationship to minidrivers, 29
class filters
installing, 787-90
Windows 98/Me issues, 800
class key, registry
accessing, 705
defined, 698
order of driver loading and, 38-39
overview, 701-2
user-mode interface, 707
classes, WMI. See also device classes
defined, 509
instance naming, 525-26
mapping to C structures, 511-12
cleanup handlers. See IRP_MJ_CLEANUP function code
CleanupRequests function, 322, 341
CLEAR_FEATURE standard device request, 573, 574
client-side installs, defined, 744
CM_PARTIAL_RESOURCE_DESCRIPTOR data structure, 364
CM_PARTIAL_RESOURCE_LIST data structure, 315, 364
CM_RESOURCE_LIST data structure, 315
CM_RESOURCE_PORT_IO flag, 376, 377
code_seg pragma, 113
co-installer DLLs, 748-52, 770
COINSTALLER example, 749-52
collections. See HID collections
Command Description Blocks (CDBs), 774
common buffers
allocating, 418-19
bus-master DMA and, 420
cautions about using, 420
overview, 418
releasing, 421
slave DMA and, 419-20
Common Information Model (CIM), 508
CompleteCanceledIrp function, 268
CompleteRequest function, 105, 234
completion routines
how they get called, 245-47
IoSetCompletionRoutine function, 242-45
LOOPBACK example, 608-10
PnP complication, 254-56
problem of IoMarkIrpPending function, 247-54
return values, 244-45
in USBISO example, 627-28
WAIT_WAKE requests, 464-67
composite devices, 595, 635-38, 640
CONFIGMG.VXD file, 158, 770
configuration descriptors
list of attribute bits, 585
overview, 583-85
reading, 595-97
Configuration Manager, 158, 593-95
consumers, WMI, 508-9, 516
CONTAINING_RECORD macro, 125, 212, 266
Context field, 222
control requests
configuring, 593-604
for controlling features, 614-15
for determining device status, 616-17
initiating, 590-93
list of types, 573-74
control transfers, 566, 567, 570-75
counters. See kernel semaphores
CreateEvent function, 499
cross-platform incompatibilities, 801-10
CTL_CODE proprocessor macro, 483-85
custom PnP notifications, 359-60
customizing setup, 743-56
D
data blocks
multiple instances, 524
role of statistics gathering, 526-28
standardized, 531-33
data buffers
addressing, 367-73
methods for IOCTL requests, 487-92
specifying access method, 368-73
ways to address, 367-73
data queries, control flow diagram, 519
data streaming, 622-25
data transfer
allowable maximum packet sizes, 567
bulk type, 566, 567, 575-77
control type, 566, 567, 570-75
information packaging, 568-69
interrupt type, 566, 567, 577-78
isochronous type, 566, 567, 578-79
overview, 566-67
USB 1.1 vs. USB 2.0, 567
data_seg pragma, 112
DbgPrint function, 153
DbgView tool, 351
DBT_DEVICEARRIVAL notification, 354
DBT_DEVICEQUERYREMOVE notification, 349
DBT_DEVICEREMOVECOMPLETE notification, 349, 353
DBT_QUERYREMOVEDEVICE notification, 352, 353
deadlocks, 173, 203, 205
debugging
INF files, 736-37
power management code, 434-36
simplifying, 152-57
deferred procedure calls (DPCs)
custom objects, 389
DpcForIsr routine, 241-42
overview, 21, 25, 82, 385-87
PCI42 example, 396
role in servicing device interrupts, 385-89
routine, 241-42
scheduling, 387-88
setting importance level, 388
triggering from notification timers, 193-94
DefineDosDevice function, 67-68
descriptors
configuration type, 583-85, 595-97
device qualifier type, 583
device type, 580-83
endpoint type, 586-88
interface type, 585-86
list of types, 579
overview, 579
string type, 588-89
DestroyContextStructure function, 631-32, 633, 634
DEVCON example, 754
DEVCTL tool, 494
DEVEQUE object
aborting requests, 341-42
awaiting current IRP, 340
full IRP_MJ_PNP implementation, 338-42
list of service routines, 322
when to use, 322
DEVGUID.H file, 709
Device Class Definition for Human Input Devices specification, 639
Device Class Definition for Physical Interface Devices specification, 639
device classes
defining in INF file, 737-38
HID devices, 639-71
power requirements, 427-28
property page provider, 738-43
Unknown class, 736
writing minidrivers for, 13-14
device descriptors, 580-83
device drivers. See drivers
device extension
defining structures for multifunction drivers, 537
defining structures for power management, 436-37
initializing, 80-82
device filters, installing, 790-91
device identifiers
for 1394 devices, 731-32
for generic devices, 732
for IDE devices, 729-30
in INF files, 726-32
for ISAPNP devices, 730
for PCI devices, 726-27
for PCMCIA devices, 727-28
for SCSI devices, 728-29
for USB devices, 730-31
device interfaces
enumerating, 77-80
IoRegisterDeviceInterface function, 75, 76
overview, 73-74
registering, 75-76
role of GUIDs, 73-74
device IRQL (DIRQL), 167, 212
device key, registry, 34, 38-39
Device Manager
Power Management tab, 462-63, 469
relationship to registry, 699-701
USB host controller property page, 621
device objects. See also hardware
configuring, 363-67
creating, 61-63
creating with IoCreateDevice function, 51, 60, 61-63, 708, 780
deleting, 318-20
determining status, 616-17
flags for managing power, 460-61
initializing, 80-85
interrupt-driven example, 389-97
issues in naming, 63-80
locating, 228-32
naming, 71, 72, 230
NextDevice field, 51
optimizing power state changes, 474
overriding property settings, 708-9
overview, 51-54
permission to stop, 323-25
polling, 683
powering off when idle, 469-73
preventing premature removal, 328-31
reading and writing data, 363-423
removing, 326-37
setting and clearing features, 614-15
starting, 312-16, 323, 363
stopping, 316-17, 323-26
synchronizing removal, 328-31
usage notifications, 344-47
wake-up features, 461-69
device polling, 683, 686-89
device power IRPs
flow when decreasing power, 451
flow when increasing power, 450
higher state, 455
overview, 449-51
requesting in Windows 98/Me, 476
setting higher power state, 451-55
setting lower power state, 456-59
submitting requests, 445-46
vs. system power IRPs, 449
device qualifier descriptors, 583
device tree, visualizing, 45, 46
DEVICE_CAPABILITIES structure, 441-42
DEVICE_DESCRIPTION structure, 401, 402, 403-4, 416, 417
DeviceIoControl function
alternatives, 479
asynchronous calls, 482-83
calling, 481-83
defining I/O control codes, 483-85
input and output buffers, 480-81
overview, 9, 64, 479, 480-81
PNPMON example, 358
prototype, 480
synchronous calls, 481-82
in USB42 bulk transfer example, 604
WDMWIZ.AWX and, 814
DEVICELIST.CPP file, 77
DEVICELIST.H file, 77
DEVICE_OBJECT data structure, 30, 51
DeviceObject field, 50, 221, 245
DevicePropertyClassGuid property, 705
DevicePropertyCompatibleIDs property, 705
DevicePropertyDeviceDescription property, 705
DevicePropertyDriverKeyName property, 706
DevicePropertyFriendlyName property, 706
DevicePropertyHardwareId property, 705
DevicePropertyManufacturer property, 706
DEVICE_RELATIONS structure, 541-42
DEVICE_REMOTE_WAKE-UP standard device request, 574
DeviceUsageTypeDumpFile usage type, 347
DeviceUsageTypeHibernation usage type, 347
DeviceUsageTypePaging usage type, 346
DEVINTERFACE example, 80
DEVPROP example, 706
DEVQUEUE object
cancelling IRPs, 279-80
cancel-safe queuing, 276-79
as cleanup tool, 291-92
handling cancellation, 273-80
implementing, 274-76
initializing, 273-74
IRP queuing and, 386-87
overview, 260-63
PCI42 example, 395
restarting IRP queues, 339-40
stalling IRP queue, 338
state transitions, 320-42
unstalling IRP queues, 339-40
DEVVIEW utility, 45, 63, 64
DIF codes, 745-48
DIF_ADDPROPERTYPAGE_ADVANCED function code, 747
DIF_ALLOW_INSTALL function code, 746
DIF_DESTROYPRIVATEDATA function code, 746, 747, 748
DIF_INSTALLDEVICE function code, 746, 747
DIF_INSTALLDEVICEFILES function code, 746
DIF_INSTALLINTERFACES function code, 746, 747
DIF_NEWDEVICEWIZARD_FINISHINSTALL function code, 746, 747
DIF_POWERMESSAGEWAKE function code, 747
DIF_PROPERTYCHANGE function code, 747, 748
DIF_REGISTER_COINSTALLERS function code, 746, 747
DIF_REGISTERDEVICE function code, 746, 747
DIF_SELECTBESTCOMPATDRV function code, 746
digital certificates, 17, 770
direct memory access (DMA)
IoGetDmaAdapter function, 367, 398, 401, 402-4, 416, 418
list of DmaOperations function pointers, 398
overview, 21, 397-98
packet-based transfers, 401-17
performing transfers, 401-17
role of common buffers in transfers, 418-21
role of data buffers, 82-83
transfer model, 397-98
transfer strategies, 399-400
transfers using scatter/gather lists, 410-15
transfers using system controller, 415-17
Windows XP, 397-98
direct method, for accessing data buffers, 367, 370-72, 487
direct-call interfaces
exporting, 552-53
identifying, 550
locating and using, 550-52
overview, 549-50
DIRQL (device IRQL), 167, 212
disk and tape storage devices
driver stacks, 774
driver usage notifications, 344-47
drivers for mass storage devices, 16, 87
function drivers, 774
standard data blocks, 531-32
DISKPERF driver, 778
DISK.SYS driver, 774, 775, 776
dispatch routines. See also DispatchPnP routine
DispatchAny, 783-84
DispatchPower, 111, 651-53, 784
forwarding to, 226-32
overview, 232-39
DispatchAny function, 783-84
DispatchClose function, 473
DispatchControl function, 486-87
DispatchCreate function, 473
dispatcher objects. See kernel dispatcher objects
DispatchInternalControl routine
callback in HIDCLASS minidrive, 653-55
common features of control operations, 654
skeleton code, 654-55
DISPATCH_LEVEL IRQL, 165, 166-67, 168, 169, 170
DispatchPnP routine
callback in HIDCLASS minidrivers, 649-51
code for HIDFAKE example, 650-51
for filter drivers, 784-87
for IRP_MJ_PNP, 310-11
synchronization problem, 162-64
DispatchPower function, 111, 651-53, 784
divisor latch, 384
DMA. See direct memory access
Dma resource type, 367
DmaOperations structure, 398
DO_BUFFERED_IO flag, 83, 301, 369, 372, 393, 781
DO_DEVICE_INITIALIZING flag, 85
DO_DIRECT_IO flag, 83, 301, 370, 372, 401, 606, 781
DO_POWER_INRUSH flag, 84, 460-61, 782
DO_POWER_PAGABLE flag, 84, 346, 432, 460, 461, 475, 781, 786
\DosDevices directory, 72
DpcForIsr routine, 241-42
DPCs. See deferred procedure calls
driver key, registry
accessing, 705
defined, 698
initializing, 722
overview, 703
user-mode interface, 707
driver layering, 28-30, 41
driver objects
DeviceObject field, 50
DriverExtension field, 50
DriverStartIo field, 51, 57
DriverUnload field, 51
FastIoDispatch field, 51
HardwareDatabase field, 50
illustrated, 47, 48
list of kernel-mode type names, 48-49
MajorFunction field, 51
overview, 47-51
driver packages
creating, 763-69
signed, 732-34, 743, 752
value-added software and, 743, 753
Windows 98/Me issues, 770
driver stacks. See also IO_STACK_LOCATION data structure
for disk and tape storage devices, 774-76
for DVD-ROM drives, 775
IoAttachDeviceToDeviceStack function, 84-85
for joysticks, 799
location, 219-22
overview, 41, 42
passing IRPs, 236-38
for PS/2 mice, 776
for SCSI hard disks, 775
for serial mice, 777
for USB mice, 776
Driver Verifier
Deadlock Detection option, 205
heap allocation and, 117, 120, 121
I/O verification and, 222
lookaside lists and, 132
overview, 154-57
DriverEntry routine
for filter drivers, 779-80
for function drivers, 54-59
for HIDCLASS minidrivers, 646-47
moving to WDM driver INIT section, 113-14
overview, 21, 22, 25
Windows 98/Me issues, 87
Windows NT and, 35
DRIVER_OBJECT data structure, 47
DRIVER_POWER_STATE_FAILURE bug check, 461
drivers. See also WDM drivers
vs. applications, 22-24
history, 1-5
operating systems and, 3-5
processors and, 1-2
role in Windows XP, 7-8
types of, 10-12
DriverUnload function
callback in HIDCLASS minidrivers, 649
deregistration and, 355
for filter drivers, 780
overview, 25, 51, 57, 59
Windows 98/Me issues, 87
DT.EXE file, 641
dynamic linking, run-time, 802-3
E
end users, role in controlling wake-up features, 462-63
endpoint descriptors, 586-88
ENDPOINT_HALT feature, 575
endpoints
bus transactions, 570
determining status, 616-17
interrupt, 617, 618
isochronous, 617, 618
setting and clearing features, 614-15
enumerating device interfaces, 77-80
enumeration, recursive, 38, 39
error handling
bug check aspect, 106-7
creating error log packets, 675-78
logging errors, 673-82, 695
in LOOPBACK example, 611-13
overview, 92
status code aspect, 93-95
structured exception handling aspect, 95-105
error logging
creating packets, 675-78
overview, 673-75
Windows 98/Me issues, 695
Event kernel dispatcher object, 177
event log, 18, 723
Event Viewer
error messages and, 678-82
role of registry, 681-82
EVENTLOG example, 679-80
EVENT_MODIFY_STATE privilege, 499-500
events
notifying applications, 497-505
shared, 497, 498, 499-500
WMI, overview, 528-29
EVWAIT sample driver, 499
ExAcquireFastMutex function, 202
ExAcquireFastMutexUnsafe function, 202, 203
ExAllocateFromNPagedLookasideList function, 132
ExAllocateFromPagedLookasideList function, 132
ExAllocatePoolWithQuotaTag function, 123-24
ExAllocatePoolWithTag function, 108, 117-19, 133
ExAllocatePoolWithTagPriority function, 123-24
_except expression, 103-4
exception filter expressions, 102-3
exception handling, structured, 95-105
exceptions, raising, 104
ExDeleteNPagedLookasideList function, 133, 134
ExDeletePagedLookasideList function, 133, 134
executable files
device drivers as, 24-27
sections within, 111, 113-14
executive, role in Windows XP architecture, 90, 91
executive fast mutex objects, 190, 201-4
ExFreePool function, 108, 122-23, 133, 632, 633
ExFreePoolWithTag function, 808
ExFreeToNPagedLookasideList function, 133
ExFreeToPagedLookasideList function, 133
ExGetPreviousMode function, 201
ExInitializeFastMutex function, 202, 203
ExInitializeNPagedLookasideList function, 132
ExInitializePagedLookasideList function, 132
ExInitializeSListHead function, 211
ExInterlockedAddLargeInteger function, 206, 209
ExInterlockedAddLargeStatistic function, 206, 210
ExInterlockedAddULong function, 206, 209, 210
ExInterlockedInsertHeadList function, 211
ExInterlockedInsertTailList function, 211
ExInterlockedPopEntryList function, 212
ExInterlockedPopEntrySList function, 212
ExInterlockedPushEntryList function, 211
ExInterlockedPushEntrySList function, 211
ExInterlockedRemoveHeadList function, 212
ExIsProcessorFeaturePresent function, 152, 809
ExLocalTimeToSystemTime function, 808
exporting direct-call interfaces, 552-53
ExRaiseAccessViolation function, 105
ExRaiseDatatypeMisalignment function, 105
ExRaiseStatus function, 105
ExReleaseFastMutex function, 202
ExReleaseFastMutexUnsafe function, 202
ExSystemTimeToLocalTime function, 808
Extended I/O Verification, 222
Extra Device Objects (EDOs), 793
ExTryToAcquireFastMutex function, 202
F
fast mutex objects, 190, 201-4
FASTINST example, 754
FastIoDispatch field, 51
FDOs (functional device objects)
bus filters as, 795-96
defined, 30
examples, 42-45
multifunction devices and, 536, 537
relationship to PDOs and FiDOs, 42-45
USB42 example, 45, 46
FEATURE example, 615-16
feature reports, 643, 645, 665
feature URBs, 614-15
FiDOs (filter device objects)
bus filters and, 795-96
defined, 30
examples, 42-45
relationship to PDOs and FDOs, 42-45
upper filter drivers and, 773
file I/O, Windows 98/Me issues, 157-58
file system drivers
IRP creation and, 223
overview, 12
role in opening disk files, 66-67
FILE_ANY_ACCESS permission, 484
FILE_DEVICE_DISK devices, 471
FILE_DEVICE_MASS_STORAGE devices, 471
FILEIO example, 148, 158
FileObject pointer, 221, 228, 229
FILE_READ_ACCESS permission, 484
FILE_READ_ATTRIBUTES permission, 69
FILE_REMOVABLE_MEDIA flag, 787
FILE_TRAVERSE permission, 69
FILE_WRITE_ACCESS permission, 484
filter drivers
vs. bus drivers, 30
creating, 779-87
defined, 11
DispatchPnP routine, 784-87
DispatchPower routine, 784
DriverEntry routine, 779-80
examples, 791-99
FiDO and, 30, 42, 43, 44, 45
vs. function drivers, 30
installing, 787-91
IRP routing and, 41
lower, 30, 38-39, 778-79
overview, 14, 773
PnP Manager and, 313-14
as power policy owner, 426
registry information, 38-39
role in power management, 427
upper, 30, 38-39, 773-78
Windows 98/Me issues, 800
FILTER example, 779
FILTER.HTM file, 791
filtering
after-the-fact, 790-91
driver resource requirements, 342-44
HID devices, 776-77, 799
filters
bus, 795-96
keyboard, 796-99
mouse, 796-99
named, 792-95
FILTJECT.DLL example, 790-91
finite state machine
HandlePowerEvent routine, 437
IRP flow when decreasing device power, 450-51
IRP flow when decreasing system power, 447
IRP flow when increasing device power, 450
IRP flow when increasing system power, 438
overview, 434
state transitions when decreasing system power, 447, 448
state transitions when increasing system power, 438-41
state transitions when querying about higher device power state, 455
state transitions when querying about lower device power state, 448-59
state transitions when setting higher device power state, 451-54
state transitions when setting lower device power state, 456-58
floating-point calculations, 151-52, 158-59
FlushAdapterBuffers routine, 409-10
FlushPendingIo function, 434, 449
FPUTEST example, 152
free build environment, 153, 154
friendly names, 79, 772
function drivers
AddDevice routine, 60-86
vs. bus drivers, 30
bus drivers as, 774
for composite devices, 636-38
defined, 29
for disk and tape storage devices, 774
DriverEntry routine, 54-59
FDO and, 30, 42, 43, 44, 45
vs. filter drivers, 30
implementing selective suspend protocol, 635-38
installing device filters at the same time, 790
MOUCLASS.SYS as, 776
for multifunction devices in Windows 98/Me, 535
overview, 29
passing power requests to lower-level drivers, 430-33
PnP Manager and, 314
as power policy owner, 426-27
wake-up problems, 635-36
G
game pads, HIDCLASS-compatible ID for, 642
generic devices, device identifiers for, 732
GenericCacheControlRequest function, 651
GenericIdleDevice function, 638
GenericSaveRestoreComplete function, 454, 457
GENERIC.SYS driver
delegating IRP_MJ_POWER requests, 433-34
DEVQUEUE code in, 260, 274-80, 323
keeping track of asynchronous IOCTL requests, 502
RestoreDeviceContext function, 453-54
SaveDeviceContext function, 457, 458
selecting power states, 445
GenericUncacheControlRequest function, 651
GenericWakeupFromIdle function, 638
GENINF tool, 736
GET_CONFIGURATION standard device request, 574
GetCurrentIrp function, 322, 694
GET_DESCRIPTOR standard device request, 573, 580, 583-84, 585, 586, 588
GetDevicePowerState function, 434, 445
GetDeviceTypeToUse function, 781
GET_INTERFACE standard device request, 574
GET_ISO_URB_SIZE macro, 623
GetProcAddress function, 802
Get_Report_Request control pipe command, 645
GetScatterGatherList routine, 413-15
GET_SELECT_INTERFACE_REQUEST_SIZE request, 620
GET_STATUS standard device request, 573
GetStringDescriptor function, 599
GetWindowLong function, 741
\GLOBAL?? directory, 65-66, 72, 87
globally unique identifiers (GUIDs)
creating, 74
determining for HID devices, 657, 658
for direct-call interfaces, 549, 550
kernel-mode notifications and, 355, 356-57
overview, 73-74
WM_DEVICECHANGE message and, 348, 354
WMILIB and, 516, 523-24
GUID_DEVICE_INTERFACE_ARRIVAL notification, 357
GUID_DEVICE_INTERFACE_REMOVAL notification, 357
GUIDGEN utility, 73, 74
GUID_HWPROFILE_CHANGE_CANCELLED notification, 357, 358
GUID_HWPROFILE_CHANGE_COMPLETE notification, 357, 358
GUID_HWPROFILE_QUERY_CHANGE notification, 357, 358
GUIDs. See globally unique identifiers
GUIDS.H file, 75
GUID_TARGET_DEVICE_QUERY_REMOVE notification, 357, 358
GUID_TARGET_DEVICE_REMOVE_CANCELLED notification, 357
GUID_TARGET_DEVICE_REMOVE_COMPLETE notification, 357
H
HAL. See hardware abstraction layer
HAL.DLL file, 29
HalGetAdapter function, 401
HalTranslateBusAddress function, 808
handshake phase, bus transactions, 568-69
hardware. See also device objects
creating HIDCLASS minidrivers for, 646-69
detection by operating system, 28, 31-37
how drivers work, 21-27
installing drivers programmatically, 754, 770
layering, 28-30
managing device drivers in development, 16-19
preinstalling driver files, 752-53
wake-up features, 461-69
hardware abstraction layer (HAL), 8, 29, 90, 91, 241, 374, 375, 778
Hardware Compatibility Tests (HCTs), 697, 757-63
hardware key, registry
accessing, 705
defined, 698
list of device properties, 705-6
overview, 34, 699-701
user-mode interface, 706
hardware parameters key, registry
accessing, 705
defined, 698
initializing, 720-22
overview, 703
user-mode interface, 706
HardwareDatabase field, 50
header files
BASETSD.H file, 49
DEVICELIST.H file, 77
GUIDS.H file, 75
NTSTATUS.H file, 58
heap allocation, 117-24
Hibernate state, 428
HID collections
application collections, 641
link collections, 642
logical collections, 641, 645
opening in user mode, 656-58
physical collections, 641
HID Descriptor Tool, 641-44, 661
HID devices
alternative to DeviceIoControl, 479
determining GUIDs, 657, 658
drivers for, 13, 640
filtering, 776-77, 799
overview, 639
role of reports and report descriptors, 640-45
Windows 98/Me compatibility issues, 670-71
HID Usage Tables specification, 639, 641
HIDCLASS minidrivers
common features of control operations, 654
driver callback routines, 647-55
HIDUSB.SYS driver, 13, 640, 646, 776
list of control operations, 653
role of DriveEntry function, 646-47
HIDCLASS.SYS driver, 13, 469, 640
HID_DEVICE_EXTENSION structure, 648-49
HID_DEVICE_SYSTEM_CONSUMER ID, 642
HID_DEVICE_SYSTEM_CONTROL ID, 642
HID_DEVICE_SYSTEM_GAME ID, 642
HID_DEVICE_SYSTEM_KEYBOARD ID, 642
HID_DEVICE_SYSTEM_MOUSE ID, 642
HidD_GetAttributes function, 658
HidD_GetFeature function, 479, 665
HidD_GetHidGuid function, 657
HidD_GetIndexedString function, 668
HidD_GetInputReport function, 662
HidD_GetManufacturerString function, 666
HidD_GetProductString function, 667
HidD_GetSerialNumberString function, 667
HidD_SetFeature function, 479, 665
HidD_SetOutputReport function, 662
HID_MINIDRIVER_REGISTRATION structure, 646-47
HidRegisterMinidriver function, 646
HIDUSB.SYS driver, 13, 640, 646, 776
highest-level drivers, 178, 179
HIGH_LEVEL IRQL, 167
HKEY_LOCAL_MACHINE registry branch, 698
host controllers, in USB devices, 561, 562
hot-plug capability, 32, 536
Human Interface Devices (HIDs). See HID devices
I
I8042.SYS driver, 776
IDE devices
device identifiers for, 729-30
standard data blocks, 532
IgnoreRequest subroutine, 542-43
IMAPI.SYS driver, 775, 776
INF files
add-registry syntax, 718-20
CHKINF tool, 734-35
debugging, 736-37
defining device classes, 737-38
defining driver service, 717-18
device identifiers, 726-32
event logging, 723
GENINF tool, 736
Install section, 713-18
legacy devices and, 712
list of predefined classes, 710-11
literal strings in, 725
Manufacturer section, 711-12
overview, 709-13
platform variations, 714-15
ranking multiple drivers, 732-34
security settings, 723-25
table of named strings, 725
tools for, 734-37
as tree structure, 711-12
Version section, 709-10
WDMWIZ.AWX wizard and, 818-19
Windows 98/Me issues, 771, 800
information flow
allowable maximum packet sizes, 567
bulk data transfer type, 566, 567, 575-77
control data transfer type, 566, 567, 570-75
data transfer methods, 566-79
interrupt data transfer type, 566, 567, 577-78
isochronous data transfer type, 566, 567, 578-79
packaging, 568-69
Initialize function, 78-79
InitializeLinkHead function, 126, 127, 211
InitializeObjectAttributes macro, 139-40
InitializeQueue function, 322, 338
input reports, 642, 643, 645
INRUSH flag. See DO_POWER_INRUSH flag
InsertHeadList function, 126, 127
InsertIrp routine, 267
InsertTailList function, 126, 127
installing
class filters, 787-90
device filters, 790
drivers for legacy devices, 35-37
filter drivers, 787-91
Plug and Play devices, 32
Windows 98/Me driver issues, 769-72
instance key, registry, 698, 699-701
instances, defined, 508-9
interface descriptors, 585-86
interface key, registry, 141-42
interfaces
descriptors for, 597, 599-600
determining status, 616-17
setting and clearing features, 614-15
interlocked arithmetic, 206-10
interlocked linked lists, 210-13
InterlockedAnd function, 206, 208
InterlockedCompareExchange function, 206
InterlockedCompareExchange64 function, 206, 210
InterlockedCompareExchangePointer function, 207
InterlockedDecrement function, 206, 207
InterlockedExchange function, 206, 208
InterlockedExchangeAdd function, 206
InterlockedExchangePointer function, 208
InterlockedIncrement function, 206-7
InterlockedOr function, 206, 208
InterlockedXor function, 206, 208
InterlockedXxx functions, 206-9
INTERNAL_POWER_ERROR bug check, 461
interrupt data transfer type, 566, 567, 577-78
interrupt endpoints, 617, 618
interrupt pipes, managing, 613-14
interrupt request levels (IRQLs)
APC_LEVEL, 167, 168, 199, 204, 282, 305
DISPATCH_LEVEL, 165, 166-67, 168, 169, 170
example, 167-68
explicitly controlling, 171-72
HIGH_LEVEL, 167
implicitly controlling, 169-71
linked list restrictions, 212-13
list of levels, 165
overview, 164-67
paging and, 168-69
PASSIVE_LEVEL, 164, 166, 167, 168, 169, 170, 171
PROFILE_LEVEL, 167, 168
SYNCH_LEVEL, 167
vs. thread priorities, 168
Interrupt resource type, 367, 390
interrupt service routines (ISRs)
DPC and, 241-42
overview, 241, 382
PCI42 driver example, 394-96
programming restrictions in, 382
role of deferred procedure calls, 82
synchronizing operations with, 383-84
interrupts
configuring, 379-81
handling, 381-84
handling in PKTDMA, 422-23
servicing, 379-97
I/O controls (IOCTLs)
asynchronous, 501-2
data buffer methods for requests, 487-92
defining codes, 483-85
designing interfaces, 492-94
internal operations, 494-97
notifying applications of events, 497-505
I/O Manager
addressing data buffers, 367-73
creating file objects, 290
creating IRPs, 223-26
defined, 6
role in naming device objects, 69-71
role in registering device interfaces, 76
role in Windows XP architecture, 89, 91
role of driver object data structure, 47-51
I/O request packets (IRPs)
aborting requests, 341-42
APCs and, 199-200
associated, 635
asynchronous vs. synchronous, 223
awaiting current IRP, 340
basic data structure, 215-19
cancelling, 269-93
cancelling someone else's, 286-88
completing, 232-36
completion routines, 242-56
creating, 223-26
decreasing system power, 446-48
deleting to WMILIB, 514-23
device power overview, 449-51
final cleanup, 236
function codes, major and minor, 33
handle-based, 336
increasing system power, 438-46
IO_STACK_LOCATION data structure, 215, 219-22
overview, 215
passing down stacks, 236-38
queuing, 256-69
restarting queues, 339-40
role in power management, 426-33
role of PnP Manager, 25, 307
routing, 41-46
scenario 1: pass down with completion routine, 294-95
scenario 2: pass down without completion routine, 295-96
scenario 3: complete in dispatch routine, 296-97
scenario 4: queue for later processing, 297-99
scenario 5: creating asynchronous IRP, 299-301
scenario 6: creating synchronous IRP, 301-3
scenario 7: synchronous pass down, 303-4
scenario 8: asynchronous IRP handled synchronously, 304-6
sending to bus driver, 32-34
setting higher device power state, 451-55
setting lower device power state, 456-59
stack locations, 219-22
stalling queues, 338
standard model for processing, 222-42
state transitions and, 320-42
submitting device power requests, 445-46
surprise removal, 308, 319-20, 353, 360
tail union map, 219
unstalling queues, 339-40
I/O resources
defined, 312
direct memory access channels, 312
handling lists, 364-67
interrupt requests, 312
I/O ports, 312
list of processing steps, 367
list of types, 312
memory registers, 312
WDMWIZ.AWX wizard and, 815
I/O Verification, 222
IoAcquireRemoveLock function, 162, 300, 303, 306, 329-30
IoAcquireRemoveLockEx function, 808
IoAllocateAdapter function, 398
IoAllocateIrp function, 223, 225, 226, 227, 284, 299
IoAllocateWorkItem function, 808
IoAttachDevice function, 231
IoAttachDeviceToDeviceStack function
in filter driver AddDevice routine, 708, 780, 781, 782
in function driver AddDevice routine, 60, 81, 84-85, 236, 708
vs. IoDetachDevice function, 318
IoBuildAsynchronousFsdRequest function, 223, 225, 226, 284, 299, 301, 474
IoBuildDeviceIoControlRequest function, 223, 224, 225, 248, 302, 494-95, 496
IoBuildSynchronousFsdRequest function, 223, 224, 225, 248, 302, 495
IoCallDriver function, 227-28, 231, 236, 244, 245, 251, 283, 495
IoCancelIrp function
cancelling I/O requests, 269, 270, 271, 272-73, 277, 278, 279, 281, 282, 283
in USBISO example, 629, 630-31, 633, 634
IoCompleteRequest function
APC routine and, 200
calling completion routines, 245-47, 248, 249, 250, 251, 252, 253, 465
overview, 224, 233, 234-36, 242
role in cancelling IRPs, 281, 283, 288
IoConnectInterrupt function, 241, 379-81, 382, 383
IoControlCode parameter, 486
IoCopyCurrentIrpStackLocationToNext macro, 237, 244, 249
IoCreateDevice function
buffer alignment and, 83
in filter driver AddDevice routine, 708, 780, 781
in function driver AddDevice routine, 51, 60, 61-63, 708
vs. IoDeleteDevice function, 318
naming of device objects and, 69-71, 231
overview, 51, 60, 61-63, 708, 780
security descriptors and, 69, 70-71
IoCreateDeviceSecure function, 70
IoCreateNotificationEvent function, 808
IoCreateSymbolicLink function, 68
IoCreateSynchronizationEvent function, 808
IoCsqInsertIrp function, 267, 268
IoCsqRemoveNextIrp function, 267, 268
IOCTL_GET_PHYSICAL_DESCRIPTOR control code, 653, 666
IOCTL_HID_GET_DEVICE_ATTRIBUTES control code, 653, 655-58
IOCTL_HID_GET_DEVICE_DESCRIPTOR control code, 653, 658-60
IOCTL_HID_GET_FEATURE control code, 653, 663-66
IOCTL_HID_GET_INDEXED_STRING control code, 653, 668-69
IOCTL_HID_GET_REPORT_DESCRIPTOR control code, 653, 660-61
IOCTL_HID_GET_STRING control code, 653, 666-68
IOCTL_HID_READ_REPORT control code, 653, 661-63
IOCTL_HID_SEND_IDLE_NOTIFICATION control code, 653, 669
IOCTL_HID_SET_FEATURE control code, 653, 663-66
IOCTL_HID_WRITE_REPORT control code, 653, 663
IOCTL_INTERNAL_GET_SECRET request, 497
IOCTL_INTERNAL_KEYBOARD_CONNECT request, 797
IOCTL_INTERNAL_MOUSE_CONNECT request, 797
IOCTL_INTERNAL_USB_GET_PORT_STATUS request, 611
IOCTL_INTERNAL_USB_RESET_PORT request, 611
IOCTL_SCSI_PASS_THROUGH request, 479
IOCTL_WAIT_NOTIFY control code, 500
IoDeleteDevice function, 81, 134, 318, 332-33, 650
IoDereferenceObject function, 229
IoDetachDevice function, 318, 333, 337, 650
IO_ERROR_LOG_PACKET data structure, 675
IoForwardIrpSynchronously function, 304
IoFreeIrp function, 248, 251, 281, 282, 285, 630
IoFreeWorkItem function, 808
IoGetAttachedDeviceReference function, 228, 232, 781
IoGetConfigurationInformation function, 72
IoGetCurrentIrpStackLocation function, 246, 310
IoGetDeviceObjectPointer function, 64, 228-31, 300, 332, 356, 358
IoGetDeviceProperty function, 705, 772
IoGetDmaAdapter function, 367, 398, 401, 402-4, 416, 418
IoGetNextIrpStackLocation function, 226
IoInitializeDpcRequest macro, 385
IoInitializeRemoveLock function, 329
IoInitializeRemoveLockEx function, 808
IoInvalidateDeviceRelations function, 32
IoMakeAssociatedIrp function, 635
I/O-mapped devices, 373, 375-77
IoMapTransfer function, 398
IoMarkIrpPending function, 247-54, 437
IoOpenDeviceInterfaceRegistryKey function, 138, 141-42
IoOpenDeviceRegistryKey function, 138, 141, 772
IoQueueWorkItem function, 356, 690, 691, 808
IoRaiseInformationalHardError function, 808
IoRegisterDeviceInterface function, 75, 76, 122, 348, 708
IoRegisterPlugPlayNotifications function, 355
IoReleaseCancelSpinLock function, 271
IoReleaseRemoveLock function, 300, 303, 306, 329-30
IoReleaseRemoveLockAndWait function, 331, 335
IoReleaseRemoveLockEx function, 808
IoReleaseRemoveLockExAndWaitEx function, 808
IO_REMOVE_LOCK object, 328, 361, 807
IoReportTargetDeviceChange function, 359, 361
IoReportTargetDeviceChangeAsynchronous function, 359, 361, 809
IoRequestDpc function, 242, 385-86, 387
IO_RESOURCE_REQUIREMENTS_LIST data structure, 342
IoReuseIrp function, 610, 809
IoSetCancelRoutine function, 504, 632, 633, 634
IoSetCompletionRoutine function, 242-45, 337
IoSetCompletionRoutineEx function, 254-56, 809
IoSkipCurrentIrpStackLocation function, 237-38, 249, 335, 337, 431
IO_STACK_LOCATION data structure
copying vs. skipping, 237-38
overview, 215, 219-22
Power substructure, 430
UsageNotification substructure, 344-47
IoStartNextPacket function, 256-57, 271
IoStartPacket function, 256-57, 271
IoStartTimer function, 693
IoStatus field, 217, 233, 234
IoStopTimer function, 693
IO_TIMER object, 691, 692
IoUnregisterPlugPlayNotifications function, 355
IoWmiRegistrationControl function, 513, 523
IO_WORKITEM structure, 690
IRP_MJ_CLEANUP function code, 289-90, 291, 292, 505
IRP_MJ_CLOSE function code, 289-90, 473, 502, 622, 692
IRP_MJ_CREATE function code, 289-90, 473, 502, 622, 692
IRP_MJ_DEVICE_CONTROL function code
data buffering methods, 487-92
overview, 479, 485-88
stack location parameters, 485, 486
IRP_MJ_INTERNAL_DEVICE_CONTROL function code
in dispatch routine for filter driver, 797
sending URBs, 589, 592
typical internal I/O control operation, 494-97
in USBISO example, 626
IRP_MJ_PNP function code
dispatch function for, 310-11, 330
in dispatch routine in filter drivers, 784-85
full DEVQUEUE implementation, 338-42
in HIDCLASS minidriver, 646, 649
PnP Manager and, 336
IRP_MJ_POWER function code, 336, 429-33, 437, 460, 464, 554, 646, 784
IRP_MJ_QUERY_VOLUME_INFORMATION function code, 336
IRP_MJ_READ function code, 368, 605, 607, 626
IRP_MJ_SHUTDOWN function code, 336
IRP_MJ_SYSTEM_CONTROL function code, 336, 512-13, 817-18
IRP_MJ_WRITE function code, 368, 605, 607, 626
IRP_MM_CHANGE_SINGLE_INSTANCE function code, 513
IRP_MM_CHANGE_SINGLE_ITEM function code, 513
IRP_MM_DISABLE_COLLECTION function code, 513
IRP_MM_DISABLE_EVENTS function code, 513
IRP_MM_ENABLE_COLLECTION function code, 513
IRP_MM_ENABLE_EVENTS function code, 513
IRP_MM_EXECUTE_METHOD function code, 513
IRP_MM_QUERY_ALL_DATA function code, 513
IRP_MM_QUERY_SINGLE_INSTANCE function code, 513
IRP_MM_REGINFO function code, 513
IRP_MN_CANCEL_REMOVE_DEVICE function code, 308, 326, 327, 539
IRP_MN_CANCEL_STOP_DEVICE function code, 308, 325, 539
IRP_MN_CHANGE_SINGLE_INSTANCE function code, 518, 521
IRP_MN_CHANGE_SINGLE_ITEM function code, 518, 522
IRP_MN_DEVICE_USAGE_NOTIFICATION function code, 308, 325, 344-47, 540, 785, 786
IRP_MN_DISABLE_EVENTS function code, 529
IRP_MN_EJECT function code, 308, 540
IRP_MN_ENABLE_EVENTS function code, 529
IRP_MN_FILTER_RESOURCE_REQUIREMENTS function code, 342-44, 539
IRP_MN_INTERNAL_DEVICE_CONTROL function code, 607
IRP_MN_POWER_SEQUENCE function code, 429, 474, 554
IRP_MN_QUERY_ALL_DATA function code, 518, 519
IRP_MN_QUERY_BUS_INFORMATION function code, 308, 540
IRP_MN_QUERY_CAPABILITIES function code, 308, 319, 441, 539
IRP_MN_QUERY_DEVICE function code, 539
IRP_MN_QUERY_DEVICE_RELATIONS function code, 308, 336, 536, 539, 541, 548-49
IRP_MN_QUERY_DEVICE_TEXT function code, 539
IRP_MN_QUERY_ID function code, 308, 540, 547-48, 670-71
IRP_MN_QUERY_INTERFACE function code, 308, 336, 539, 549-53
IRP_MN_QUERY_LEGACY_BUS_INFORMATION function code, 540
IRP_MN_QUERY_PNP_DEVICE function code, 540
IRP_MN_QUERY_PNP_DEVICE_STATE function code, 308, 553
IRP_MN_QUERY_POWER function code, 429, 433, 434, 437, 445, 458, 554
IRP_MN_QUERY_REMOVE_DEVICE function code, 308, 326, 327-28, 352, 353, 539
IRP_MN_QUERY_RESOURCE_REQUIREMENTS function code, 308, 539, 558
IRP_MN_QUERY_RESOURCES function code, 308, 539
IRP_MN_QUERY_SINGLE_INSTANCE function code, 518, 519
IRP_MN_QUERY_STOP_DEVICE function code, 308, 323, 324, 326, 327, 539
IRP_MN_READ_CONFIG function code, 308, 540
IRP_MN_REGINFO function code, 515, 516, 518
IRP_MN_REMOVE_DEVICE function code
in DispatchPnP routine, 785, 787
in filter drivers, 785, 787
in HIDCLASS minidrivers, 650
overview, 307, 308, 318-19
parent driver handling, 539, 546-47
state transitions and, 328, 331, 333-35, 336
terminating system threads, 686
Windows 98/Me issues, 361
IRP_MN_SET_LOCK function code, 308, 540
IRP_MN_SET_POWER function code, 429, 433, 434, 437, 438, 445, 451, 456, 554, 555, 636, 782
IRP_MN_START_DEVICE function code
in DispatchPnP routine, 785, 787
FILE_REMOVABLE_MEDIA flag and, 787
in filter drivers, 785, 787
in HIDCLASS minidrivers, 650, 655
overview, 307, 308, 313-16
parent driver handling, 539
spawning system threads, 686
state transitions and, 323
IRP_MN_STOP_DEVICE function code
overview, 307, 308, 316-17
parent driver handling, 539
state transitions and, 323, 325-26
terminating system threads, 686
IRP_MN_SURPRISE_REMOVAL function code, 308, 319-20, 353, 465, 540
IRP_MN_WAIT_POWER function code, 554
IRP_MN_WAIT_WAKE function code, 429, 462, 464-65, 554, 556-57, 615, 635-36
IRP_MN_WRITE_CONFIG function code, 308, 540
IRPs. See I/O request packets
IRQLs. See interrupt request levels
ISAPNP devices, device identifiers for, 730
IShellExtInit interface, 471
IShellPropSheetExt interface, 471
IsListEmpty function, 126, 127
isochronous data transfers, 566, 567, 578-79, 622-28
isochronous endpoints, 617, 618
isochronous pipes
data streaming, 622-25
overview, 617-35
reading from, 622-25
writing to, 622-25
isochronous URBs, 623-25
IWhemClassObject interface, 528
Next
Last Updated: December 12, 2002
|
