Kernel to User Notification

Windows Driver Kit: WDM Devices

Event - Kernel to User Notification

Description

The Event sample is a legacy style (non-WDM) sample that demonstrates two different ways that a Microsoft Windows NT kernel-mode driver can notify an application about a hardware event. One is an event-based method and the other is an IRP-based method. Because the sample driver is not talking to any real hardware, it uses a timer DPC to simulate hardware events. The test application informs the driver whether it wants to be notified by signaling an event or by completing the pending IRP and also gives a relative time at which the DPC timer has to fire.

Theory of Operation

Event-based approach: The application creates an event by using CreateEvent(). It then passes the event handle to the driver in a private IOCTL_REGISTER_EVENT IOCTL. Because the driver is a monolithic top-level driver, its IRP dispatch routines run in the application process context and as a result the event handle is still valid in the driver. The driver dereferences the user-mode handle into system space and saves the event object pointer for later use and queues a custom timer DPC. When the DPC fires, the driver signals the event through KeSetEvent() at DISPATCH_LEVEL and deletes the references to the event object. You cannot use this approach if your driver is not a monolithic top-level driver, because you cannot guarantee the process context in a multi-level driver stack if you are not at the top.

 

Pending IRP based approach: The application makes a synchronous IOCTL_REGISTER_EVENT IOCTL request. The driver marks the device I/O control IRP pending and queues a timer DPC and returns STATUS_PENDING. When the timer fires to indicate a hardware event, the driver completes the pending IRP to notify the application about the hardware event.

 

There are two advantages of this method over the event-based approach. One is that you can send a message to the application along with your notification and other one is that the driver routines do not have to be in the context of the process that made the request. The application can do a synchronous or asynchronous (overlapped) ioctl to the driver.

Building the Sample

1. Click the free or checked build environment icon under Development Kits program group to set basic environment variables.
2. Change to the directory that contains the device source code, such as CD Src\General\Event.
3. Run build -ceZ, or use the macro BLD. This command invokes the Microsoft make routines to build the components. If the build succeeds, you will find the driver, event.sys, and the test application, event.exe, in the i386 subdirectory of the %TARGETPATH% directory specified in the Sources file. If it fails, you will find errors and warnings in the buildxxx.err and buildxxx.wrn files respectively, where xxx is either chk or fre depending on the build environment.

Installation

General

To install this driver, copy the test app, event.exe, and the driver, event.sys, to a directory on the test machine and run the application. The application will automatically load the driver if it's not already loaded and interact with the driver. When you exit the application, the driver will be stopped, unloaded and the service information about the driver will be removed from the registry.

Code Tour

File Manifest

File	Description
Sys	Contains source code of driver
Exe	Contains source code of test application