PCI 5 - PCI software driver for Windows
Now that we need a driver for our PCI card, there are two ways to get it.
Check out WinDriver.
That's a commercial toolkit that can build a PCI plug-and-play driver solution for you in minutes.
It works like that:
Windriver may be nice, but at $2000, that's expensive if all you want to do is experiment with PCI plug-and-play mechanisms.
The DDKs are easy to install. For Win98 and Win2000 DDKs, first install Visual C++ 5.0 or 6.0, then the DDK itself. Then following the "install.htm" instructions to build a few sample drivers using the "build" command.
Since it's a WDM driver, it works in WinXP/2000/98.
The entry point of a WDM driver is a "DriverEntry" function (like the "main" of a C program).
Its main purpose is to publish addresses of callback functions. Our minimum driver just needs 2.
A WDM driver creates at least one "device" (if your PC has multiple similar items, the same WDM driver may create multiple devices). Before the driver can create a device, we need a "Device Extension" structure. The structure is used by each device to store information. We can make it as big as we want, and a typical device will store many fields in there. Our minimum device just needs one field.
What is this "NextStackDevice" for? a WDM implementation detail...
WDM devices process IRPs ("I/O Request Packets", create/read/write/close...). WDM devices don't work alone but are assembled in logical "stacks" of devices. IRP requests are sent along the stack and are processed on the way. Stacks are created from bottom to top (bottom=hardware layers, top=logical layers). When a stack is created, each device attaches itself to the device just below. A device typically stores the info about the device just below himself in the Device Extension, so that later, it can forward along IRP requests. A device doesn't really know where it is in the stack, it just processes or forwards requests as they are coming.
Anyway, now we can implement DevicePCI_AddDevice.
It creates a device object and attaches the device to the device stack.
Finally we can process the Plug-and-Play IRP requests.
Our minimum device processes only START_DEVICE and REMOVE_DEVICE requests.
The START_DEVICE request is the one where we accept or refuse the memory resources. Here we don't do anything but forward the request down the stack, where it is always accepted.
Now, our device gets some memory resources, but doesn't do anything with them.
To be more useful, the driver would need to:
You can get more sample code by studying the "portio" project in the Windows 2000 DDK for example.
The easy way
The easy way consists on having someone else doing the hard work for you!Check out WinDriver.
That's a commercial toolkit that can build a PCI plug-and-play driver solution for you in minutes.
It works like that:
- You run a wizard that detects your plug-and-play devices, including the PCI cards.
- You select your card of interest, give a name to your device and create an ".inf" file.
- That's enough for Windows to be able to recognize the hardware and convince him that it should use WinDriver's driver. You quit the wizard, and go through Window's plug-and-play hardware detection to install the driver.
- Once the driver is installed, you run the wizard again, this time to build some example source code to access the PCI card.
Windriver may be nice, but at $2000, that's expensive if all you want to do is experiment with PCI plug-and-play mechanisms.
The hard way
Installing Windows DDK
The latest Windows DDKs releases are not free, while earlier incarnations (98/2000) were free to download.The DDKs are easy to install. For Win98 and Win2000 DDKs, first install Visual C++ 5.0 or 6.0, then the DDK itself. Then following the "install.htm" instructions to build a few sample drivers using the "build" command.
A minimum WDM Plug-and-Play driver
Here's the very minimum code required for Windows device manager to allocate the memory resource used by our PCI card.Since it's a WDM driver, it works in WinXP/2000/98.
The entry point of a WDM driver is a "DriverEntry" function (like the "main" of a C program).
Its main purpose is to publish addresses of callback functions. Our minimum driver just needs 2.
|
NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath) { DriverObject->DriverExtension->AddDevice = DevicePCI_AddDevice; DriverObject->MajorFunction[IRP_MJ_PNP] = DevicePCI_PnP; return STATUS_SUCCESS; } |
A WDM driver creates at least one "device" (if your PC has multiple similar items, the same WDM driver may create multiple devices). Before the driver can create a device, we need a "Device Extension" structure. The structure is used by each device to store information. We can make it as big as we want, and a typical device will store many fields in there. Our minimum device just needs one field.
|
typedef struct { PDEVICE_OBJECT NextStackDevice; } DevicePCI_DEVICE_EXTENSION, *PDevicePCI_DEVICE_EXTENSION; |
What is this "NextStackDevice" for? a WDM implementation detail...
WDM devices process IRPs ("I/O Request Packets", create/read/write/close...). WDM devices don't work alone but are assembled in logical "stacks" of devices. IRP requests are sent along the stack and are processed on the way. Stacks are created from bottom to top (bottom=hardware layers, top=logical layers). When a stack is created, each device attaches itself to the device just below. A device typically stores the info about the device just below himself in the Device Extension, so that later, it can forward along IRP requests. A device doesn't really know where it is in the stack, it just processes or forwards requests as they are coming.
Anyway, now we can implement DevicePCI_AddDevice.
It creates a device object and attaches the device to the device stack.
|
NTSTATUS DevicePCI_AddDevice(PDRIVER_OBJECT DriverObject, PDEVICE_OBJECT pdo) { // Create the device and allocate the "Device Extension" PDEVICE_OBJECT fdo; NTSTATUS status = IoCreateDevice(DriverObject, sizeof(DevicePCI_DEVICE_EXTENSION), NULL, FILE_DEVICE_UNKNOWN, 0, FALSE, &fdo); if(!NT_SUCCESS(status)) return status; // Attach to the driver below us PDevicePCI_DEVICE_EXTENSION dx = (PDevicePCI_DEVICE_EXTENSION)fdo->DeviceExtension; dx->NextStackDevice = IoAttachDeviceToDeviceStack(fdo, pdo); fdo->Flags &= ~DO_DEVICE_INITIALIZING; return STATUS_SUCCESS; } |
Finally we can process the Plug-and-Play IRP requests.
Our minimum device processes only START_DEVICE and REMOVE_DEVICE requests.
|
NTSTATUS DevicePCI_PnP(PDEVICE_OBJECT fdo, PIRP IRP) { PDevicePCI_DEVICE_EXTENSION dx = (PDevicePCI_DEVICE_EXTENSION)fdo->DeviceExtension; PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(IRP); ULONG MinorFunction = IrpStack->MinorFunction; switch(MinorFunction) { case IRP_MN_START_DEVICE: // we should check the allocated resource... break; case IRP_MN_REMOVE_DEVICE: status = IRP_NotCompleted(fdo, IRP); if(dx->NextStackDevice) IoDetachDevice(dx->NextStackDevice); IoDeleteDevice(fdo); break; } // call the device below us IoSkipCurrentIrpStackLocation(IRP); return IoCallDriver(dx->NextStackDevice, IRP); } |
The START_DEVICE request is the one where we accept or refuse the memory resources. Here we don't do anything but forward the request down the stack, where it is always accepted.
Now, our device gets some memory resources, but doesn't do anything with them.
To be more useful, the driver would need to:
- Check the memory resources before accepting them
- Export a device name
- Implement some "DeviceIOcontrol" to communicate with a Win32 application
- Handle more IO requests ("IRP")
- ...
You can get more sample code by studying the "portio" project in the Windows 2000 DDK for example.
Links
- Jungo's WinDriver toolkit
- Examples of NT4 style drivers: Kamel from ADP GmbH, DumpPCI from Microsoft
- Programming the Microsoft Windows driver model book from Walter Oney
