开发者社区> andyro1984> 正文

A simple demo for WDM Driver development

简介: Introduction A lot of articles have been investigating in application layer issues, like skin-based dialogs, MFC, ATL, thread, process, registry etc.
+关注继续查看

Introduction

A lot of articles have been investigating in application layer issues, like skin-based dialogs, MFC, ATL, thread, process, registry etc. It won't be easy to find any driver related articles posted with full source code. The root cause is that most drivers are developed for specific hardware. Without the domain knowledge, you will never want to get in touch with it. I believe a lot of software engineers are afraid when they involve in kernel mode programming for the very first time, and there are not too much resources that can guide them through the whole process from DDK study to program stage. Hence I decided to share some of my experiences in driver programming in Windows. This demo focuses on a quick introduction to WDM Driver's architecture, and will introduce two I/O modes coming with Windows, which are Direct I/O and Buffered I/O, how to communicate with drivers residing in system kernel space, and read/write data to it.

There is no need for you to read the demo program with any hardware related background, the demo drivers are all pseudo drivers. That's drivers installed without a physical device in computer.

The member functions defined in this demo program can be used as templates for later driver development by you.

Background

You might be a well-experienced software engineer and might want to involve in kernel programming.

Create your WDM Driver: a Pseudo Driver tutorial

Before we start, declaration for member routines and structures is required. The most important driver-required data structure is - DEVICE_EXTENSION!

Collapse Copy Code
typedef struct tagDEVICE_EXTENSION {
    PDEVICE_OBJECT DeviceObject;       // device object this driver creates
    PDEVICE_OBJECT NextDeviceObject;   // next-layered device object in this
                                       // device stack
    DEVICE_CAPABILITIES pdc;           // device capability
    IO_REMOVE_LOCK RemoveLock;         // removal control locking structure
    LONG handles;                      // # open handles
    PVOID DataBuffer;                  // Internal Buffer for Read/Write I/O
    UNICODE_STRING Device_Description; // Device Description
    SYSTEM_POWER_STATE SysPwrState;    // Current System Power State
    DEVICE_POWER_STATE DevPwrState;    // Current Device Power State
    PIRP PowerIrp;                     // Current Handling Power-Related IRP
} DEVICE_EXTENSION, *PDEVICE_EXTENSION;

Code segment below demonstrates the start of creating a valid WDM Driver.

There are mandatory and optional members in a WDM Driver. A valid WDM Driver should come with the following member routines, the most important task item for DriverEntry is to register all member routines to kernel:

Collapse Copy Code
//
NTSTATUS
DriverEntry( 
IN PDRIVER_OBJECT DriverObject, 
IN PUNICODE_STRING RegistryPath 
)
{
RtlInitUnicodeString(
&Global_sz_Drv_RegInfo,
RegistryPath->Buffer);

// Initialize function pointers

DriverObject->DriverUnload = DriverUnload;
DriverObject->DriverExtension->AddDevice = AddDevice;

DriverObject->MajorFunction[IRP_MJ_CREATE] = PsdoDispatchCreate;
DriverObject->MajorFunction[IRP_MJ_CLOSE] = PsdoDispatchClose;
DriverObject->MajorFunction[IRP_MJ_READ] = PsdoDispatchRead;
DriverObject->MajorFunction[IRP_MJ_WRITE] = PsdoDispatchWrite;
DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = PsdoDispatchDeviceControl;
DriverObject->MajorFunction[IRP_MJ_POWER] = PsdoDispatchPower;
DriverObject->MajorFunction[IRP_MJ_PNP] = PsdoDispatchPnP;

return STATUS_SUCCESS;
}
//

Normal operation workflow within WDM Driver

Code segment below demonstrates the workflow in AddDevice routine: the most important task for AddDevice routine is to create a Device object, and attach it to the existing device stack.

Collapse Copy Code
NTSTATUS
AddDevice(
IN PDRIVER_OBJECT DriverObject,
IN PDEVICE_OBJECT PhysicalDeviceObject 
)
{
    ULONG DeviceExtensionSize;
    PDEVICE_EXTENSION p_DVCEXT;
    PDEVICE_OBJECT ptr_PDO;
    NTSTATUS status;

    RtlInitUnicodeString(
        &Global_sz_DeviceName, L"");
    //Get DEVICE_EXTENSION required memory space
    DeviceExtensionSize = sizeof(DEVICE_EXTENSION);
    //Create Device Object
    status = IoCreateDevice(
        DriverObject,
        DeviceExtensionSize,
        &Global_sz_DeviceName,
        FILE_DEVICE_UNKNOWN,
        FILE_DEVICE_SECURE_OPEN, 
        FALSE,
        &ptr_PDO
        );

    if (NT_SUCCESS(status)) {
        ptr_PDO->Flags &= ~DO_DEVICE_INITIALIZING;
        ptr_PDO->Flags |= DO_BUFFERED_IO;  //For Buffered I/O
        //ptr_PDO->Flags |= DO_DIRECT_IO;  //For Direct I/O
        p_DVCEXT = ptr_PDO->DeviceExtension;
        p_DVCEXT->DeviceObject = ptr_PDO;
        RtlInitUnicodeString(

        /*
        //Other initialization tasks go here
        */

        //Store next-layered device object
        //Attach device object to device stack
        p_DVCEXT->NextDeviceObject = 
            IoAttachDeviceToDeviceStack(ptr_PDO, PhysicalDeviceObject);
    }

    return status;
}

Code segment below shows how to support IRP_MJ_CREATE, it is send when client application tries to connect to the underlying Pseudo Driver. Before proceeding, see graph below in advance to realize the connection process.

Usually, you will use CreateFile/fopen Win32 API to connect to the underlying device. It is the right time that Win32 Subsystem submits IRP_MJ_CREATE and asks driver to connect to the target device!

Collapse Copy Code
NTSTATUS
PsdoDispatchCreate(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
)
{
    PIO_STACK_LOCATION p_IO_STK;
    PDEVICE_EXTENSION p_DVCEXT;
    NTSTATUS status;

    p_IO_STK = IoGetCurrentIrpStackLocation(Irp);
    p_DVCEXT = DeviceObject->DeviceExtension;
    status = IoAcquireRemoveLock(&p_DVCEXT->RemoveLock, p_IO_STK->FileObject);
    if (NT_SUCCESS(status)) {
        CompleteRequest(Irp, STATUS_SUCCESS, 0);
        return STATUS_SUCCESS;
    } else {
        IoReleaseRemoveLock(&p_DVCEXT->RemoveLock, p_IO_STK->FileObject);
        CompleteRequest(Irp, status, 0);
        return status;
    }
}

Code segment below shows how to support IRP_MJ_CLOSE, the IRP is sent when client application tries to close connection to the underlying Pseudo Driver. Before proceeding, see graph below in advance to realize the closing process.

Usually, you will use CloseHandle/fclose Win32 API to close connection to the underlying device. It is the right time that Win32 Subsystem submits IRP_MJ_CLOSE and asks driver to close connection to target device!

Collapse Copy Code
NTSTATUS
PsdoDispatchClose(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
)
{
    PIO_STACK_LOCATION p_IO_STK;
    PDEVICE_EXTENSION p_DVCEXT;

    p_IO_STK = IoGetCurrentIrpStackLocation(Irp);
    p_DVCEXT = DeviceObject->DeviceExtension;
    IoReleaseRemoveLock(&p_DVCEXT->RemoveLock, 
    p_IO_STK->FileObject);
    CompleteRequest(Irp, STATUS_SUCCESS, 0);
    return STATUS_SUCCESS;
}

I/O Support : Buffered I/O Mode

There are three I/O modes in Windows kernel, they are Buffer, Direct and Neither modes. Now, we'll talk about Buffered I/O, and this article will not involve Neither mode for data transfer if processing under user-thread occupied memory space, it might be dangerous!! If client application is going to read/write data to and from driver, the memory address of data source will not be directly referenced by the underlying driver. System kernel will allocate another data buffer with equivalent size in kernel. All data transferred must be copied into this area before they are to the target place. Usually, you will call ReadFile/WriteFile or fread/fwrite to make read/write request.

Below code segment demos the workflow in I/O handle for read request. As we can see, the routine that is registered for reading is PsdoDispatchRead in DriverEntry, this member routine will read data out of Driver's internal member - DataBuffer to client application:

Collapse Copy Code
NTSTATUS
PsdoDispatchRead(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
)
{
    PVOID Buf; //Buffer provided by user program
    ULONG BufLen; //Buffer length for user provided buffer
    LONGLONG Offset;//Buffer Offset
    PVOID DataBuf; //Buffer provided by Driver
    ULONG DataLen; //Buffer length for Driver Data Buffer
    ULONG ByteTransferred;
    PIO_STACK_LOCATION p_IO_STK;
    PDEVICE_EXTENSION p_DVCEXT;

    DbgPrint("IRP_MJ_READ : Begin/r/n");
    //Get I/o Stack Location & Device Extension
    p_IO_STK = IoGetCurrentIrpStackLocation(Irp);
    p_DVCEXT = DeviceObject->DeviceExtension;

    //Get User Output Buffer & Length 
    BufLen = p_IO_STK->Parameters.Read.Length;
    Offset = p_IO_STK->Parameters.Read.ByteOffset.QuadPart;
    Buf = (PUCHAR)(Irp->AssociatedIrp.SystemBuffer) + Offset;

    //Get Driver Data Buffer & Length
    DataBuf = p_DVCEXT->DataBuffer;
    if (DataBuf == NULL)
        DataLen = 0;
    else
        DataLen = 1024;

    IoAcquireRemoveLock(&p_DVCEXT->RemoveLock, Irp);

    DbgPrint("Output Buffer Length : %d/r/n", BufLen);
    DbgPrint("Driver Data Length : %d/r/n", DataLen);
    //
    if (BufLen <= DataLen) {
        ByteTransferred = BufLen; 
    } else {
        ByteTransferred = DataLen;
    }

    RtlCopyMemory(
        Buf, DataBuf, 
        ByteTransferred);

    IoReleaseRemoveLock(&p_DVCEXT->RemoveLock, Irp);
    CompleteRequest(Irp, STATUS_SUCCESS, ByteTransferred);

    DbgPrint("IRP_MJ_READ : End/r/n");
    return STATUS_SUCCESS;
}

Below code segment demos the possible task items in workflow that can support the normal I/O requests to write data from application to driver.

Collapse Copy Code
NTSTATUS
PsdoDispatchWrite(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
)
{
    PVOID Buf; //Buffer provided by user program
    ULONG BufLen; //Buffer length for user provided buffer
    LONGLONG Offset;//Buffer Offset
    PVOID DataBuf; //Buffer provided by Driver
    ULONG DataLen; //Buffer length for Driver Data Buffer
    ULONG ByteTransferred;
    PIO_STACK_LOCATION p_IO_STK;
    PDEVICE_EXTENSION p_DVCEXT;
    NTSTATUS status;

    DbgPrint("IRP_MJ_WRITE : Begin/r/n");

    //Get I/o Stack Location & Device Extension
    p_IO_STK = IoGetCurrentIrpStackLocation(Irp);
    p_DVCEXT = DeviceObject->DeviceExtension;

    //Get User Input Buffer & Length 
    BufLen = p_IO_STK->Parameters.Write.Length;
    Offset = p_IO_STK->Parameters.Read.ByteOffset.QuadPart;
    Buf = (PUCHAR)(Irp->AssociatedIrp.SystemBuffer) + Offset;

    //Get Driver Data Buffer & Length
    DataBuf = p_DVCEXT->DataBuffer;
    DataLen = 1024;

    IoAcquireRemoveLock(&p_DVCEXT->RemoveLock, Irp);

    DbgPrint("Input Buffer Length : %d/r/n", BufLen);
    DbgPrint("Driver Data Length : %d/r/n", DataLen);

    if (BufLen <= DataLen) {
        ByteTransferred = BufLen; 
    } else {
        ByteTransferred = DataLen;
    }

    ByteTransferred = BufLen;
        RtlZeroMemory(
        p_DVCEXT->DataBuffer,
        1024);

    RtlCopyMemory(
        DataBuf,
        Buf, 
        ByteTransferred);

    IoReleaseRemoveLock(&p_DVCEXT->RemoveLock, Irp);
    CompleteRequest(Irp, STATUS_SUCCESS, ByteTransferred);

    DbgPrint("IRP_MJ_WRITE : End/r/n");
    return STATUS_SUCCESS;
}

I/O Support : Direct I/O Mode

Below graph exhibits how Direct I/O mode is supported when data is transferred between client application and driver. Under Direct I/O mode, Memory Manager will create MDL (Memory Descriptor List) to reference the physical address taken by user-provided buffer, all data can be directly referenced via MDL from kernel environment.

In DDK, some MMXxx routines are provided to help you to get MDL that maps to physical address of user-provided buffer.

Below code segment contains the statements that can support data reading under Direct I/O mode. It is achieved by Mmxxx routine, please read it carefully, and you can also find the full code in the zip file. The most important MmXxx you will use in this mode should be - MmGetSystemAddressForMdlSafe, it can obtain the MDL that references the physical address of user-buffer.

Collapse Copy Code
NTSTATUS
PsdoDispatchRead(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
)
{
    PVOID Buf; //Buffer provided by user program
    ULONG BufLen; //Buffer length for user provided buffer
    ULONG Offset;//Buffer Offset
    PVOID DataBuf; //Buffer provided by Driver
    ULONG DataLen; //Buffer length for Driver Data Buffer
    ULONG ByteTransferred;
    PIO_STACK_LOCATION p_IO_STK;
    PDEVICE_EXTENSION p_DVCEXT;

    DbgPrint("IRP_MJ_READ : Begin/r/n");
    //Get I/o Stack Location & Device Extension
    p_IO_STK = IoGetCurrentIrpStackLocation(Irp);
    p_DVCEXT = DeviceObject->DeviceExtension;

    //Get User Output Buffer & Length 
    Buf = MmGetSystemAddressForMdlSafe(
        Irp->MdlAddress, HighPagePriority);

    if (Buf == NULL) {
        DbgPrint("Can't get Virtual Address from MDL/r/n");
        return STATUS_INSUFFICIENT_RESOURCES;
    }
    BufLen = MmGetMdlByteCount(Irp->MdlAddress);
    Offset = MmGetMdlByteOffset(Irp->MdlAddress);

    //Get Driver Data Buffer & Length
    DataBuf = p_DVCEXT->DataBuffer;
    if (DataBuf == NULL)
        DataLen = 0;
    else
        DataLen = 1024;

    IoAcquireRemoveLock(&p_DVCEXT->RemoveLock, Irp);

    DbgPrint("Output Buffer Length : %d/r/n", BufLen);
    DbgPrint("Offset for Buffer in the Memory Page: %d/r/n", Offset);
    DbgPrint("Driver Data Length : %d/r/n", DataLen);
    //
    if (BufLen <= DataLen) {
        ByteTransferred = BufLen; 
    } else {
        ByteTransferred = DataLen;
    }

    RtlCopyMemory(
        Buf, 
        DataBuf, 
        ByteTransferred);

    IoReleaseRemoveLock(&p_DVCEXT->RemoveLock, Irp);
    CompleteRequest(Irp, STATUS_SUCCESS, ByteTransferred);

    DbgPrint("IRP_MJ_READ : End/r/n");
    return STATUS_SUCCESS;
}

Below code segment demos the possible workflow to write data from user application to driver:

Collapse Copy Code
NTSTATUS
PsdoDispatchWrite(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
)
{
    PVOID Buf; //Buffer provided by user program
    ULONG BufLen; //Buffer length for user provided buffer
    ULONG Offset;//Buffer Offset
    PVOID DataBuf; //Buffer provided by Driver
    ULONG DataLen; //Buffer length for Driver Data Buffer
    ULONG ByteTransferred;
    PIO_STACK_LOCATION p_IO_STK;
    PDEVICE_EXTENSION p_DVCEXT;
    NTSTATUS status;

    DbgPrint("IRP_MJ_WRITE : Begin/r/n");

    //Get I/o Stack Location & Device Extension
    p_IO_STK = IoGetCurrentIrpStackLocation(Irp);
    p_DVCEXT = DeviceObject->DeviceExtension;

    //Get User Input Buffer & Length 
    Buf = MmGetSystemAddressForMdlSafe(
        Irp->MdlAddress, HighPagePriority);

    if (Buf == NULL) {
        DbgPrint("Can't get Virtual Address from MDL/r/n");
        return STATUS_INSUFFICIENT_RESOURCES;
    }

    BufLen = MmGetMdlByteCount(Irp->MdlAddress);
    Offset = MmGetMdlByteOffset(Irp->MdlAddress);

    //Get Driver Data Buffer & Length
    DataBuf = p_DVCEXT->DataBuffer;
    DataLen = 1024;

    IoAcquireRemoveLock(&p_DVCEXT->RemoveLock, Irp);

    DbgPrint("Input Buffer Length : %d/r/n", BufLen);
    DbgPrint("Offset for Buffer in the Memory Page: %d/r/n", Offset);
    DbgPrint("Driver Data Length : %d/r/n", DataLen);

    if (BufLen <= DataLen) {
        ByteTransferred = BufLen; 
    } else {
        ByteTransferred = DataLen;
    }

    ByteTransferred = BufLen;
    RtlZeroMemory(
        p_DVCEXT->DataBuffer,
        1024);

    RtlCopyMemory(
        DataBuf,
        Buf, 
        ByteTransferred);

    IoReleaseRemoveLock(&p_DVCEXT->RemoveLock, Irp);
    CompleteRequest(Irp, STATUS_SUCCESS, ByteTransferred);

    DbgPrint("IRP_MJ_WRITE : End/r/n");
    return STATUS_SUCCESS;
}

Contents of the source zip package

The zip file contains below subfolders:

  1. Application: it contains the client applications to the Pseudo Driver.
  2. bin: it contains the install/uninstall utility for Pseudo Driver.
  3. BufferedIO_PW: it is where the Pseudo Driver that employees Buffered I/O mode for read/write resides.
  4. DirectIO_PW: it is where the Pseudo Driver that employees Direct I/O Mode for read/write resides.
  5. IOCTL_PW: it is where the Pseudo Driver that simply supports user-defined I/O Control Code resides.
  6. ShareFiles: it is the common shared library for PnP, Power Management, I/O completion.
  7. Install: it contains the source code of install/uninstall utility. (Install utility is directly referenced from DDK's sample, I won't provide redundant copy of it, only the uninstall utility source code is provided in it).

How to build the Pseudo Driver?

  1. Unzip the package to some folder you'd like it to be, let's name it ROOT_OF_SOURCE.
  2. Select Start->Programs->Development Kits->Windows DDK xxxx.xxxx->Build Environments->Free Build. (This is for free release without debug information in it.)
  3. Enter ROOT_OF_SOURCE/SharedFiles subfolder, enter build -cefw, it all goes well, shared library will be generated.
  4. Enter ROOT_OF_SOURCE/BufferedIO_PW subfolder, enter build -cefw, it will create Pseudo Driver - BufferDrv.sys. Copy this file into ROOT_OF_SOURCE/BufferedIO_PW/Install if you have made add-in for any new features, the copy is for later driver install.
  5. Enter ROOT_OF_SOURCE/DirectIO_PW subfolder, enter build -cefw, it will create Pseudo Driver - DirectDrv.sys. Copy this file into ROOT_OF_SOURCE/DirectIO_PW/Install if you have made add-in for any new features, the copy is for later driver install.
  6. Enter ROOT_OF_SOURCE/IOCTL_PW subfolder, enter build -cefw, it will create Pseudo Driver - PseudoDrv.sys. Copy this file into ROOT_OF_SOURCE/IOCTL_PW/Install if you have made add-in for any new features, the copy is for later driver install.

Install Pseudo Driver into system (XP)

  1. Unzip the source file, launch DOS prompt-console.
  2. Enter into bin subfolder.
  3. Execute DevInst.bat, it will automatically install the Pseudo Driver into your system.

Uninstall Pseudo Driver from system (XP)

  1. Enter into bin subfolder.
  2. Execute DevRemove.bat, it will automatically uninstall all-driver related resources from your system.

Execute client application

You can enter into ROOT_OF_SOURCE/Application subfolder, execute bufferclient.exe, directclient.exe, and clientapp.exe to verify if the three Pseudo Drivers have been installed successfully.

Known Issues

  • The install/uninstall of Pseudo Driver won't wok on Window 2000, the root cause might be that the Setup API doesn't work on Window 2000, can't allow driver installed without a physical hardware in it. Can anybody help to resolve it? Many Thanks.
  • If you'd like to install/uninstall the Pseudo Driver in Windows 2000, you will need to launch New Hardware Wizard from within Device Manager, and select to install new hardware->Display all hardware->Install from disk->"ROOT_OF_SOURCE/BufferedIO_PW/Install", click on OK button. New Hardware Wizard will install Buffered I/O Pseudo Driver. (This is for Buffered I/O demo driver install. As for Direct I/O, please set source directory to "ROOT_OF_SOURCE/DirectIO_PW/Install").
  • Reboot is required if the driver has been reinstalled after un-installation. I don't know why this happened, I hope somebody can inform me. Many Thanks.

Future Directions for Pseudo Driver

  1. Fix above issues.
  2. WMI support in Pseudo Driver will be added-in.

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
阿里云服务器如何登录?阿里云服务器的三种登录方法
购买阿里云ECS云服务器后如何登录?场景不同,大概有三种登录方式:
9446 0
使用SSH远程登录阿里云ECS服务器
远程连接服务器以及配置环境
13052 0
阿里云服务器怎么设置密码?怎么停机?怎么重启服务器?
如果在创建实例时没有设置密码,或者密码丢失,您可以在控制台上重新设置实例的登录密码。本文仅描述如何在 ECS 管理控制台上修改实例登录密码。
20111 0
阿里云服务器端口号设置
阿里云服务器初级使用者可能面临的问题之一. 使用tomcat或者其他服务器软件设置端口号后,比如 一些不是默认的, mysql的 3306, mssql的1433,有时候打不开网页, 原因是没有在ecs安全组去设置这个端口号. 解决: 点击ecs下网络和安全下的安全组 在弹出的安全组中,如果没有就新建安全组,然后点击配置规则 最后如上图点击添加...或快速创建.   have fun!  将编程看作是一门艺术,而不单单是个技术。
18396 0
阿里云服务器如何登录?阿里云服务器的三种登录方法
购买阿里云ECS云服务器后如何登录?场景不同,阿里云优惠总结大概有三种登录方式: 登录到ECS云服务器控制台 在ECS云服务器控制台用户可以更改密码、更换系.
24952 0
如何设置阿里云服务器安全组?阿里云安全组规则详细解说
阿里云安全组设置详细图文教程(收藏起来) 阿里云服务器安全组设置规则分享,阿里云服务器安全组如何放行端口设置教程。阿里云会要求客户设置安全组,如果不设置,阿里云会指定默认的安全组。那么,这个安全组是什么呢?顾名思义,就是为了服务器安全设置的。安全组其实就是一个虚拟的防火墙,可以让用户从端口、IP的维度来筛选对应服务器的访问者,从而形成一个云上的安全域。
17087 0
阿里云服务器ECS远程登录用户名密码查询方法
阿里云服务器ECS远程连接登录输入用户名和密码,阿里云没有默认密码,如果购买时没设置需要先重置实例密码,Windows用户名是administrator,Linux账号是root,阿小云来详细说下阿里云服务器远程登录连接用户名和密码查询方法
21585 0
+关注
andyro1984
本团队有11年以上的解决方案端到端开发经验,涉及的行业有云计算、应用软件(包括WEB)、嵌入式、分布式、大型服务程序(Windows/Linux)、操作系统等。
211
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
JS零基础入门教程(上册)
立即下载
性能优化方法论
立即下载
手把手学习日志服务SLS,云启实验室实战指南
立即下载