USB驱动开发(六)操作USBD.SYS

转自：http://blog.csdn.net/xxxluozhen/article/details/5023666

3.3.2.3.    操作USBD.SYS

正如前面所述，对USBD.SYS驱动操作的中介只URB结构体，因此对USBD.SYS的操作主要可以分构造URB和调用请求两部分，如下以USB读写操作过程为例进行分析。
第一步构造URB：由于EasyArm2400下位机固件程序USB采用的是中断方式进行数据传输，因此我们就需要构造一个中断传输的URB，实现如下代码。

UsbBuildInterruptOrBulkTransferRequest(urb,        sizeof(struct _URB_BULK_OR_INTERRUPT_TRANSFER),        pipeInformation->PipeHandle,        NULL,        mdl,        stageLength,        urbFlags,        NULL);

其中_URB_BULK_OR_INTERRUPT_TRANSFER类型指明了构造的RB用于中断方式传输的请求。
第二步调用请求：在对挂载的设备进行操作的时候，从DDK DOC中可以发现采用的函数是IoCallDriver。IoCallDriver函数的第一个参数指定的为挂载的设备对象，第二参数为当前的IRP。
其实对USBD.SYS的操作有以上两步基本能够完成，但是你会发现其实并没有真正意义上操作了USBD.SYS。分析一下可以发现，其实的构造的URB并没有传输到挂载的设备上。
在DDK中提供IoGetNextIrpStackLocation函数获取挂载的设备当前的IRP，如下代码帮你实现URB的传输。

nextStack = IoGetNextIrpStackLocation(Irp);    nextStack->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL;    nextStack->Parameters.Others.Argument1 = (PVOID) urb;    nextStack->Parameters.DeviceIoControl.IoControlCode =IOCTL_INTERNAL_USB_SUBMIT_URB;

其中nextStack->Parameters.Others.Argument1保存了构造后的URB，nextStack->Parameters.DeviceIoControl.IoControlCode保存了需要执行的I/O请求。
有了进一步的补充，操作USBD.SYS已经可以实现了，但是挂载的设备的何时操作完成，返回的状态是什么？这些对于上层的驱动程序来说根本无法知道。因此DDK引入了完成用例的概念，完成用例将帮助实现以上的这些需求。
完成用例的概念就是当下层设备完成操作时，IRP会产生回滚，当回滚到上层设备IRP的时候，如果该层IRP存在完成用例子时，系统将进入用例函数进行处理，DDK提供的设置完成用例函数如下。

VOID   IoSetCompletionRoutine(     IN PIRP  Irp,     IN PIO_COMPLETION_ROUTINE  CompletionRoutine,     IN PVOID   Context,     IN BOOLEAN    InvokeOnSuccess,     IN BOOLEAN  InvokeOnError,     IN BOOLEAN  InvokeOnCancel);

其中CompletionRoutine指向的是用例服务函数，Context指定为需要传递的参数。一般传递需要触发的事件。
到此为止，操作USBD.SYS的整个过程已经完成，如下展示读写操作请求的核心代码。

；申请一段内存，用于保存URB结构体。  urb = (PURB)ExAllocatePool(NonPagedPool, sizeof(struct _URB_BULK_OR_INTERRUPT_TRANSFER)); ；构建一个用于中断传输的URB。 UsbBuildInterruptOrBulkTransferRequest(urb, sizeof(struct _URB_BULK_OR_INTERRUPT_TRANSFER),      pipeInformation->PipeHandle,      NULL,      mdl,      stageLength,      urbFlags,      NULL); nextStack = IoGetNextIrpStackLocation(Irp); nextStack->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL; nextStack->Parameters.Others.Argument1 = (PVOID) urb; nextStack->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_SUBMIT_URB。 ；设置完全用例。 IoSetCompletionRoutine(Irp,                (PIO_COMPLETION_ROUTINE)LPC2478_USB_ReadWriteCompletion,      rwContext,      TRUE,      TRUE,      TRUE); ；设置Pending位 IoMarkIrpPending(Irp); ；向挂载设备发送URB，请求传输数据。 ntStatus = IoCallDriver(deviceExtension->NextDeviceObject,Irp);

提示：IoSkipCurrentIrpStackLocation与IoCopyCurrentIrpStackLocationToNext区别
在操作USDB.SYS的时候，上述的两个函数也是比较常见，同时也是比较容易混淆的。其实这两个函数的实际功能基本上一样，都是将当前的IRP
I/O堆栈拷贝给下层的驱动的I/O堆栈。但是这两个函数也存在一些特殊用途的区别，当操作USBD.SYS，设置了完成用例时，DDK规定就不能使用IoSkipCurrentIrpStackLocation函数了，只能使用IoCopyCurrentIrpStackLocationToNext。

3.3.2.4.     选择配置USB

DriverEntry函数执行完成后，开始执行AddDevice函数。这个函数创建设备对象把设备对象连接到设备堆栈上，清除DO_DEVICE_INITIALIZING标志。然后配置管理器向驱动程序发送一个即插即用请求IRP_MN_START_DEVICE，该IRP例程将配置设备。
配置USB的步骤一般是首先为设备选择一个配置(大多数设备仅有一种配置)。选定了某种配置后，接着应该选择配置中的一个或多个接口。然后向总线驱动程序发送配置选择URB，总线驱动程序接收到该URB后向设备发出命令使用选定的配置和接口。
1.        设备选择配置的过程其实就是获取设备的配置描述符的过程，首先获取固定大小的配置描述符，这时，此描述符不包含接口描述符和端点描述符。然后获取全部的配置描述符，包括接口描述符和端点描述符，代码如下。

//首先获取固定大小的配置描述符，这时，此描述符不包含接口描述符和端点描述符。 siz = sizeof(USB_CONFIGURATION_DESCRIPTOR); configurationDescriptor = ExAllocatePool(NonPagedPool, siz); if(configurationDescriptor) {     UsbBuildGetDescriptorRequest(urb,          (USHORT) sizeof(struct _URB_CONTROL_DESCRIPTOR_REQUEST),          USB_CONFIGURATION_DESCRIPTOR_TYPE,          0,          0,          configurationDescriptor,          NULL,          sizeof(USB_CONFIGURATION_DESCRIPTOR),          NULL);          /* 向USBD.SYS发送URB */           ntStatus = CallUSBD(DeviceObject, urb);         …… } //然后获取全部的配置描述符，包括接口描述符和端点描述符 siz = configurationDescriptor->wTotalLength; ExFreePool(configurationDescriptor); configurationDescriptor = ExAllocatePool(NonPagedPool, siz); if(configurationDescriptor) {      UsbBuildGetDescriptorRequest(urb,           (USHORT)sizeof(struct _URB_CONTROL_DESCRIPTOR_REQUEST),           USB_CONFIGURATION_DESCRIPTOR_TYPE,           0,           0,           configurationDescriptor,           NULL,           siz,           NULL);      ntStatus = CallUSBD(DeviceObject, urb);         …… }

2.        从配置描述符中提取感兴趣的接口描述符，总线驱动程序提供了函数USBD_ParseConfigurationDescriptorEx以简化这个过程。

interfaceDescriptor =USBD_ParseConfigurationDescriptorEx(                       ConfigurationDescriptor,ConfigurationDescriptor,                       interfaceindex,0, -1, -1, -1);

该函数各个参数的含义是：第一个参数是上一步获取的完整的配置描述符；第二个参数是描述符内部开始搜索的地址，如果从头开始搜索，需要设置和第一个参数相同；剩下的五个参数是和感兴趣的接口相关搜索关键字，分别是InterfaceNumber,
AlternateSetting, InterfaceClass, InterfaceSubClass, InterfaceProtoco。但相关的关键字不需要的时候，可以设置成-1。
由于配置描述符中可能包含多个接口，所以驱动程序需要将上述函数返回的接口描述符保存在USBD_INTERFACE_LIST_ENTRY类型的数组中。iso_usb程序首先使用ExAllocatePool函数为接口描述符分配足够的内存。

interfaceList =ExAllocatePool(NonPagedPool,    sizeof(USBD_INTERFACE_LIST_ENTRY) * (numberOfInterfaces + 1));

然后通过循环使用USBD_ParseConfigurationDescriptorEx函数获取的接口描述符对数组进行初始化。初始化时，应该把接口描述符地址赋给USBD_INTERFACE_LIST_ENTRY结构的InterfaceDescriptor成员，并把Interface成员置NULL。最后需要将数组的最后一个元素的两个成员全部置为NULL。
3.        初始化接口。首先调用USBD_CreateConfigurationRequestEx函数创建一个urb。然后需要对接口中的管道进行相应的初始化，最后将这个urb传递给底层驱动程序，由底层总线驱动程序完成接口的初始化。

urb = USBD_CreateConfigurationRequestEx(ConfigurationDescriptor, tmp); Interface = &urb->UrbSelectConfiguration.Interface; /* 需要初始化管道的MaximumTransferSize成员。它代表单一URB能携带的最大数据量 */ for(i=0; i<Interface->NumberOfPipes; i++) { Interface->Pipes[i].MaximumTransferSize = <constant> } ntStatus = CallUSBD(DeviceObject, urb);

     配置USB的过程有这几步基本上就可以完成了，配置后的信息可以通过上位机枚举显示出来。

3.3.2.5.    支持WMI(委托WMILIB处理IRP)

3.3.2.5.  1. WMI概念
Windows 2000支持一种称为Windows管理诊断(WMI)的控件，用于管理计算机系统。WBEM(基于Web的企业管理)是一个广泛的工业标准，而WMI是这个工业标准的Microsoft实现。WMI的目标是为系统管理和企业网络中管理数据的描述提供了一个模型，并尽可能独立于专用API或数据对象模型。这种独立性促进了能创建、传输，和显示控制数据的独立系统部件的发展。
WDM驱动程序以三种方式适应WMI，见图3-3-2-5-0。第一，WMI通常能响应提取性能数据的请求。第二，各种控制器应用程序可以使用WMI方式控制设备的通用特征。第三，WMI提供了一个事件通知机制，允许驱动程序通知应用程序有重要的事件发生。
在WMI模型中，数据和事件被分成了消费者和生产者两类。数据块就是抽象类的实例，其概念与C++中的类概念一致。如同C++中的类，WMI类也有数据成员和实现对象行为的方法。数据块中的内容并不是由WMI指定，而是由数据生产者和数据的使用目的决定的。送往驱动程序的数据最有可能来自管理者本身的操作。而驱动程序发出的数据通常是某种性能的统计数据，这些数据的消费者可能是某个性能监视程序，图3-3-2-5-1展示了WMI的整体结构。
WDM驱动程序可以作为WMI类实例的生产者。一个描述了驱动程序支持的各种类(驱动程序可以为这些类提供数据)的脚本称为驱动程序规划(schema)。我们可以使用MOF(Managed
Object Format)语言定义规划。系统则维护一个称为repository的数据字典，它包含了所有已知的规划定义。如果驱动程序做得正确，系统将在初始化驱动程序时自动把规划放到repository中。
3.3.2.5.  2. 支持和取消WMI服务
在WDM驱动当中，对WMI的支持需要实例化IRP_MJ_SYSTEM_CONTROL例程。在该IRP例程服务函数当中再调用IoWMIRegistrationControl函数为该驱动注册对WMI服务支持。

IoWMIRegistrationControl(DeviceExtension->FunctionalDeviceObject,                           WMIREG_ACTION_REGISTER);

相反如果要取消对WMI服务支持，需要调用同样需要调用IoWMIRegistrationControl，但是地二个参数需要设置为WMI_ACTION_DEREGISTER。

IoWMIRegistrationControl(DeviceExtension->FunctionalDeviceObject,                           WMIREG_ACTION_DEREGISTER);

3.3.2.5.  3. 委托WMILIB处理IRP
在系统控制IRP的派遣例程中，你可以委托WMILIB来完成大部分工作。WMILIB_CONTEXT结构体是WMILIB提供的一个用于处理WMI的服务器，该结构体描述如下：

typedef struct _WMILIB_CONTEXT {   ULONG  GuidCount;   PWMIGUIDREGINFO  GuidList;   PWMI_QUERY_REGINFO  QueryWmiRegInfo;   PWMI_QUERY_DATABLOCK  QueryWmiDataBlock;   PWMI_SET_DATABLOCK  SetWmiDataBlock;   PWMI_SET_DATAITEM  SetWmiDataItem;   PWMI_EXECUTE_METHOD  ExecuteWmiMethod;   PWMI_FUNCTION_CONTROL  WmiFunctionControl; } WMILIB_CONTEXT, *PWMILIB_CONTEXT;

Ø       GuidCount域指定注册WMI的驱动WMIGUIDREGINFO结构体数量，另外GuidList则指定WMIGUIDREGINFO数组。
Ø       QueryWmiRegInfo指向QueryRegInfo回调函数；QueryWmiDataBlock指向QueryDataBlock回调函数；SetWmiDataBlock指向SetDataBlock回调函数；SetWmiDataItem指向SetDataItem回调函数。
Ø       ExecuteWmiMethod和WmiFunctionControl一般设置为NULL。
有了这个结构体，你可以委托WMILIB来完成大部分工作，代码如下；

WMIGUIDREGINFO guidlist[] = {                                                                                                                      <--1   {&GUID_WMI42_SCHEMA, 1, WMIREG_FLAG_INSTANCE_PDO}, };   WMILIB_CONTEXT libinfo = {   arraysize(guidlist),   guidlist,   QueryRegInfo,   QueryDataBlock,   SetDataBlock,   SetDataItem,   ExecuteMethod,   FunctionControl, };   NTSTATUS DispatchWmi(IN PDEVICE_OBJECT fdo, IN PIRP Irp) {   PDEVICE_EXTENSION pdx = (PDEVICE_EXTENSION) fdo->DeviceExtension;   NTSTATUS status = IoAcquireRemoveLock(&pdx->RemoveLock, Irp);                                                        <--2   if (!NT_SUCCESS(status))     return CompleteRequest(Irp, status, 0);     SYSCTL_IRP_DISPOSITION disposition;   status = WmiSystemControl(&libinfo, fdo, Irp, &disposition);                                                         <--3     switch (disposition)                                                                                                                                       <--4   {     case IrpProcessed:     break;   case IrpNotCompleted:                                                                                                                                 <--5     IoCompleteRequest(Irp, IO_NO_INCREMENT);     break;     default:                                                                                                                                                         <--6   case IrpNotWmi:   case IrpForward:                                                                                                                           <--7     IoSkipCurrentIrpStackLocation(Irp);     status = IoCallDriver(pdx->LowerDeviceObject, Irp);     break;   }     IoReleaseRemoveLock(&pdx->RemoveLock, Irp);   return status; }

Ø       guidlist声明的有效范围是整个文件，它描述了驱动程序支持的类GUID，并列出几个WMILIB用于处理WMI请求的回调函数。
Ø       与其它派遣例程相同，我们在处理这种IRP时也获取和释放删除锁。我们要防止PnP事件使下层设备对象消失。我们自己的设备对象不会消失，因为IoWMIRegistrationControl调用获得了对它的一次引用。
Ø      status
= WmiSystemControl(&libinfo, fdo, Irp, &disposition)语句调用WMILIB来处理该IRP。我们传递了WMILIB_CONTEXT结构的地址。通常我们应使用一个静态上下文结构，因为从一个IRP到另一个IRP，其中的信息不可能被改变。WmiSystemControl返回两个信息：一个NTSTATUS代码和一个SYSCTL_IRP_DISPOSITION值。
Ø       执行这个IRP时我们可能需要做一些额外工作，这取决于它的特征代码，如果这个代码为IrpProcessed，则该IRP已经完成，我们不需要再做任何事情。对于除IRP_MN_REGINFO之外的其它副功能码，这种情况就是通常情况。
Ø       如果代码是IrpNotCompleted，则我们有责任完成该IRP。这也是通常情况，除了IRP_MN_REGINFO。WMILIB已经填充完IRP中的IoStatus块，所以我们仅需要调用IoCompleteRequest。
Ø       default和IrpNotWmi情况不应该发生在Windows
2000中。如果不能处理所有可能的特征代码，我们将到达default。如果我们向WMILIB发送一个IRP，但其副功能码在WMI中未定义，则我们到达IrpNotWmi处。
Ø       IrpForward情况发生于该系统控制IRP是发往其它驱动程序的。回想一下ProviderId参数，它指出处理该IRP的驱动程序。WmiSystemControl用设备对象指针指向的值与第二个参数比较。如果不相同，它就返回到IrpForward，然后我们把该IRP下传到下一个驱动程序。
WMI消费者通过查看WMILIB_CONTEXT结构中的GUID来判断驱动程序是否是一个WMI生产者。当一个消费者想提取数据时，它通过(间接地)访问WMI数据字典(
repository)，把一个符号对象名翻译成一个GUID，这个GUID就是以前提到的MOF语句的一部分，它应该与WMILIB_CONTEXT结构中的GUID一致，WMILIB会关心这个匹配。
WMILIB将回调驱动程序中的例程来执行设备相关或驱动程序相关的处理。回调函数大部分时间以同步方式执行IRP的操作。除了IRP_MN_REGINFO之外，我们可以推迟IRP处理并返回STATUS_PENDING。如果一个回调例程挂起了该IRP，那么它应该额外再调用一次IoAcquireRemoveLock。任何完成该IRP的例程都应该调用相反的IoReleaseRemoveLock函数。
3.3.2.5.  4. 完成WMI修改服务
在SetDataBlock回调函数和SetDataItem回调函数完成之后，需要将修改后的信息保存在资源文件当中，由于委托WMILIB处理WMI服务，因此WMILIB为我们提供了一个WmiCompleteRequest函数，该函数将实现我们需要的功能，函数描述如下；

NTSTATUS   WmiCompleteRequest(     IN PDEVICE_OBJECT  DeviceObject,     IN PIRP  Irp,     IN NTSTATUS  Status,     IN ULONG  BufferUsed,     IN CCHAR  PriorityBoost     );

BufferUsed指定实际需要完成的数据量，如果该值设置过小，系统会返回STATUS_BUFFER_TOO_SMALL，如果该值设置过大，系统会自动根据实际需要设置完成的数据量。
在WmiCompleteRequest函数实现过程当中，其实操作系统仍然调用IoCompleteRequest函数完成相关的IRP例程，PriorityBoost域指定I/O处理的优先级别。PriorityBoost值一般设置为IO_NO_INCREMENT。