如何构造一个简单的USB过滤驱动程序

Posted 2023-05-02

一、基本原理 我们知道，WDM（和KDM）是分层的，在构造设备栈时，IO管理器可以使一个设备对象附加到另外一个初始驱动程序创建的设备对象上。与初始设备对象相关的驱动程序决定的IRP,也将被发送到附加的设备对象相关的驱动程序上。 参考技术A 本文分三部分来介绍如何构造一个简单的USB过滤驱动程序，包括“基本原理”、“程序的实现”、“使用INF安装”。此文的目的在于希望读者了解基本原理
后，可以使用除DDK以外最流行也最方便的驱动开发工具DriverStudio来实现一个自己的过滤驱动，并正确地安装。

一、基本原理
我
们知道，WDM（和KDM）是分层的，在构造设备栈时，IO管理器可以使一个设备对象附加到另外一个初始驱动程序创建的设备对象上。与初始设备对象相关的
驱动程序决定的IRP,也将被发送到附加的设备对象相关的驱动程序上。这个被附加的驱动程序便是过滤驱动程序。如右图，过滤驱动可以在设备栈的任何层次中
插入。IO管理器发出的IRP将会沿着右图的顺序从上往下传递并返回。因此，我们可以使用过滤驱动程序来检查、修改、完成它接收到的IRP，或者构造自己
的IRP。
上面这种文字是很枯燥的，好在“前人”已经写过一些范例以供我们更好地理解这些概念。读过Waltz
Oney的《Programming Windows Driver Mode》一书的读者大概都知道Waltz
Oney提供的范例中有一个关于USB过滤器(第九章)的例子，而在此基础上，《USB Design By
Example》(http://www.usb-by-example.com)的作者John
Hyde实现了一个USB键盘过滤驱动程序，即给此程序增加了一个“拦截(Intercept)”功能来处理USB键盘的Report以实现特定的功能：
当驱动程序在IRP_MJ_INTERNAL_DEVICE_CONTROL设置的完成例程从USB设备拦截到一个
Get_Report_Descriptor时，拦截程序将此Descriptor中的USAGE值从“Keyboard”改为
“UserDefined”，再返回给系统。
我们可以从这个例子中获得一些灵感，比如，在Win2k下，键盘是由OS独占访问的，我们可以通过这
种方式使之可以让用户自由访问；我们也可以拦截其他Report_Descriptor，将部分键重新定义，以满足特殊的要求；如果你愿意再做一个用户态
的程序，你还可以将你拦截到的键值传递给你的用户态程序，以实现象联想、实达等国内电脑大厂出品的那些键盘上的各种实用的功能。

二、程序的实现
Waltz Oney和John Hyde的例子已经写得很详细了，读者可以不用修改一个字节便顺利地编译生成一个过滤驱动程序。本文的目的在于使用DriverStudio组件Driverworks来实现同样的功能。
相
信读者读到这篇文章时，已经对DriverStudio有了很多的了解。DriverStudio作为一个以C++为基础的“快速”驱动开发工具，它封装
了基本上所有的DDK的函数，其集成在VC++中的DriverWizard，可以很方便地引导你完成设备驱动程序开发的全过程，能根据你的硬件种类自动
生成设备驱动程序源代码，并提供了很多范例程序。当然，这些例子中便包含一个USB
Filter驱动程序的框架。在不侵犯版权的前提下，充分利用现有共享的、免费的、授权的代码是我们的一贯作法。我们下面便以此范例为基础来作修改。
我
们的目的是做一个HID小驱动程序hidusb.sys的Lower Filter，它附加在“人机接口设备”
，通过拦截USB的Get_Report_Descriptor来修改其返回值，当它发现该Descriptor的Usage
为“Keyboard”时，将其改为“UserDefined”，如此我们便可以完全控制这只键盘。具体做法是，拦截
IRP_MJ_INTERNAL_DEVICE_CONTROL，并检查其IOCTL代码及URB，如果满足IOCTRL功能代码为
IOCTL_INTERNAL_USB_SUBMIT_URB以及URB功能代码为
URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE的条件，即上层驱动发来
Get_Report_Descriptor请求时，设置一个完成例程，在这个完成例程中，我们将判断Usage的值，将Usage由
“6(Keyboard)”时，将其改为“0(UserDefined)”。
打开C:\Program
Files\NuMega\DriverStudio\DriverWorks\Examples\wdm\usbfilt目录(具体目录依你的
DriverStudio所安装的目录不同而不同) ，再打开工程文件usbfilt.dsw，我们先看一下代码。
程序由两个类组成，一个是Driver类，一个是Device类。Driver类包括：
入口函数DriverEntry:
DECLARE_DRIVER_CLASS(UsbFilterDriver, NULL)
/////////////////////////////////////////////////////////////////////
// Driver Entry
//
NTSTATUS UsbFilterDriver::DriverEntry(PUNICODE_STRING RegistryPath)

T << "UsbFilterDriver::DriverEntry\n";

m_Unit = 0;
return STATUS_SUCCESS;

// The following macro simply allows compilation at Warning Level 4
// If you reference this parameter in the function simply remove the macro.
UNREFERENCED_PARAMETER(RegistryPath);

AddDevice函数
NTSTATUS UsbFilterDriver::AddDevice(PDEVICE_OBJECT Pdo)

T << "UsbFilterDriver::AddDevice\n";
UsbFilterDevice * pFilterDevice = new (
static_cast<PCWSTR>(NULL),
FILE_DEVICE_UNKNOWN,
static_cast<PCWSTR>(NULL),
0,
DO_DIRECT_IO
)
UsbFilterDevice(Pdo, m_Unit);
if (pFilterDevice)

NTSTATUS status = pFilterDevice->ConstructorStatus();
if ( !NT_SUCCESS(status) )

T << "Failed to construct UsbFilterDevice"
<< (ULONG) m_Unit
<< " status = "
<< status
<< "\n";

delete pFilterDevice;

else

m_Unit++;

return status;

else

T << "Failed to allocate UsbFilterDevice"
<< (ULONG) m_Unit
<< "\n";
return STATUS_INSUFFICIENT_RESOURCES;



这两段代码基本上和自动生成的代码差不多。AddDevice的作用是构造一个过滤器的实例。
关键的代码在Device类。在这个类里，我们把过滤器插入设备栈，并拦截IRP，用自己的完成例程来实现特定的功能。
Device构造函数
UsbFilterDevice::UsbFilterDevice(PDEVICE_OBJECT Pdo, ULONG Unit) :
KWdmFilterDevice(Pdo, NULL)

T << "UsbFilterDevice::UsbFilterDevice\n";
// Check constructor status
if ( ! NT_SUCCESS(m_ConstructorStatus) )

return;

// Remember our unit number
m_Unit = Unit;
// initialize the USB lower device
m_Usb.Initialize(this, Pdo);
NTSTATUS status = AttachFilter(&m_Usb); //Attach the filter
if(!NT_SUCCESS(status))

m_ConstructorStatus = status;
return;

SetFilterPowerPolicy();
SetFilterPnpPolicy();

在
DDK中，我们用IoAttachDevice将设备对象插入设备栈中。DriverStudio封装了这个函数。在DriverStudio中，其他驱
动程序需要用Initialize来初始化设备对象和接口，对于过滤驱动，我们关键是需要Attachfilter将其附加在堆栈中。
对于大部分如IRP_MJ_SYSTEM_CONTROL等IRP，我们所做的只需用PassThrough(Irp)将其直接往设备栈下层传递，不需要做任何工作。这些代码我们就不一一列举了。下面的部分才是本文的关键。

我们知道，HIDUSB.SYS是使用内部IOCTRL发出URB给USB类驱动程序(USBD)读取数据的，那么，HIDUSB首先必须构造一个
IRP_MJ_INTERNAL_DEVICE_CONTROL，它的IOCTL功能码为
IOCTL_INTERNAL_USB_SUBMIT_URB(发出URB的内部IOCTL)。另外，因为我们要检查并修改的是USB键盘某个接口的报告
描述，那么这个URB应该是URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE，如下：
NTSTATUS UsbFilterDevice::InternalDeviceControl(KIrp I)

T << "UsbFilterDevice::InternalDeviceControl\n";
// Pass through IOCTLs that are not submitting an URB
//不是我们感兴趣的IOCTL不要理它
if (I.IoctlCode() != IOCTL_INTERNAL_USB_SUBMIT_URB)
return DefaultPnp(I);

PURB p = I.Urb(CURRENT); // get URB pointer from IRP

//不是我们感兴趣的URB，也不要理它，
if (p->UrbHeader.Function !=
URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE)
return DefaultPnp(I);
//符合要求的IRP才被设置完成例程
return PassThrough(I, LinkTo(DeviceControlComplete), this);

在设置好条件以后，再来实现完成例程。所有的检查、修改等动作都是在完成例程里面完成的。
NTSTATUS UsbFilterDevice::DeviceControlComplete(KIrp I)

PURB p = I.Urb(CURRENT);
if(p)

//拦截到设备返回的描述表，
char* DescriptorBuffer = (char*)p->UrbControlDescriptorRequest.TransferBuffer;
//指向第三个字节，表示设备Usage属性的值
DescriptorBuffer += 3;
//如果值为6则改成0，6表示hid键盘，0表示未知设备
//在设备管理器里面，原来的hid兼容键盘就不复存在了，取而代之的则是hid兼容设备
if ((*DescriptorBuffer&0xff) == 6)
*DescriptorBuffer = 0;

return I.Status();

读者可以对照DriverWorks中的例子，直接替换掉（或者修改）上面这两个函数，再编译一下，便可以得到一个完整的键盘过滤器驱动程序。
其实，只要弄清楚了我们需要做些什么动作，在DriverStudio里面只需要写少量的关键代码，便可实现我们的要求，其余的大部分工作，或有范例可供参考，或有Driver Wizard自动生成。

从上面可以看出，我们只需要修改这两个函数，拦截合适的IRP，便可以在完成例程里面实现我们特定的要求。正如开头所说，我们也可以拦截其他的IRP，拦
截其他的URB，或者拦截特定键盘的按键键值，将之传递到用户态，以方便实现联想、实达等随机配备的多功能键盘的功能。

三、使用INF安装驱动

在完成了驱动以后，还必须把它安装到系统里面，驱动程序才会起作用。一般来说，我们都必须为我们的驱动程序提供一个inf文件，以便于用户安装或者维护。
对于新手来说，过滤驱动程序的inf或许有些棘手。所以，针对本文所描述的驱动，我们提供一个Win98下的安装范例usbkey.inf，范例中“;”
后的文字是注解，以方便读者理解。

; usbkey.INF
;
; Installs Lower Level Filter for a HID keyboard device
;
; (c) Copyright 2001 SINO Co., Ltd.
;
[Version]
;”CHICAGO”表示Win9x平台
Signature="$CHICAGO$"
;键盘所属类名
Class=HID
ClassGUID=745a17a0-74d3-11d0-b6fe-00a0c90f57da
；驱动程序提供者，此信息会显示在设备属性的“常规”页
Provider=%USBDBE%
LayoutFile=layout.inf
;显示在驱动程序文件详细资料窗口
DriverVer=11/12/2001,4.10.2222.12

;[ControlFlags]
;ExcludeFromSelect = *

;驱动程序安装目录，inf会将我们的驱动程序安装到如下目录
;记得Destinationdir后面一定要带一个“s”
[DestinationDirs]
DefaultDestDir = 10,system32\drivers

;要增加的注册表项
[ClassInstall]
Addreg=HIDClassReg

[HIDClassReg]
HKR,,,,%HID.ClassName%
HKR,,Icon,,-20

;制造商
[Manufacturer]
%USBDBE%=USBDBE

[USBDBE]
;我们所要附加过滤驱动程序的设备ID。这个ID可以从IC的规范上得来，也可以
;用hidview.exe读出，或者从注册表HKLM\Enum\hid和usb项找出
%HID.DeviceDesc% = Keypad_Inst, USB\VID_05AF&PID_0805&MI_00

;要安装的文件和需要修改的注册表项
;Install usbkey driver
[Keypad_Inst]
CopyFiles=Keypad_Inst.CopyFiles
AddReg=Keypad_Inst.AddReg

[Keypad_Inst.CopyFiles]
hidusb.sys
hidparse.sys
hidclass.sys
usbfilt.sys

[Keypad_Inst.AddReg]
HKR,,DevLoader,,*ntkern
HKR,,NTMPDriver,,"hidusb.sys"

[Keypad_Inst.HW]
AddReg=Keypad_Inst.AddReg.HW

;Lowerfilters表示是低层过滤驱动，如果是上层过滤驱动，则必须改为upperfilters
[Keypad_Inst.AddReg.HW]
HKR,,"LowerFilters",0x00010000,"usbfilt.sys"

;HID设备所需要安装的文件和注册表中需要修改的地方
;Install USBHIDDevice
[USBHIDDevice]
CopyFiles=USBHIDDevice.Copy
AddReg=USBHIDDevice.AddReg

[USBHIDDevice.Copy]
hidclass.sys
hidusb.sys
hidparse.sys

[USBHIDDevice.AddReg]
HKR,,DevLoader,,*ntkern
HKR,,NTMPDriver,,"hidusb.sys"

;以下定义需要在上面某些地方使用时替换的字符串
[strings]
USBDBE = "SINO Co., Ltd."
HID.DeviceDesc = "SINO USB MultiKeyboard"
HID.HIDDeviceDesc = "Human Interface Devices"
HID.DefaultDevice = "HID Default Device"
HID.ClassName = "Human Input Devices (HID)"
HID.SvcDesc = "Microsoft HID Class Driver"

其实最简单的写inf的方式，是找一些类似设备的inf文件或范例来修改。在不侵权的前提下，充分利用现有资源是我们的一贯原则。

windows设备驱动程序WDF开发

第8章 KMDF过滤器驱动程序

1. 管理设备的主功能为功能驱动FDO， 过滤器驱动位于FDO的上层或下层

    WdfFdoInitSetFilter // 声明这个一个过滤驱动

2. 安装要修改FDO的inf文件

FilterSample实例

 

第9章 USB设备开发

1. USB2.0 最快480Mb/s， UBS3.0速度 5.0Gbps (500MB/s)

2. USB设备有一到多个配置

    每个配置有一到多个接口

    每个接口有一到多个端点，端点是通信管道的终点， 有四种：批量（bulk), 控制，中断（interrupt），同步（Isochronous)

    1）端点0默认是可以访问的，输入和输出

    2）FDO的作用是把IRP引导到正确端点的管道上，把需求提给总线驱动，总线驱动分解成事务（transaction），送往总线

        事务有一到多个阶段（phase），phase分令牌(token)，数据和握手（ack)

 

3. USB数据传输方式

    1）控制传输：最高优先级，最大数据64B，每个控制事务包括一个SETUP令牌，带可选的数据阶段和握手阶段，设备必须响应控制传输

    2）

 (usb驱动部分待续）

 

第10章 PCI设备驱动程序开发

1. 微机扩展插槽有：ISA(已淘汰）， PCI（即插即用，不是热插拔）

   PCI: 32位数据总线，速率132~264MB/s, 

   通用PCI总线接口：AMCC的S5933，PLX的9054。也可以用FPGA实现PCI接口

2. 开发驱动主要有3方面问题：硬件访问，中断处理，DMA传输

    X86有两种地址空间：I/O地址（只有64KB)，内存地址（4GB以上）

    I/O映射：一个芯片的地址在I/O地址空间的范围，只能通过I/O指令来访问。

    内存映射：内存指令访问

3. I/O访问

    WRITE_PORT_UCHAR ,   WRITE_PORT_USHORT, WRITE_PORT_ULONG

    WRITE_PORT_BUFFER_UCHAR ...

4. 存储器访问

    WRITE_REGISTER_UCHAR ...

    WRITE_REGISTER_BUFFER_UCHAR

5. 硬件访问编程

   1) 根据配置定义地址指针，用于修改PCI9054的寄存器， MemBaseAddress0 和 IoBaseAddress0

   2）EvtDevicePrepareHardware 中初始化 MemBaseAddress0

6. 中断处理

   WDFINTERRUPT， 运行在DIRQL级别，处理时间尽可能短

   中断服务例程是异步调用的，必须考虑其他例程和中断服务例程的共享数据的保护性访问(硬件中断自旋锁，运行在DIRQL）

   WDF_INTERRUPT_CONFIG_INIT， WdfInterruptCreate

7. DMA编程对象

   1) WDFDMAENABLER，用于建立一个DMA适配器，说明DMA通道的特性,  WdfDmaEnablerCreate

   2) WDFDMATRANSACTION， 用于传输控制, WdfDmaTransactionCreate

       启动一个DMA传输，获取传输缓冲区的物理地址和字节数，DMA传输结束后的数据处理

       函数：

       WdfDmaTransactionInitialize（EvtProgramDmaFunction）: WdfDmaTransactionExecute后会调用EvtProgramDmaFunction

       WdfDmaTransactionExecute 执行DMA传输

       WdfDmaTransactionRelease 终止传输

   　 WdfDmaTransactionDmaCompleted 测试传输是否完成

       WdfDmaTransactionDmaCompletedFinal 强行完成DMA传输

       WdfDmaTransactionGetBytesTransferred 传输的总字节数

       WdfDmaTransactionSetMaximumLength 设置传输的最大字节数，应小于65536

   3) WDFCOMMONBUFFER，申请系统的公用缓冲区, WdfCommonBufferCreate

 

       对于DMA操作，系统提供一个特殊的内存，物理上连续的内存，称为公用缓冲区（比较稀有，避免浪费）。

       对于支持分散/聚集DMA的设备，可以不用公用缓冲区

  

8. DMA传输编程

    DPC中，测试DMA传输完成没有，若没有，则WdfDmaTransactionExecute 继续传输

PCI9056：

#define INTCSR 0x68
#define CNTRL 0x6C
#define DMAMODE0 0x80
#define DMAPADR0 0x84
#define DMALADR0 0x88
#define DMASIZ0 0x8C
#define DMADPR0 0x90//descriptor
#define DMACSR0 0xA8//DMA通道0 命令状态寄存器
#define HPIC 0x00
#define HPIA 0x04
#define HPID 0x08

 

第11章 UMDF驱动程序编程入门

UMDFSample实例

是dll程序

 

第12章 WinDbg使用介绍

1. windbg调试：双机调试，也可以用虚拟机代替

    目标机：启动时选择“启用调试程序”

    主控机：winDbg中kernel debugging

    windbg：debug-》break， 使主控机和目标机连接

    .reload 加载符号文件

    ld projectName  加载PDB文件

    lm l 显示已经加载符号文件列表

 

2. 调试

    F9 在源文件中设置断点

    G  使目标机运行

    F10 执行