Windows API Reference

Documentation for Windows Driver Kit (WDK) APIs

Drivers

This section provides detailed documentation for the APIs and concepts related to developing device drivers for the Windows operating system. Drivers are essential software components that enable the operating system to interact with hardware devices.

Introduction to Windows Drivers

Developing drivers for Windows requires a deep understanding of the operating system's architecture, memory management, and concurrency models. The Windows Driver Kit (WDK) provides the tools, libraries, and header files necessary for driver development.

Drivers operate in kernel mode, giving them privileged access to hardware and system resources. This power comes with significant responsibility; bugs in drivers can lead to system instability and security vulnerabilities.

Driver Models

Microsoft offers different frameworks to simplify driver development:

WDF (Windows Driver Frameworks)

WDF is the recommended framework for most driver development. It abstracts many low-level details of the Windows Driver Model (WDM), providing a more object-oriented and event-driven programming model. WDF consists of two branches:

  • KMDF (Kernel-Mode Driver Framework): For kernel-mode drivers.
  • UMDF (User-Mode Driver Framework): For user-mode drivers.

Key WDF concepts include Framework Objects (like framework devices, I/O queues, and I/O targets) and request objects.

WDM (Windows Driver Model)

WDM is the foundational driver model for Windows. While more complex than WDF, it offers maximum flexibility and control. Most kernel-mode drivers interact directly with the Windows Executive and I/O Manager through WDM structures and routines.

Core WDM components include device objects, driver objects, and I/O Request Packets (IRPs).

Core Driver APIs and Concepts

Understanding these fundamental elements is crucial for any Windows driver developer:

I/O Manager

The I/O Manager is a core component of the Windows Executive that handles I/O operations. It routes I/O requests from applications to the appropriate drivers.

Key routines include:

  • IoCreateDevice
  • IoCreateSymbolicLink
  • IoGetIoControlCode

Device Objects

A device object (DEVICE_OBJECT) represents a physical or logical device to the I/O Manager. Drivers create device objects to identify and manage the devices they control.

Key structures:

  • DEVICE_OBJECT
  • DRIVER_OBJECT

IRPs (I/O Request Packets)

An IRP (IRP) is a data structure used by the I/O Manager to pass I/O requests down the driver stack. Drivers process IRPs for operations like creating/closing the device, reading/writing data, and device control codes.

Common IRP major functions:

  • IRP_MJ_CREATE
  • IRP_MJ_READ
  • IRP_MJ_WRITE
  • IRP_MJ_DEVICE_CONTROL
  • IRP_MJ_CLOSE
  • IRP_MJ_CLEANUP

Example IRP processing snippet:


NTSTATUS DispatchRead(PDEVICE_OBJECT DeviceObject, PIRP Irp) {
    PIO_STACK_LOCATION irpSp = IoGetCurrentIrpStackLocation(Irp);
    ULONG length = irpSp->Parameters.Read.Length;
    // ... handle read operation ...
    Irp->IoStatus.Status = STATUS_SUCCESS;
    Irp->IoStatus.Information = bytesRead;
    IoCompleteRequest(Irp, IO_NO_INCREMENT);
    return STATUS_SUCCESS;
}

DPCs and SRBs

Deferred Procedure Calls (DPCs) are routines that execute at a high interrupt request level (IRQL), allowing time-consuming tasks to be deferred from interrupt service routines (ISRs).

Scsi Request Blocks (SRBs) are used by storage drivers to communicate with the system's storage stack.

Types of Drivers

Drivers can be categorized based on their role:

Filter Drivers

Filter drivers intercept I/O requests directed to another driver. They can modify requests, add functionality, or provide logging.

Function Drivers

Function drivers are responsible for the primary operation of a device.

Bus Drivers

Bus drivers manage hardware buses (e.g., PCI, USB) and enumerate devices attached to them.

Kernel-Mode vs. User-Mode Drivers

Kernel-Mode Drivers: Run in the privileged kernel mode. They have direct access to hardware and system services. Examples include graphics drivers, network drivers, and storage drivers.

User-Mode Drivers: Run in the less privileged user mode. This enhances system stability as driver errors are less likely to crash the entire system. UMDF is used for developing these drivers. Examples include drivers for some USB devices and cameras.

Security Considerations

Driver security is paramount. Developers must:

  • Validate all inputs to prevent buffer overflows and other vulnerabilities.
  • Use appropriate IRQLs and synchronization mechanisms to avoid race conditions.
  • Handle errors gracefully and avoid exposing sensitive system information.
  • Adhere to Microsoft's security best practices for driver development.

Further Reading