Anatomy of a Windows driver: from DriverEntry to the IRP
On this page
The most common crash is misunderstood#
If you've ever seen a blue screen, chances are it said IRQL_NOT_LESS_OR_EQUAL. That's bug check 0xA, and its name suggests someone broke an abstract rule about interrupt levels. It's almost never that.
In the vast majority of real cases, there's something much more mundane behind it: a bad pointer, NULL or pointing to memory that has already been freed, or pageable memory touched at an IRQL too high for the page fault to be resolved. At DISPATCH_LEVEL or above, the system can't bring pages in from disk. What in a normal program would be a routine page fault, resolved without you ever noticing, becomes a bug check in the kernel. Its relative, 0xD1 (DRIVER_IRQL_NOT_LESS_OR_EQUAL), goes one step further and points straight at a driver.
That's why, when you debug one of these, the useful question isn't "which IRQL rule did I break?", but this one:
Which pointer did I dereference? Was it valid? And was its memory guaranteed to be present, given the IRQL my code was running at?
In From Ring 3 to Ring 0 we described the boundary between your programs and the kernel from the outside: how it's crossed and why a failure on the other side brings down the whole system. Today we cross that boundary and look at how the code living inside is organized: a Windows driver, from the moment it loads until it serves a request. To understand that question, we first need to understand what a driver is and what IRQL is.
A driver isn't a program#
An executable is passive: the operating system starts it, gives it its own memory space and, if it fails, closes the process and cleans up after it. A driver has none of that. It runs as part of the operating system, in Ring 0, and there's no process boundary protecting the rest of the system from its mistakes.
It doesn't have a main either. Its entry point is DriverEntry, and the Windows I/O Manager starts it when it loads the driver, without the C runtime startup chain that ends up calling main in a normal program. The only thing in between is GsDriverEntry, a minimal wrapper the compiler generates automatically, which does a little initialization and calls your DriverEntry. This is DriverEntry's signature, in a fragment from my driver fundamentals guide:
NTSTATUS DriverEntry(
// your identity, handed to you
PDRIVER_OBJECT DriverObject,
// your configuration key in the registry
PUNICODE_STRING RegistryPath
);Three rules come with that signature:
DriverEntryruns atPASSIVE_LEVEL, the lowest level, the same as a normal thread.- If it returns an error instead of
STATUS_SUCCESS, the driver isn't loaded and its unload routine is never called. Anything you created before failing is yours to undo, right there. - The
DRIVER_OBJECTisn't yours: it's handed to you, and you never delete it.
IRQL, the kernel's law of physics#
IRQL (Interrupt Request Level) is a small number, and there's one per core: from 0 to 15 on 64-bit Windows, the only kind Windows 11 comes in, and from 0 to 31 on old 32-bit x86. The rule is simple and has no exceptions: code running at a given IRQL can only be interrupted by something at a strictly higher IRQL. This is the table from my guide, with the 64-bit values:
| Level | Value | What runs there | Pageable memory / waiting |
|---|---|---|---|
PASSIVE_LEVEL | 0 | Normal threads, user mode, DriverEntry, AddDevice, Unload | Yes / Yes |
APC_LEVEL | 1 | Almost identical to PASSIVE_LEVEL; only blocks APC delivery | Yes / almost always |
DISPATCH_LEVEL | 2 | DPCs, cancel routines, IoTimer; no thread scheduling | No / No (bug check) |
| DIRQL | 3–12 | Each device's interrupt service routines (ISRs) | No / No: do the minimum and return |
Above the devices sit levels reserved for the system itself, such as the clock (13) or the highest one, HIGH_LEVEL (15). The important boundary, though, is between 1 and 2. Below it, your code behaves like any thread: it can wait, sleep and touch memory that might be on disk, because the system brings it in if needed. From DISPATCH_LEVEL up there's no thread scheduling on that core: nothing can put you to sleep or wake you up, and the system can't stop to read a page from disk. That's the explanation for the crash at the start: the same line of code that works at PASSIVE_LEVEL brings the system down at DISPATCH_LEVEL if the memory it touches turns out to be paged out.
An IRP's journey#
When a program asks a device for something, that request doesn't reach the driver as a function call. It arrives as an IRP (I/O Request Packet): a structure that represents the I/O request and travels down a driver stack. My guide sums it up in six steps:
- The application calls
ReadFile,WriteFileorDeviceIoControl. - The I/O Manager builds the IRP, with one
IO_STACK_LOCATIONfor each driver in the stack. - Filter drivers, if there are any, inspect it and pass it down.
- The function driver receives the IRP in its dispatch routine.
- The bus driver talks to the hardware.
IoCompleteRequestsends the IRP back up, with the result.
The non-negotiable rule: every IRP is completed or forwarded exactly once. A forgotten IRP isn't a memory leak, it's hung I/O: a program waiting forever for an answer that will never come. And my guide includes a very specific warning: if you call IoSkipCurrentIrpStackLocation and then set a completion routine, you can overwrite the one belonging to the driver above you.
Check it from user mode#
You don't need to write a driver to see the first step of that journey. This program opens the first physical disk and asks the Windows disk driver for its geometry with DeviceIoControl. It opens the disk with access 0, which only allows querying metadata: it doesn't read or write anything, which is why it doesn't need administrator rights. Like the Ring -2 post, this is Windows-only code:
// g++ -std=c++20 ioctl.cpp -o ioctl.exe (Windows)
// Asks the disk driver for its geometry with DeviceIoControl,
// without administrator rights.
#include <windows.h>
#include <winioctl.h>
#include <format>
#include <iostream>
int main() {
// Access 0: metadata only; the disk is neither read nor written.
HANDLE disk = CreateFileW(L"\\\\.\\PhysicalDrive0", 0,
FILE_SHARE_READ | FILE_SHARE_WRITE,
nullptr, OPEN_EXISTING, 0, nullptr);
if (disk == INVALID_HANDLE_VALUE) return 1;
DISK_GEOMETRY_EX geo{};
DWORD bytes = 0;
const DWORD code = IOCTL_DISK_GET_DRIVE_GEOMETRY_EX;
const BOOL ok = DeviceIoControl(disk, code, nullptr, 0,
&geo, sizeof geo, &bytes, nullptr);
CloseHandle(disk);
if (!ok) return 1;
// CTL_CODE(DeviceType, Function, Method, Access), unpacked
std::cout << std::format("IOCTL 0x{:08X}\n", code)
<< std::format(" DeviceType 0x{:X}\n", code >> 16)
<< std::format(" Function 0x{:X}\n", (code >> 2) & 0xFFF)
<< std::format(" Method {}\n", code & 3)
<< std::format(" Access {}\n", (code >> 14) & 3)
<< std::format("Disk {:.1f} GB\n",
geo.DiskSize.QuadPart / 1e9)
<< std::format("Sector {} bytes\n",
geo.Geometry.BytesPerSector);
}This is the real output on my machine, an Intel Core i9-14900KF running Windows 11:
IOCTL 0x000700A0
DeviceType 0x7
Function 0x28
Method 0
Access 0
Disk 2000.4 GB
Sector 512 bytesThat DeviceIoControl call is exactly step 1 of the journey. The I/O Manager builds an IRP_MJ_DEVICE_CONTROL IRP and sends it down the disk driver stack, which answers with a 2000.4 GB disk and 512-byte sectors.
The most interesting part is in the first lines. The code 0x000700A0 isn't an arbitrary number: it's the CTL_CODE macro packed together, and the program unpacks it. DeviceType 0x7 is the disk type; Function 0x28 is the specific operation; Method 0 is METHOD_BUFFERED; and Access 0 is FILE_ANY_ACCESS, which is precisely what lets us request it with a handle opened with access 0. We'll see what those methods mean in a moment, because it's the same thing a driver defines when it creates its own codes.
The dispatch table#
How does the driver know which function to call when an IRP arrives? Through its dispatch table. DRIVER_OBJECT.MajorFunction is an array of function pointers indexed by request type, IRP_MJ_*, and DriverEntry fills it in. Another fragment from my guide:
NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject,
PUNICODE_STRING RegistryPath) {
DriverObject->MajorFunction[IRP_MJ_CREATE] = MyCreateClose;
DriverObject->MajorFunction[IRP_MJ_CLOSE] = MyCreateClose;
DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = MyDeviceControl;
DriverObject->DriverUnload = MyUnload;
// ... IoCreateDevice and IoCreateSymbolicLink (see below) ...
return STATUS_SUCCESS;
}Entries you don't assign fail the request by default. And my guide insists on the order: the table is filled in before calling IoCreateDevice, so the device never exists with a half-filled table.
Custom IOCTLs#
When a driver needs operations that don't fit reading or writing, it defines its own IOCTLs with the same macro we just unpacked:
#define IOCTL_MY_DEVICE_DO_THING \
CTL_CODE(FILE_DEVICE_UNKNOWN, 0x800, METHOD_BUFFERED, FILE_ANY_ACCESS)The third argument, the transfer method, decides how data travels between user mode and the driver:
METHOD_BUFFERED: the I/O Manager copies the data into a system buffer. It's the recommended one, and the one the disk driver uses in our example.METHOD_IN_DIRECTandMETHOD_OUT_DIRECT: the data is described with an MDL. Meant for large transfers.METHOD_NEITHER: the driver receives raw user pointers and has to validate everything by hand. It's rarely used, and for good reason.
Never trust the size or the contents of a buffer coming from user mode, whatever the method. It's the same idea we saw with syscalls: the kernel trusts nothing that comes from Ring 3.
Synchronization: can you spot the bug?#
A driver serves requests from several threads and several cores at once, so it needs to protect its shared data. It has two main tools, and IRQL decides which one you can use:
- Spinlock: acquired at
DISPATCH_LEVELor below, and it raises you toDISPATCH_LEVELwhile you hold it. If it's taken, you wait actively by spinning, so it has to be held for as short a time as possible. - Mutex: waiting on it requires
APC_LEVELat most, and in practicePASSIVE_LEVEL. If it's taken, the thread sleeps until it's released.
With that, this fragment from my guide is a challenge. Take a good look before reading on:
VOID MyDpcRoutine(PKDPC Dpc, PVOID Context, PVOID Arg1, PVOID Arg2) {
KeAcquireSpinLock(&g_DeviceLock, &oldIrql);
// Shared resource ALSO used by an IOCTL handler
KeWaitForSingleObject(&g_ConfigMutex, Executive, KernelMode,
FALSE, NULL);
UpdateSharedConfig();
KeReleaseMutex(&g_ConfigMutex, FALSE);
KeReleaseSpinLock(&g_DeviceLock, oldIrql);
}See it? A DPC already runs at DISPATCH_LEVEL, and on top of that it holds a spinlock. Waiting on a dispatcher object, such as the mutex, at that IRQL, with anything but a zero timeout (here it's unbounded), is a documented fatal error: an immediate bug check. It makes perfect sense if you remember the table: at DISPATCH_LEVEL there's no thread scheduling, so nothing can put this thread to sleep or wake it up when the mutex becomes free.
The fix depends on who touches the data:
- If both the DPC and the IOCTL handler touch it, protect it with the same spinlock in both places, and the mutex goes away.
- If it should only be touched at
PASSIVE_LEVEL, move that work out of the DPC with a work item, which the system runs later on a thread atPASSIVE_LEVEL.
Lifecycle: create and unload#
For a program to talk to the driver, the driver has to create a device. It does so with IoCreateDevice, whose key parameters are the size of the device extension (the driver's own memory for that device), a name of the form \Device\…, the device type and FILE_DEVICE_SECURE_OPEN. Then IoCreateSymbolicLink creates a symbolic link so that user mode can open it with CreateFile.
With one caveat: Microsoft's documentation recommends that production drivers use IoRegisterDeviceInterface, with an interface class identified by a GUID. The symbolic link is the usual choice in guides and simple drivers.
On unload, DriverUnload undoes everything in reverse order: first it deletes the symbolic link, then the device, and it frees everything it allocated. In the kernel there's no process to close: a leak lasts until reboot.
How it's really done#
All of the above explains why driver development has its own way of working. My lab guide organizes it like this:
- Never on your main machine. You work in a test virtual machine.
- Test-signing in that VM, so you can load your test drivers. It's blocked if the VM has Secure Boot enabled.
- Two-machine debugging. A bug check also kills any debugger running on the same machine, so WinDbg connects from outside: over the VM's serial pipe or over the network with KDNET.
- Symbols from Microsoft's public server, so call stacks show names and not just addresses.
- Driver Verifier (
verifier.exe), which stresses the driver on purpose so memory errors, leaks and IRQL violations show up in the lab and not in production. Only in the VM. - Kernel memory dump enabled and automatic restart disabled, so you can read the blue screen and analyze it afterwards.
- Snapshots. When the VM breaks, you go back to the last snapshot instead of trying to rescue it.
I wrote both guides, the driver fundamentals one and the lab one, for my own lab, where I build drivers with Visual Studio Build Tools 2022 and the WDK 10.0.26100. If I had to keep just one of the lessons that come up most often in them, it would be this: frequent crashes are a normal and expected part of driver development. They're not a failure if the lab is ready for them.
There's no safety net in the kernel#
If one idea ties all of the above together, it's that there's no safety net in the kernel. In user mode, a bad pointer closes your program; in Ring 0, it takes down the system. That's why the rules in this post aren't a matter of style: respecting IRQL, completing every IRP exactly once and validating every buffer that comes from user mode is what separates a driver from a blue screen.
If you want to see where all this fits in the CPU architecture, the rings series starts at From Ring 3 to Ring 0, goes down to the hypervisor in Ring -1 and ends in the firmware, in Ring -2.
References
- Writing a DriverEntry RoutineMicrosoft · learn.microsoft.com
- Managing Hardware PrioritiesMicrosoft · learn.microsoft.com
- Bug Check 0xA: IRQL_NOT_LESS_OR_EQUALMicrosoft · learn.microsoft.com
- Bug Check 0xD1: DRIVER_IRQL_NOT_LESS_OR_EQUALMicrosoft · learn.microsoft.com
- I/O Request PacketsMicrosoft · learn.microsoft.com
- Defining I/O Control CodesMicrosoft · learn.microsoft.com
- Buffer Descriptions for I/O Control CodesMicrosoft · learn.microsoft.com
- DeviceIoControl function (ioapiset.h)Microsoft · learn.microsoft.com
- IOCTL_DISK_GET_DRIVE_GEOMETRY_EXMicrosoft · learn.microsoft.com
- Driver VerifierMicrosoft · learn.microsoft.com
Share
Does your project need to go below the application layer?
Systems software, performance and security on Windows and Linux: diagnostics, custom tooling and low-level code review.
Let's talk→
Comments
Commenting requires a GitHub account. Comments live in GitHub Discussions (SoftDryzz/blog-comments) and are moderated: no promotional links.