Tips for Windows NT Driver Developers -- Things to Avoid

INFO: Tips for Windows NT Driver Developers -- Things to Avoid

Retired KB Content Disclaimer

View products that this article applies to.

This article was previously published under Q186775

Expand all | Collapse all

SUMMARY

Following are some tips for creating Windows NT device drivers. The tips presen...

Following are some tips for creating Windows NT device drivers. The tipspresented apply to all technologies. You can also use this as a checklistfor troubleshooting driver problems.

You need to have a basic knowledge of Windows NT architecture and somedevice driver development experience to use the information presented beloweffectively. For more information on device driver development, please seethe Windows NT device driver kit (DDK), which is available through MSDNProfessional membership.

Back to the top

MORE INFORMATION

Following is a list of things that developers should avoid when working with Wi...

Following is a list of things that developers should avoid when workingwith Windows NT device drivers:

1. Never return STATUS_PENDING from a dispatch routine without marking the I/O request packet (IRP) pending (IoMarkIrpPending).
2. Never call KeSynchronizeExecution from an interrupt service routine (ISR). It will deadlock your system.
3. Never set DeviceObject->Flags to both DO_BUFFERED_IO and DO_DIRECT_IO. It can confuse the system and eventually lead to fatal error. Also, never set METHOD_BUFFERED, METHOD_NEITHER, METHOD_IN_DIRECT or METHOD_OUT_DIRECT in DeviceObject->Flags, because these values are only used in defining IOCTLs.
4. Never allocate dispatcher objects from a paged pool. If you do, it will cause occasional system bugchecks.
5. Never allocate memory from paged pool, or access memory in paged pool, while running at IRQL >= DISPATCH_LEVEL. It is a fatal error.
6. Never wait on a kernel dispatcher object for a nonzero interval at IRQL >= DISPATCH_LEVEL. It is a fatal error.
7. Never call any function that causes the calling thread to wait directly or indirectly while executing at IRQL >= DISPATCH_LEVEL. It is a fatal error.
8. Never lower the interrupt request level (IRQL) below the level at which your top-level routine has been invoked.
9. Never call KeLowerIrql() if you haven't called KeRaiseIrql().
10. Never stall a processor (KeStallExecutionProcessor) longer than 50 microseconds.
11. Never hold any spin locks longer than necessary. For better overall system performance, do not hold any system-wide spin locks longer than 25 microseconds.
12. Never call KeAcquireSpinLock and KeReleaseSpinLock, or KeAcquireSpinLockAtDpcLevel and KeReleaseSpinLockFromDpcLevel, while running at IRQL greater than DISPATCH_LEVEL.
13. Never release a spin lock that was acquired with KeAcquireSpinLock by calling KeReleaseSpinLockFromDpcLevel, because the original IRQL will not be restored.
14. Never call KeAcquireSpinLock and KeReleaseSpinLock or any other routine that uses an executive spin lock from an ISR or SynchCritSection routine(s).
15. Never forget to clear DO_DEVICE_INITIALIZING flag when you create a device object in a routine other than DriverEntry.
16. Never queue a deferred procedure call (DPC) object (using KeInsertQueueDpc) with multiple threads on different processors simultaneously. It can lead to fatal error.
17. Never deallocate a periodic timer from a CutomerTimerDPC routine. You can deallocate nonperiodic timers from a DPC routine.
18. Never pass the same DPC pointer to KeSetTimer, or KeSetTimerEx (CustomTimerDpc) and KeInsertQueueDpc (CustomDpc), because it causes race conditions.
19. Never call IoStartNextPacket while holding a spin lock. It can deadlock your system.
20. Never call IoCompleteRequest while holding a spin lock. It can deadlock your system.
21. Never call IoCompleteRequest without setting the completion routine to NULL if your driver sets the completion routine.
22. Never forget to set the I/O status block in the IRP before calling IoCompleteRequest.
23. Never call IoMarkPending after queuing an IRP or sending it to another driver (IoCallDriver). The IRP may be completed before the driver calls IoMarkPending and a bugcheck might occur. For drivers with completion routines, the completion routines must call IoMarkPending if Irp->PendingReturned is set.
24. Never touch an IRP after you have called IoCompleteRequest on it.
25. Never call IoCancelIrp on an IRP that is not owned by your driver unless you know that the IRP has not been completed yet.
26. Never call IoCancelIrp for the IRP that your dispatch routine is working on until your dispatch routine returns to caller.
27. Never call IoMakeAssociatedIrp to create IRPs for lower drivers from an intermediate driver. The IRP you get in your intermediate driver could be an associated IRP, and you cannot associate other IRPs to an already associated IRP.
28. Never call IoMakeAssociatedIrp on an IRP that is set up to perform buffered I/O.
29. Never simply dereference virtual pointers to device I/O registers and access them. Always use correct hardware abstraction layer (HAL) functions to access a device.
30. Never access IRP or device object fields from an ISR that may be modified from DISPATCH_LEVEL. On a symmetric multiprocessor system this can cause data corruption.
31. Never modify data while running at high-IRQL if that data may be written by low-IRQL code. Use the KeSynchronizeExecution routine.
32. Never acquire one of the driver's own spin locks (if you have any) in your DispatchCleanup routine, before acquiring the system-wide cancel spin lock (IoAcquireCancelSpinLock). Following a consistent lock acquisition hierarchy throughout your driver is essential to avoiding potential deadlocks.
33. Never call IoAcquireCancelSpinLock in your cancel routine because it is always called with the system cancel spin lock held on its behalf.
34. Never forget to call IoReleaseCancelSpinLock before returning from a cancel routine.
35. Never use IRQL-based synchronization because this works only on single processor systems. Raising IRQL on one processor does not mask interrupts on other processors.
36. Never use RtlCopyMemory for overlapped memory address ranges. Use RtlMoveMemory.
37. Never assume page sizes are constant, even for a given CPU. Use PAGE_SIZE and other page related constants defined in header files to maintain portability.
38. Never access any registry keys other than Registry/Machine/Hardware and Registry/Machine/System from DriverEntry routine of a driver loaded in Boot/System Initialization phase.
39. Never create an Enum key for loading a driver under a driver's registry key (Registry/Machine/System/CurrentControlSet/Services). The system creates this key dynamically.
40. Never attempt to initialize a physical device without claiming the necessary bus-relative I/O ports, memory ranges, interrupt, or direct memory access (DMA) channel/port hardware resources in the registry first.
41. Never call IoRegisterDriverReinitialization from your DriverEntry routine unless it returns STATUS_SUCCESS.
42. Never call KeSetEvent with the Wait parameter set to TRUE from a pageable thread or pageable driver routine that runs at IRQL PASSIVE_LEVEL. This type of call causes a fatal page fault if your routine happens to be paged out between the calls to KeSetEvent and KeWait..Object(s).
43. Never call KeReleaseSemaphore with the Wait parameter set to TRUE from a pageable thread or pageable driver routine that runs at IRQL PASSIVE_LEVEL. If your routine happens to be paged out between the calls to KeReleaseSemaphore and KeWait..Object(s), this type of a call causes a fatal page fault.
44. Never call KeReleaseMutex with the Wait parameter set to TRUE from a pageable thread or pageable driver routine that runs at IRQL PASSIVE_LEVEL. If your routine happens to be paged out between the calls to KeReleaseMutex and KeWait..Object(s), this type of a call causes a fatal page fault.
45. Never call KeBugCheckEx or KeBugCheck from a retail Windows NT driver to bring down the system, unless the error encountered is a critical error which would corrupt system memory or eventually cause the system to bugcheck. Always try to handle error conditions gracefully.
46. Never assume that an IoTimer routine will be called precisely on a one- second boundary because the intervals at which any particular IoTimer routine is called ultimately depends on resolution of the system clock.
47. Never call Win32s application programming interfaces (API) from a kernel-mode device driver.
48. Never use recursive functions that can cause the stack to overflow because the calling thread's kernel-mode stack does not grow dynamically while it is running in kernel-mode.
49. Never use interrupt object pointers (PKINTERRUPT) to identify interrupts in an ISR that handles more than one interrupt, because the address of the interrupt object you get in the ISR will not always be the same as the one you got from IoConnectInterrupt. You should only use the ServiceContext value that you specify in IoConnectInterrupt to identify the current interrupting device.
50. Never unload a driver without clearing CustomTimerDpc (KeCancelTimer). If the DPC is fired after the driver is unloaded, it could hit non existent-code and cause the system to bugcheck.
51. Never unload a driver until all the IRPs that have the I/O CompletionRoutine of the driver set in it are completed. If the IRP gets completed by the lower driver after your driver is unloaded, the system could try to execute the non-existent code and cause the system to crash.
52. Never enable device interrupt until your driver is ready to handle it. You should enable only after your driver is completely initialized, and it is safe for the system to touch the driver's internal structures in ISR and DPC.
53. Never call outside of your driver while holding a spinlock because it can cause deadlock.
54. Neverreturn any status other than STATUS_MORE_PROCESSING_REQUIRED from yourI/O CompletionRoutine for an IRP created by your driver withIoBuildAsynchronousFsdRequest/IoAllocateIrp because the IRP is notprepared for completion related post-processing by the I/O manager.Such an IRP should be freed explicitly (IoFreeIrp) by the driver. Ifthe IRP is not meant for reuse, it can be freed in theCompletionRoutine before returning statusSTATUS_MORE_PROCESSING_REQUIRED.
55. Never allocate an IRP with IoBuildSynchronousFsdRequest/IoBuildDeviceIoControlRequest in an Arbitrary thread context because the IRP remains associated with the thread (Irp->ThreadListEntry) until it is freed.
56. Nevercall IoInitializeIrp on an IRP that has been allocated withIoAllocateIrp with ChargeQuota parameter set to TRUE. When you allocatean IRP with ChargeQuota set to TRUE, the I/O manager keeps theinformation about the pool from which it allocated the memory for theIRP in the IRP's internal flag.
    
    When you call IoInitializeIrp on such an IRP, the allocation poolinformation is lost as this function blindly zeros the entire IRP. Thisleads to memory corruption when you free the IRP. Also, never reuse anIRP that comes from the IO manager. If you want to reuse an IRP, youshould allocate your own by using IoAllocateIrp.
57. Never specify WaitMode as UserMode inKeWaitForSingleObject/KeWaitForMultipleObjects if the Object isallocated in the calling thread's stack. The corollary of this is thatif the Object being waited on is created in the function stack, youmust specify KernelMode as the WaitMode to prevent the thread stackfrom being paged out.
58. Never acquire resources such as ERESOURCES andFastMutex(Unsafe) in the context of a user-mode thread withoutprotecting the code in a critical section.
    
    Because the acquisition of these resources does not raise the IRQL toAPC_LEVEL, if the thread is suspended (done by queuing an APC) after ithas acquired the resource, it could cause deadlock and compromisesystem security. Therefore, you should acquire such resources either byexplicitly raising the IRQL to APC_LEVEL or in a critical section bycalling KeEnterCriticalRegion.