Writing a device driver for Windows

http://www.adp-gmbh.ch/win/misc/writing_devicedriver.html

Ren Nyffenegger's collection of things on the web

Ren Nyffenegger on Oracle - Most wanted - Feedback

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'

1 de 6

09 de may de 2011 07:13 a.m.

Writing a device driver for Windows

http://www.adp-gmbh.ch/win/misc/writing_devicedriver.html

typedef struct _KAMEL_DRIVER_EXTENSION { char buffer[BUFFERSIZE]; } KAMEL_DRIVER_EXTENSION, *PKAMEL_DRIVER_EXTENSION; KAMEL_DRIVER_EXTENSION* driverExtension=0; NTSTATUS NTSTATUS NTSTATUS NTSTATUS NTSTATUS NTSTATUS NTSTATUS VOID DriverEntry (IN CreateCamel (IN ReadCamel (IN WriteCamel (IN ShutdownCamel(IN CleanupCamel (IN IoCtlCamel (IN CmlUnload (IN PDRIVER_OBJECT PDEVICE_OBJECT PDEVICE_OBJECT PDEVICE_OBJECT PDEVICE_OBJECT PDEVICE_OBJECT PDEVICE_OBJECT PDRIVER_OBJECT DriverObject, IN DeviceObject, IN DeviceObject, IN DeviceObject, IN DeviceObject, IN DeviceObject, IN DeviceObject, IN DriverObject); PUNICODE_STRING RegistryPath); PIRP Irp); PIRP Irp); PIRP Irp); PIRP Irp); PIRP Irp); PIRP Irp);

#ifdef ALLOC_PRAGMA #pragma alloc_text(INIT, #pragma alloc_text(PAGE, #pragma alloc_text(PAGE, #pragma alloc_text(PAGE, #pragma alloc_text(PAGE, #pragma alloc_text(PAGE, #pragma alloc_text(PAGE, #endif

DriverEntry) CreateCamel) ReadCamel) WriteCamel) ShutdownCamel) IoCtlCamel) CmlUnload)

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] DriverObject->MajorFunction[IRP_MJ_READ] DriverObject->MajorFunction[IRP_MJ_WRITE] DriverObject->MajorFunction[IRP_MJ_SHUTDOWN] DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] 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); = = = = = CreateCamel; ReadCamel; WriteCamel; ShutdownCamel; IoCtlCamel;

2 de 6

09 de may de 2011 07:13 a.m.

Writing a device driver for Windows

http://www.adp-gmbh.ch/win/misc/writing_devicedriver.html

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); }

3 de 6

09 de may de 2011 07:13 a.m.

Writing a device driver for Windows

http://www.adp-gmbh.ch/win/misc/writing_devicedriver.html

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 UNICODE_STRING linkString; DriverObject) {

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.

4 de 6

09 de may de 2011 07:13 a.m.

Writing a device driver for Windows

http://www.adp-gmbh.ch/win/misc/writing_devicedriver.html

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 Severity SymbolicName Language Driver Entry . MessageID Severity SymbolicName Language Create . = = = = = = = = 1 Informational MSG_DRIVER_ENTRY English 2 Informational MSG_CREATE English

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 Packet->UniqueErrorValue Packet->RetryCount Packet->SequenceNumber Packet->IoControlCode Packet->DumpDataSize = = = = = = ErrorCode; 0, 0; 0; 0; 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)

5 de 6

09 de may de 2011 07:13 a.m.

Writing a device driver for Windows

http://www.adp-gmbh.ch/win/misc/writing_devicedriver.html

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.

6 de 6

09 de may de 2011 07:13 a.m.