windows USB 装备驱动开发-USB复合装备的注册

USB 多功能装备的驱动步调（称为复合驱动步调）可以向根本 USB 驱动步调堆栈注册和注销复合装备。 Microsoft 提供的驱动步调（Usbccgp.sys）是由 Windows 加载的默认复合驱动步调。 本文中的过程实用于更换Usbccgp.sys的基于 WDM的自界说 Windows 驱动步调模子 。
通用串行总线 (USB) 装备可以提供多个同时处于运动状态的功能。 此类多功能装备也称为 复合装备。 比方，复合装备大概为键盘功能界说一个函数，为鼠标界说另一个函数。 复合驱动步调罗列装备的功能。 复合驱动步调可以在团体模子中管理这些函数本身，或为每个函数创建物理装备对象 (PDO) 。 这些单独的 PDO 由各自的 USB 功能驱动步调、键盘驱动步调和鼠标驱动步调管理。
USB 3.0 规范界说了 函数停息和长途唤醒功能 ，使各个函数可以或许进入和退出低功耗状态，而不会影响其他功能或整个装备的电源状态。 
若要使用该功能，复合驱动步调须要将装备注册到根本 USB 驱动步调堆栈。 由于该功能实用于 USB 3.0 装备，因此复合驱动步调必须确保根本堆栈支持版本USBD_INTERFACE_VERSION_602。 通过注册哀求，复合驱动步调：

• 关照根本 USB 驱动步调堆栈，驱动步调负责发送哀求，以支持功能驱动举行长途唤醒。 长途唤醒哀求由 USB 驱动步调堆栈处理处罚，该堆栈将须要的协议哀求发送到装备；
  
• 获取 (USB 驱动步调堆栈分配的每个函数) 一个函数句柄的列表。 然后，复合驱动步调可以在驱动步调的哀求中使用函数句柄，以便长途唤醒与句柄关联的函数；
  

通常，复合驱动步调在驱动步调的 AddDevice 或启动装备例程中发送注册哀求来处理处罚 IRP_MN_START_DEVICE。 因此，复合驱动步调会开释在驱动步调的卸载例程，比方 stop-device (IRP_MN_STOP_DEVICE ) 或 remove-device 例程 (IRP_MN_REMOVE_DEVICE) 中为开释在注册时分配的资源。
先决条件

发送注册哀求之前，请确保：

• 你拥有装备中的函数数。 该数字可以派生 get-configuration 哀求检索到的形貌符；
  
• 在对 USBD_CreateHandle 的上一次调用中，你已得到 USBD 句柄；
  
• 根本 USB 驱动步调堆栈支持 USB 3.0 装备。 为此，请调用 USBD_IsInterfaceVersionSupported 并将 USBD_INTERFACE_VERSION_602 作为版本转达给 查抄；
  

注册复合装备

以下过程先容怎样天生和发送注册哀求，以将复合驱动步调与 USB 驱动步调堆栈相干联。
1.分配 COMPOSITE_DEVICE_CAPABILITIES 布局并通过调用 COMPOSITE_DEVICE_CAPABILITIES_INIT 宏对其举行初始化；
2.将 COMPOSITE_DEVICE_CAPABILITIES 的 CapabilityFunctionSuspend 成员设置为 1；
3.分配 REGISTER_COMPOSITE_DEVICE 布局，并通过调用 USBD_BuildRegisterCompositeDevice 例程初始化 布局 。 在调用中，指定 USBD 句柄、初始化 COMPOSITE_DEVICE_CAPABILITIES 布局和函数数；
4.通过调用 IoAllocateIrp (IRP) 分配 I/O 哀求数据包，并通过调用 IoGetNextIrpStackLocation 获取指向 IRP 的第一个堆栈位置的指针 (IO_STACK_LOCATION) ；
5.为足以容纳函数句柄数组的缓冲区分配内存 (USBD_FUNCTION_HANDLE) 。 数组中的元素数必须是 PDO 的数目；
6.通过设置 IO_STACK_LOCATION的以下成员来天生哀求：

• 通过将 Parameters.DeviceIoControl.IoControlCode 设置为 IOCTL_INTERNAL_USB_REGISTER_COMPOSITE_DEVICE，指定哀求的范例。
  
• 通过将 Parameters.Others.Argument1 设置为初始化的 REGISTER_COMPOSITE_DEVICE 布局的地点来指定输入参数。
  
• 通过将 AssociatedIrp.SystemBuffer 设置为在步调 5 中分配的缓冲区来指定输出参数。
  

7.调用 IoCallDriver ，通过将 IRP 转到达下一个堆栈位置来发送哀求；
完成后，查抄 USB 驱动步调堆栈返回的函数句柄数组。 可以将数组存储在驱动步调的装备上下文中，以供未来使用；
下面的代码示例演示怎样天生和发送注册哀求。 该示例假定复合驱动步调将从前获取的函数数和 USBD 句柄存储在驱动步调的装备上下文中。

2. VOID  RegisterCompositeDriver(PPARENT_FDO_EXT parentFdoExt)  
3. {  
4.     PIRP                            irp;  
5.     REGISTER_COMPOSITE_DRIVER       registerInfo;  
6.     COMPOSITE_DRIVER_CAPABILITIES   capabilities;  
7.     NTSTATUS                        status;  
8.     PVOID                           buffer;  
9.     ULONG                           bufSize;  
10.     PIO_STACK_LOCATION              nextSp;  
12.     buffer = NULL;  
14.     COMPOSITE_DRIVER_CAPABILITIES_INIT(&capabilities);  
15.     capabilities.CapabilityFunctionSuspend = 1;  
17.     USBD_BuildRegisterCompositeDriver(parentFdoExt->usbdHandle,  
18.         capabilities,  
19.         parentFdoExt->numFunctions,  
20.         &registerInfo);  
22.     irp = IoAllocateIrp(parentFdoExt->topDevObj->StackSize, FALSE);  
24.     if (irp == NULL)
25.     {  
26.         //IoAllocateIrp failed.
27.         status = STATUS_INSUFFICIENT_RESOURCES;  
28.         goto ExitRegisterCompositeDriver;   
29.     }  
31.     nextSp = IoGetNextIrpStackLocation(irp);  
33.     bufSize = parentFdoExt->numFunctions * sizeof(USBD_FUNCTION_HANDLE);  
35.     buffer = ExAllocatePoolWithTag (NonPagedPool, bufSize, POOL_TAG);  
37.     if (buffer == NULL)
38.     {  
39.         // Memory alloc for function-handles failed.
40.         status = STATUS_INSUFFICIENT_RESOURCES;  
41.         goto ExitRegisterCompositeDriver;   
42.     }  
44.     nextSp->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL;     
45.     nextSp->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_REGISTER_COMPOSITE_DRIVER;  
47.     //Set the input buffer in Argument1      
48.     nextSp->Parameters.Others.Argument1 = &registerInfo;  
50.     //Set the output buffer in SystemBuffer field for USBD_FUNCTION_HANDLE.      
51.     irp->AssociatedIrp.SystemBuffer = buffer;  
53.     // Pass the IRP down to the next device object in the stack. Not shown.
54.     status = CallNextDriverSync(parentFdoExt, irp, FALSE);  
56.     if (!NT_SUCCESS(status))
57.     {  
58.         //Failed to register the composite driver.
59.         goto ExitRegisterCompositeDriver;   
60.     }  
62.     parentFdoExt->compositeDriverRegistered = TRUE;  
64.     parentFdoExt->functionHandleArray = (PUSBD_FUNCTION_HANDLE) buffer;  
66. End:  
67.     if (!NT_SUCCESS(status))
68.     {  
69.         if (buffer != NULL)
70.         {  
71.             ExFreePoolWithTag (buffer, POOL_TAG);  
72.             buffer = NULL;  
73.         }  
74.     }  
76.     if (irp != NULL)
77.     {  
78.         IoFreeIrp(irp);  
79.         irp = NULL;  
80.     }  
82.     return;  
83. }

复制代码

取消注册复合装备

• 通过调用 IoAllocateIrp 分配 IRP，并通过调用 IoGetNextIrpStackLocation 获取指向 IRP 的第一个堆栈位置 (IO_STACK_LOCATION) 的指针；
  
• 通过将 IO_STACK_LOCATION 的 Parameters.DeviceIoControl.IoControlCode 成员设置为IOCTL_INTERNAL_USB_UNREGISTER_COMPOSITE_DEVICE来天生哀求；
  
• 调用 IoCallDriver ，通过将 IRP 转到达下一个堆栈位置来发送哀求；
  

复合驱动步调在 remove-device 例程的上下文中发送一次 IOCTL_INTERNAL_USB_UNREGISTER_COMPOSITE_DEVICE 哀求。 哀求的目标是删除 USB 驱动步调堆栈与复合驱动步调及其罗列函数之间的关联。 该哀求还会整理为维护该关联而创建的全部资源，以及上一个注册哀求中返回的全部函数句柄。
下面的代码示例演示怎样天生并发送取消注册复合装备的哀求。 该示例假定复合驱动步调从前是通过注册哀求注册的，如本主题前面所述。

2. VOID  UnregisterCompositeDriver(  
3.     PPARENT_FDO_EXT parentFdoExt )  
4. {  
5.     PIRP                irp;  
6.     PIO_STACK_LOCATION  nextSp;  
7.     NTSTATUS            status;  
9.     PAGED_CODE();  
11.     irp = IoAllocateIrp(parentFdoExt->topDevObj->StackSize, FALSE);  
13.     if (irp == NULL)
14.     {  
15.         //IoAllocateIrp failed.
16.         status = STATUS_INSUFFICIENT_RESOURCES;  
17.         return;  
18.     }  
20.     nextSp = IoGetNextIrpStackLocation(irp);  
22.     nextSp->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL;     
23.     nextSp->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_UNREGISTER_COMPOSITE_DRIVER;  
25.     // Pass the IRP down to the next device object in the stack. Not shown.
26.     status = CallNextDriverSync(parentFdoExt, irp, FALSE);  
28.     if (NT_SUCCESS(status))
29.     {  
30.         parentFdoExt->compositeDriverRegistered = FALSE;      
31.     }  
33.     IoFreeIrp(irp);  
35.     return;  
36. }

复制代码

在后续会报告复合装备的电源管理题目。