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
Allocating Pool Memory
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;
}
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.
|