Writing a device driver for Windows

In order to write a device driver for windows, one needs the device driver development kit (ddk) and a c compiler.

According to this article, a device driver's maximum size is 960MB on Windows XP (100MB on NT4, 220MB on Win2K).

Setting up the environment

A proper environment must be setup. Use setenv (which ships with the ddk) to set the environment variables (and what not) to build a driver:

C:\>programme\ntddk\bin\setenv \programme\ntddk.

The argument that is given to setenv must point to the directory under which the ddk is installed.

makefile

The directory that contains the sources for the device driver must have a file called makefile and another file called sources. For a simple device driver, it is sufficient to have one single line in the makefile:

!INCLUDE $(NTMAKEENV)\makefile.def

sources

This file actually contains the names of the files to be compiled:

TARGETNAME=kamel
TARGETPATH=obj
TARGETTYPE=DRIVER

SOURCES=kamel.c writeEvent.c kamelMsg.rc

C_DEFINES=-DUNICODE -DSTRICT

kamel.c is the code for the driver itself, writeEvent.c contains a function that can be called to write messages to the system event log (see below) and kamelMsg.rc contains the strings that are written

Writing the driver

I call the driver we're going to write Kamel. In german, this will then be called Kameltreiber which is a pun german speaking people will understand. So, we're creating (according to the sources file) a file called kamel.c. The first lines contain the includes we need:

#include "ntddk.h"
#include "writeEvent.h"
#include "kamelMsg.h"

ntddk.h must always be included, writeEvent.h contains the declaration of WriteEvent (which is a function to write events, of course) and kamelMsg.h (being created by the message compiler) contains the identifiers of the strings we want to write using WriteEvent.

Each driver needs a DriverEntry function which is called when the driver is loaded:

Now, we use write the forward declarations together with the pragmas alloc_text. They indicate wheather or not the function is pageable.

#define BUFFERSIZE 1024
#define BUFFERTAG  'kmlb'

typedef struct _KAMEL_DRIVER_EXTENSION {
  char buffer[BUFFERSIZE];
} KAMEL_DRIVER_EXTENSION, *PKAMEL_DRIVER_EXTENSION;

KAMEL_DRIVER_EXTENSION* driverExtension=0;


NTSTATUS DriverEntry  (IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPath);
NTSTATUS CreateCamel  (IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp);
NTSTATUS ReadCamel    (IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp);
NTSTATUS WriteCamel   (IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp);
NTSTATUS ShutdownCamel(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp);
NTSTATUS CleanupCamel (IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp);
NTSTATUS IoCtlCamel   (IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp);
VOID     CmlUnload    (IN PDRIVER_OBJECT  DriverObject);


#ifdef ALLOC_PRAGMA
#pragma alloc_text(INIT, DriverEntry)
#pragma alloc_text(PAGE, CreateCamel) 
#pragma alloc_text(PAGE, ReadCamel) 
#pragma alloc_text(PAGE, WriteCamel) 
#pragma alloc_text(PAGE, ShutdownCamel)
#pragma alloc_text(PAGE, IoCtlCamel)
#pragma alloc_text(PAGE, CmlUnload)
#endif

NTSTATUS DriverEntry(IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPath) {

  UNICODE_STRING nameString, linkString;
  PDEVICE_OBJECT deviceObject;
  NTSTATUS status;

  WriteEvent(MSG_DRIVER_ENTRY,DriverObject,NULL);

  RtlInitUnicodeString(&nameString, L"\\Device\\Kamel");

  status = IoCreateDevice(
    DriverObject, 
    sizeof(65533),
    &nameString, 
    0, //FILE_DEVICE_UNKNOWN,
    0, 
    FALSE, 
    &deviceObject);

  if (!NT_SUCCESS(status))
    return status;


  deviceObject->Flags |= DO_DIRECT_IO;
  deviceObject->Flags &= ~DO_DEVICE_INITIALIZING;


  RtlInitUnicodeString(&linkString, L"\\DosDevices\\Kamel");
  status = IoCreateSymbolicLink (&linkString, &nameString);

  if (!NT_SUCCESS(status)) {
    IoDeleteDevice (DriverObject->DeviceObject);
    return status;
  }


  DriverObject->MajorFunction[IRP_MJ_CREATE]         = CreateCamel;
  DriverObject->MajorFunction[IRP_MJ_READ]           = ReadCamel;
  DriverObject->MajorFunction[IRP_MJ_WRITE]          = WriteCamel;
  DriverObject->MajorFunction[IRP_MJ_SHUTDOWN]       = ShutdownCamel;
  DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = IoCtlCamel;
  
  DriverObject->DriverUnload=CmlUnload;

  // ExAllocatePool is obsolete and ExAllocatePoolWithTag should be used.
  driverExtension = ExAllocatePool(NonPagedPool, sizeof (KAMEL_DRIVER_EXTENSION));

  if(!driverExtension) {
    WriteEvent(MSG_NO_IOALLOCATEDRIVEROBJECTEXTENSION, DriverObject, NULL);
    return STATUS_INSUFFICIENT_RESOURCES;
  }

  RtlZeroMemory(driverExtension->buffer, BUFFERSIZE);

  RtlCopyBytes (driverExtension->buffer, "123456789012345", 16);

  return STATUS_SUCCESS;
}

DriverEntry first writes an Event (using WriteEvent, explained later) so it can be verified that DriverEntry indeed was called. Then, the actual device is created using IoCreateDevice and initialized.

Setting Up Major Functions

An Application communicates with a driver with the driver's Major Functions. These are set in the drivers array of function pointers MajorFunction.

User Visible Name for the driver

In order to create a user-visible name for the device just created, IoCreateSymbolicLink is called.

Allocating Pool Memory

The driver allocates some Pool Memory with ExAllocatePool.

By the way, Paged and Non-Paged Pool Memory sized can be adjusted with the registry keys HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\(Non)PagedPoolSize. The Value specified is the size in bytes.

Programming the Major Functions

In DriverEntry, the Major Functions IRP_MJ_CREATE, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_SHUTDOWN, IRP_MJ_DEVICE_CONTROL were set. Here are the actual functions they point to:

IRP_MJ_CREATE

This function is called when a file using this deivce is created. In Win32Api, Devices are opened using CreateFile which then routes in the function associated with IRP_MJ_CREATE.

NTSTATUS CreateCamel (IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp) {
  WriteEvent(MSG_CREATE,(PVOID)DeviceObject,NULL);

  IoCompleteRequest(Irp,IO_NO_INCREMENT);
  return  STATUS_SUCCESS;
}

IRP_MJ_READ

NTSTATUS ReadCamel(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp) {
  PUCHAR                      currentAddress;
  PIO_STACK_LOCATION          irpStack;

  WriteEvent(MSG_READ,DeviceObject,NULL);

  if (!driverExtension) {
    WriteEvent(MSG_DRIVEREXTISNULLINREAD,DeviceObject,NULL);
    IoCompleteRequest(Irp, IO_NO_INCREMENT);
    return STATUS_INSUFFICIENT_RESOURCES;
  }
  irpStack = IoGetCurrentIrpStackLocation(Irp);

  if (irpStack->MajorFunction == IRP_MJ_READ) {
    currentAddress = MmGetSystemAddressForMdlSafe(Irp->MdlAddress, NormalPagePriority);

    if (!currentAddress) {
      WriteEvent(MSG_MMGETSYSTEMADDRESS,DeviceObject,NULL);
      IoCompleteRequest(Irp, IO_NO_INCREMENT);
      return STATUS_SUCCESS;
    }
    RtlMoveMemory(currentAddress, 
    driverExtension->buffer+irpStack->Parameters.Read.ByteOffset.LowPart,
    irpStack->Parameters.Read.Length);
  }
  else {
    WriteEvent(MSG_MAJORFUNC_NOT_READ,DeviceObject,NULL);
  }

  IoCompleteRequest(Irp, IO_NO_INCREMENT);
  return STATUS_SUCCESS;
}

A driver should call IoGetCurrentIrpStackLocation in its IRP function to receive a pointer to a IO_STACK_LOCATION structure.

MmGetSystemAddressForMdlSafe is a macro. It returns a virtual address to non system-space for the buffer described by the MDL.

RtlMoveMemory

IRP_MJ_WRITE

NTSTATUS WriteCamel(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp) {
  PUCHAR                      currentAddress;
  PIO_STACK_LOCATION          irpStack;

  if (!driverExtension) {
    IoCompleteRequest(Irp, IO_NO_INCREMENT);
    return STATUS_INSUFFICIENT_RESOURCES;
  }

  irpStack = IoGetCurrentIrpStackLocation(Irp);

  if (irpStack->MajorFunction == IRP_MJ_WRITE) {
    currentAddress = MmGetSystemAddressForMdlSafe(Irp->MdlAddress, NormalPagePriority);

    if (!currentAddress) {
      IoCompleteRequest(Irp, IO_NO_INCREMENT);
      return STATUS_SUCCESS;
    }

    RtlMoveMemory(driverExtension->buffer+irpStack->Parameters.Write.ByteOffset.LowPart,
        currentAddress, irpStack->Parameters.Write.Length);
  }
  else {
    WriteEvent(MSG_MAJORFUNC_NOT_READ,DeviceObject,NULL);
  }

  IoCompleteRequest(Irp, IO_NO_INCREMENT);
  return STATUS_SUCCESS;
}

IRP_MJ_SHUTDOWN

NTSTATUS ShutdownCamel(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp) {
  WriteEvent(MSG_SHUTDOWN,DeviceObject,NULL);
  IoCompleteRequest(Irp, IO_NO_INCREMENT);
  return STATUS_SUCCESS;
}

IRP_MJ_DEVICE_CONTROL

NTSTATUS IoCtlCamel(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp) {
  WriteEvent(MSG_IOCTL,DeviceObject,NULL);
  IoCompleteRequest(Irp, IO_NO_INCREMENT);
  return STATUS_SUCCESS;
}

The unload function

VOID CmlUnload (IN PDRIVER_OBJECT  DriverObject) {
  UNICODE_STRING linkString;

  WriteEvent(MSG_DRIVERUNLOAD, DriverObject, NULL);
  ExFreePool(driverExtension);
  RtlInitUnicodeString (&linkString, L"\\DosDevices\\Kamel");
  IoDeleteSymbolicLink (&linkString);
  IoDeleteDevice(DriverObject->DeviceObject);
}

Writing Events from a Device Driver

It is possible to write strings from the driver into the system event box (which then can be viewed with the event viewer (eventvwr.exe). It is not straight forward however and the following steps must each be done.

The Message File

First, a message file must be created, having the suffix .mc, that contains each possible string you want to output and also assignes a unique id to these strings. A sample is given here:

MessageID    = 1
Severity     = Informational
SymbolicName = MSG_DRIVER_ENTRY
Language     = English
Driver Entry
.
MessageID    = 2
Severity     = Informational
SymbolicName = MSG_CREATE
Language     = English
Create
.

Each Entry must be followed by a single dot on its own line. In this sample, the unique Id is associated with the symbolic name MSG_DRIVER_ENTRY and the String "Driver Entry". If you take a look at DriverEntry above, you'll see that I call WriteEvent with the symbolic name MSG_DRIVER_ENTRY.

The Message File then is to be compiled with the message compiler mc: mc KamelMsg.mc on the command line. This produces a file called MessageFile.rc. KamelMsg.rc must be included in the sources file. It also creates the file KamelMsg.h which must be included to have the constants.

This is still not sufficient. Also a string entry must be created in the Registry under HKLM\SYSTEM\CurrentControlSet\Services\Eventlog\System\<driverName>\EventMessageFile. The string must point to the .dll or .sys into which the messages were compiled, in our case: %SystemRoot%\System32\Drivers\Kamel.sys

WriteEvent

BOOLEAN WriteEvent(IN NTSTATUS ErrorCode , IN PVOID IoObject,IN PIRP Irp) {
  PIO_ERROR_LOG_PACKET Packet;
  PIO_STACK_LOCATION IrpStack;
  PWCHAR pInsertionString;
  STRING AnsiInsertString;
  UNICODE_STRING UniInsertString;

  UCHAR PacketSize;

  PacketSize = sizeof(IO_ERROR_LOG_PACKET);

  Packet = IoAllocateErrorLogEntry(IoObject,PacketSize);
  if (Packet == NULL) return FALSE;

  Packet->ErrorCode         = ErrorCode;
  Packet->UniqueErrorValue  = 0,
  Packet->RetryCount        = 0;
  Packet->SequenceNumber    = 0;
  Packet->IoControlCode     = 0;
  Packet->DumpDataSize      = 0;
  
  if (Irp!=NULL) {
     IrpStack=IoGetCurrentIrpStackLocation(Irp);
     Packet->MajorFunctionCode = IrpStack->MajorFunction;
     Packet->FinalStatus = Irp->IoStatus.Status;
  } 
  else {
     Packet->MajorFunctionCode = 0;
     Packet->FinalStatus       = 0;
  }

  IoWriteErrorLogEntry(Packet);
  return TRUE;
}

WriteEvent.h

BOOLEAN WriteEvent(IN NTSTATUS ErrorCode , IN PVOID IoObject,IN PIRP Irp); 
#pragma alloc_text(PAGE, WriteEvent)

Entries in the registry

The driver must be registred with the registry: Create a this key HKLM\System\CurrentControlSet\Services\<driverName> and add the following keys: ErrorControl, Group, Start, Tag and Type.


	René Nyffenegger's collection of things on the web
	René Nyffenegger on Oracle - Most wanted - Feedback - Follow @renenyffenegger