USB Function Composite Device Driver Samples
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
The USB Function Composite device driver allows any USB Function client driver to work simultaneously with other USB Function client drivers. To use the USB Function Composite device driver the appropriate registry keys are set as explained below.
First, in order to load the USB Function client driver, you need to designate the USB Function Composite driver as the default client driver.
[HKEY_LOCAL_MACHINE\Drivers\USB\FunctionDrivers]
"DefaultClientDriver"="CompositeFN"
The following table describes the global USB Function Composite client registry settings read by the USB Function Composite device driver. The global USB Function client driver registry settings are set under [HKEY_LOCAL_MACHINE\Drivers\USB\FunctionDrivers\CompositeFN].
| Value:Type | Description |
|---|---|
Attributes:multi_sz |
Attributes for each configuration. Each string is a two digit hexadecimal value. The default setting is for 0x80 and one configuration. |
bcdDevice:dword |
USB function client device's release number, in binary-coded decimal (BCD) format. |
DefaultPrefix:string |
Prefix of the client specific values. The default string value is “CompositeFn_”. All client specific value names will be prefixed with this string, ex. “DefaultString” is actually “CompositeFn_DefaultString”. |
ManufacturerString:string |
Name of the USB Function client driver manufacturer. Replace appropriately. |
MaxPacketSize:dword |
Maximum packet size for endpoint zero. |
PowerConsumption:multi_sz |
Maximum power consumption for each configuration. Each string is a two digit hexadecimal value. The default setting is for one configuration with 0 mA. |
ProductID:dword |
Product Identifier of the USB function client device to be defined by the manufacturer. |
ProductString:string |
Name of the USB function client device. Replace appropriately. |
SerialString:string |
Serial number of the USB function client device. Replace appropriately. |
VendorID:dword |
VendorID must be changed. 045E belongs to Microsoft and is only to be used for prototype devices in your labs. Visit this Web site to obtain a vendor identifier. |
The following table describes the client specific USB Function client registry settings read by the USB Function Composite device driver. All of the registry values in this table begin with a prefix that is defined by the DefaultPrefix value of the USB Composite Function client driver registry settings. By default, the prefix for these values is "CompositeFn_". The client specific USB Function client driver registry settings are set under [HKEY_LOCAL_MACHINE\Drivers\USB\FunctionDrivers\<UsbFnClient>].
| Value:Type | Description |
|---|---|
<DefaultPrefix>Configurations:multi_sz |
Indicates the client configuration to use for a specific composite configuration. Each string is a two digit hexadecimal value (client driver configuration index) or “X”. An "X" indicates that the client should be excluded from a specific composite configuration. If nothing is specified, the default configuration of client drivers will be included in all composite configurations |
<DefaultPrefix>DefaultClient:dword |
The DefaultClient default value is 0. A value of 1 indicates that this client is a default client. When processing USB Function controller notifications, the USB Function Composite device driver will try to determine what client should get the notification. The default client (if specified) will get the notification if the USB Function Composite device driver was unable to determine the correct recipient for the notification. |
<DefaultPrefix>DefaultString:string |
String used when the string in a specific language string was not provided. |
<DefaultPrefix>FunctionClass:dword |
Function class code |
<DefaultPrefix>FunctionDescription:string |
String describing this function. |
<DefaultPrefix>FunctionProtocol:dword |
Function protocol code. |
<DefaultPrefix>FunctionSubclass:dword |
Function subclass code. |
If the FunctionClass, FunctionSubclass, FunctionProtocol and FunctionDescription values are not specified in the registry, the USB Function Composite device driver will use the class, subclass and protocol codes from the first interface of the client device.
The sequence in which the USB Function client drivers are loaded is controlled by setting the [HKEY_LOCAL_MACHINE\Drivers\USB\FunctionDrivers\CompositeFN\ClientDriverList] registry key as follows:
[HKEY_LOCAL_MACHINE\Drivers\USB\FunctionDrivers\CompositeFN]
ClientDriverList=multi_sz:"ClientA;ClientB;ClientC"
The above registry setting loads ClientA, then Client B, and then ClientC. If the multi_sz string is provided then it determines which USB Function client drivers are loaded and the order in which they are loaded. However, if this multi_sz key is not present, then it will be created by scanning through all the USB Function client drivers and entering them in the order they are enumerated in the configuration registry file.
On a parallel note, by default all USB Function client drivers, specified in the multi_sz key, will be loaded by the USB Function Composite device driver. If you do not want a particular USB Function client driver to be loaded, then you need to set the CompositeFn_Disable key under that specific USB Function Client driver's registry key to 1 as shown below.
[HKLM\Drivers\USB\FunctionDrivers\<USBFnClient>]
CompositeFn_Disable = DWORD:1
Essentially, two factors determine which USB Function client drivers are loaded. The first factor is whether or not the ClientDriverList multi_sz registry key is specifically set or if it is allowed to take on default settings. The second factor is whether the individual USB Function client driver has been disabled using the CompositeFn_Disable key. Based on these factors, all USB Function client drivers are loaded by default unless the individual USB Function client drivers has the CompositeFn_Disable key set to prevent their loading or the ClientDriverList multi_sz string is explicitly set to exclude a specific USB Function client driver.
The ClientDriverList multi_sz registry key simplifies the process of determining which USB Function client drivers to load. This key allows the system developer to change the USB Function client drivers loaded on a device, without having to walk through all the USB Function client drivers in the system and edit their specific registry settings. Through this system it is possible to accomplish the dynamic loading and unloading of individual USB Function client drivers.
Dynamic loading and unloading of individual client drivers
Dynamic loading and unloading of individual client drivers is still supported in Windows Embedded CE 6.0 and can easily be accomplished using the ClientDriverList multi_sz registry key mentioned above.
Under Windows CE 5.0, before the addition of the USB Function Composite device driver, switching to a different client could be accomplished by changing the protocol used by the Windows Embedded CE device. For example, under Windows CE 5.0, the user can choose at run time whether the Windows Embedded CE device uses the USB RNDIS, USB Serial, or USB Function Mass Storage client driver. In this scenario, the current client is stopped, unloaded, and a new USB Function client driver is loaded in its place.
With the addition of the USB Function Composite device driver this scenario has changed. Under CE 6.0 there is little need to switch USB Function client drivers since the device can use multiple protocols at the same time. However, if the system owner decides to dynamically change the USB Function client drivers on the device, due to a hardware limitation like the number of USB end points, then the process is straight forward. The system owner just sets the ClientDriverList multi_sz registry key, to represent the required USB Function client drivers, and then calls the USB Function controller with the IOCTL_UFN_CHANGE_CURRENT_CLIENT IOCTL code. The USB Function controller then unloads the USB Function Composite device driver, as well as all the USB Function client drivers. Subsequently, the USB Function controller switches to either the USB Function Composite device driver, running a different set of USB Function client drivers, or else to a different noncomposite USB Function client driver. Upon reload, unless a noncomposite USB Function client driver was chosen, the USB Function controller loads the USB Function Composite device driver, which in turn loads the USB Function client driver specified by the ClientDriverList multi_sz registry key. This process effectively allows the system developer to change the USB Function protocols of a device dynamically.
Compatibility Issues with USB Composite Device Driver
With Windows Embedded CE 6.0, only true USB Class device drivers can reside on top of the USB composite device driver in the device driver architecture. True USB class device drivers are drivers that conform to one of the USB.org class definitions (the class ID from USB.org).
To solve this issue so that other types of drivers, such as USBSER_Class device drivers and mass storage device drivers, can reside on top of the USB composite driver, you must explicitly add the interface numbers to the .inf file on the desktop side. To do this, find the section of the .inf file that matches the VID to the PID, for example, the [DeviceList] section. Then, add a line of code that resembles the following format:
%DESCRIPTION%=DriverInstall, USB\VID_XXXX&PID_YYYY&MI_00