Windows Driver Samples剖析之Echo （一）

一、Echo是什么

1，Echo，字典上的意思是：1）反射，vt.；2）发送回声，随声附和，vi.；3）回声。

2，在TCP/IP通信中，提到“client和server之间实现了一个Echo协议（应答协议）”。

3，在shell语言中，无论是linux的bash中，还是windows的cmd中，echo命令表示“显示，回显”。

        echo命令可以显示真实的系统路径，如上图中“%systemroot%”，被显示为“C:\Windows”。

        综上所述，echo在计算机领域，就是“显示或回显”的意思。

二、KMDF Echo Sample

1，工程简介

        Echo工程是一个并不控制任何硬件的演示驱动程序。它使用序列I/O队列来序列化针对设备的读写请求，以及显示如何处理请求。“general/echo”目录下，共有四个子目录：kmdf、umdf、umdf2和umdfSocketEcho。本系列文章只剖析“KMDF Echo Sample”。

        进入kmdf目录，显示它有driver和exe两个文件夹、kmdfecho.sln和readme两个文件。它其实是，在一个solution下包含了driver和application两个工程。事实上，driver中又包含AutoSync和DriverSync两个版本。

        先来看readme:

        The ECHO (KMDF) sample demonstrates how to use a sequential queue to serialize read and write requests presented to the driver. It also shows how to synchronize execution of these events with other asynchronous events such as request cancellation and DPC.

        从该段介绍可知，kmdf echo工程主要演示两点：1）queue对来自应用程序读写request的序列化；2）IO callback、DPC和cancel routine三者的同步。

2，文件介绍（File Mainfest）

        直接摘自readme，如下：

***(The AutoSync and DriverSync versions of the sample each have their own version of the following files)***

Driver.h, Driver.c
DriverEntry and Events on the Driver Object.

Device.h, Device.c
Events on the Device Object.

Queue.h, Queue.c
Contains Events on the I/O Queue Objects.

Echo.inx
File that describes the installation of this driver. The build process converts this into an INF file.

        从上面的内容可以看出，整个驱动程序代码的结构很简单，主要分为：Driver Object、Device Object和Queue Objects。此外就是安装相关的Inf文件。

3，代码速览（Code Tour）

DriverEntry - Creates a framework driver object.

EvtDeviceAdd: Creates a device and registers self managed I/O callbacks so that it can start and stop the periodic timer when the device is entering and leaving D0 state. It registers a device interface so that application can find the device and send I/O. For managing I/O requests, the driver creates a default queue to receive only read & write requests. All other requests sent to the driver will be failed by the framework. Then the driver creates a periodic timer to simulate asynchronous event. The purpose of this timer would be to complete the currently pending request.

In the AutoSync version of the sample, the queue is created with WdfSynchronizationScopeQueue so that I/O callbacks including cancel routine are synchronized with a queue-level lock. Since timer is parented to queue and by default timer objects are created with AutomaticSerialization set to **TRUE**, timer DPC callbacks will be serialized with EvtIoRead, EvtIoWrite and Cancel Routine.

In the DriverSync version of the sample, the queue is created with WdfSynchronizationScopeNone, so that the framework does not provide any synchronization. The driver synchronizes the I/O callbacks, cancel routine and the timer DPC using a spinlock that it creates for this purpose.

EvtIoWrite: Allocates an internal buffer as big as the size of buffer in the write request and copies the data from the request buffer to internal buffer. The internal buffer address is saved in the queue context. If the driver receives another write request, it will free this one and allocate a new buffer to match the size of the incoming request. After copying the data, it will mark the request cancelable and return. The request will be eventually completed either by the timer or by the cancel routine if the application exits.

EvtIoRead: Retrieves request memory buffer and copies the data from the buffer created by the write handler to the request buffer, and marks the request cancelable. The request will be completed by the timer DPC callback.

Since the queue is a sequential queue, only one request is outstanding in the driver.

4，测试工程

        exe文件夹中包含的是一个“echoapp”工程，主要用于测试echo驱动。主要是同步读写和异步读写两种测试。如下：

Testing
-------
**Usage:**

Echoapp.exe --- Send single write and read request synchronously

Echoapp.exe -Async --- Send 100 reads and writes asynchronously

Exit the app anytime by pressing Ctrl-C

使用Windbg调试Echo内核模式程序