USB CDC + HID + IAD interface

The descriptor belove, generated from MCP2200 device board. MCP2200 is programmed PIC18F14k50.
And it look like composite device(IAD, HID +CDC). I have test it by pickit2 programmer.
I know Windows xp sp3 or higher versions needed for IAD devices. 
Anyway, I need smilar descriptor and working PDS project . This descriptor may useful or not. I‘m not sure.

As I understood from all googling about composite devices, two interfaces usually mean that in Windows device manager

we will see composite device and two other devices that corespond to each interface.

If you need one device, then most likely you will need to use device class 0xEF and USB Interface Association Descriptor,

but I‘m not sure if it will do what you need.

http://msdn.microsoft.com/en-us/library/windows/hardware/ff540054(v=vs.85).aspx

http://www.microsoft.com/taiwan/whdc/archive/iad.mspx

usbccgp.sys hangs Windows to death when a descriptor is malformed?

Yes, it‘s true. Even for full-speed and low-speed devices. So double-check your descriptors:

• The first Configuration Descriptor has ID #1
• The first Interface Descriptor has ID #0 and are contiguous numbered.
  The Interface count in Configuration Descriptor must be set correctly.
• The first Alternate Setting has ID #0 and are contiguous numbered

Problems arise when you change your single-interface USB device into a multi-interface (multi-function) while keeping your USB VID+PID pair!

Even when your change or add some more USB interface with the same VID+PID pair, problems occur.

The Windows behaviour of assigning a driver is as follows:

• If the VID+PID is already known, Windows loads the known driver regardless whether it‘s a multi-function device or not.
  (I.e. when you loaded a driver before for the non-multifunction device with PnP ID e.g. USB\VID_16C0&PID_06B3, that driver is always used.)
  As a consequence, your driver will fail (typically with a blue screen) when it is surprisingly bound to the - now - multifunction USB device.
  
  
• If VID+PID is not known, Windows tries to load a Class Driver.
  This is "usbccgp.sys" for the top of multifunction devices which is a very special class (not USB\Class_00).
  
  
• Windows remembers the Class-Driver-To-VID+PID(+MI)-binding for the next plug-in event persistently, probably for performance purposes.
  Therefore, when you swap your Interfaces keeping VID+PID, you earn errors.
  But you can get rid easily by uninstalling your device in Device Manager. This will remove the memorized bindings.
  
  
• "usbccgp.sys" itself retries the enumeration process for the child devices in the same way,
  i.e. preferes VID+PID+MI bindings over USB Class bindings.
  
  
• In case of no match, no driver is loaded, and the entry is marked in Device Manager.

So you may conclude:

• VID+PID, and MI numbers (like USB\VID_16C0&PID_06B3&REV_4621&MI_00) have precedence,
  allowing manufacturers to deliver their own multifunction device drivers (replacing "usbccgp.sys")
  
  
• USB CLASS bindings (like USB\Class_07) have less precedence, allowing manufacturers
  to deliver their own specialized device driver replacing one of the system-supplied class drivers (like "usbprint.sys")
  
  
• REV numbers don‘t matter Windows, so manufacturers are free to (mis)use this entry,
  and there is no option to get more possible USB device bindings "for free" using the REVnumber as an extra binding criterion

An example: 

This INF file snippet is wrong because you have no control whether your driver is bound to the Interface #0
or the entire USB device (except your driver is very smart and can handle this):

• %DevDesc%=Dev,USB\VID_16C0&PID_06B3&REV_4621&MI_00
  %DevDesc%=Dev,USB\VID_16C0&PID_06B3&REV_4620 

(Windows will work as expected most of the time, but users are able to bind multi-function devices to entire devices,
and produce overwhelming trouble with your support.) 

As a result:

If you change your single-interface USB device to multi-interface and vice versa keeping VID+PID,
make sure that you cleaned your Device Manager entries beforehand.
Or at least before you plug your changed device.

Google for devmgr_show_nonpresent_devices and devmgr_show_details to get a clue.

Better you change VID+PID too, providing you have a free pair available.

If you are in doubt offering a single-interface or multi-interface USB device,

simply decide to multi-interface at the first step,

and implement an extra HID or CDC interface to make usbccgp.sys happy.

It‘s useful for debugging purposes later. At least two childs are needed.

Note that CDC interface (which is itself a composite USB device by design and handled in a special way by usbccgp.sys)

will not run properly in elsewhere-multifunction devices on Windows 2000 and earlier.

USB Composite Device

USB composite device

Examples

USB_CDC_HID_IAD_10.zip

This example implements a composite device of CDC (with IAD) and HID 

The CDC interface is based on the code of USB CDC implementation for ‘F32x and ‘F34x In either interface, CDC and HID, the device loops back the OUT transfer to IN.

Passed USBCV R1.3.1, the ch9 and HID test
Tested on these Windows version,
- Windows Vista SP1
- WinXP SP3 (usbser.sys: 5.1.2600.5508, usbccgp.sys: 5.1.2600.5512)

On the original WinXP SP2 (usbser.sys, usbccgp.sys: 5.1.2600.2180),
the HID interface of the device works well, but CDC causes BSOD when a test app opens the VCP.

USB_HID_composite_01.zip

This example implements three HID interfaces to SiLabs ‘F320/‘F340 DK.
Each interface has an interrupt IN EP and an interrupt OUT EP.
The firmware loops back the data sent to the OUT EP to the IN EP, on each interface.

Passed the USB compliance test, USBCV 1.3, ch9 and HID test.
Tested on HClient host app example on WinDDK.

USB_Mouse_INT_01.zip

This is a demonstration which shows a composite device combined SiLabs USB_HID\MouseExample and USB_Interrupt (USB_INT)

• When you are asked a device driver, specify the INF folder attached to this zip file.
• USB_Interrupt host application and device driver works with this implementation without any change.

1. What is composite device

Composite device is defined in the USB spec as follows (usb_20.pdf 5.2.3),
A device that has multiple interfaces controlled independently of each other is referred to as a composite device.
Using composite device, multiple functions are combined into a single device.
Ex.
- Keyboard + Mouse
- Video + USB Hard disk
- I/O device (HID + USB_bulk)

Another advantage of composite device is that it eases the device driver development.
OS assigns a separate device driver to each Interface of the composite device as follows.
Therefore, a dedicated monolithic driver is not required for newly designed device;
you can realize it using existing drivers.

  +----------------------------+      +----------------------
  | Composite Device           |      | Host PC
  |                            |      |
  |  Function 0 -- Interface 0 --------- Device driver A <--->
  |                            |      |
  |  Function 1 -- Interface 1 --------- Device driver B <--->
  +----------------------------+      +-----------------------

When OS has some required drivers as built-in, they are available for the composite device.

These OS built-in device drivers are called as USB class driver.
Approved Class Specification Documents from USB.org
http://www.usb.org/developers/devclass_docs#approved

Windows have these built-in class drivers.
USB FAQ: Introductory Level - USB Class Drivers from MS WHDC
http://www.microsoft.com/whdc/system/bus/usb/USBFAQ_intro.mspx

Please note, available drivers for a composite device are not limited only to class drivers.

Any driver can be applied, as long as it doesn‘t require a device class (class defined in device descriptor).

For example, SiLabs USB_INT and USB_bulk drivers are also applicable for composite devices.

2. How Windows handles a composite device

When a device satisfies these three requirement, Windows system recognizes the device as a composite device.

1. The class field of the device descriptor equals to zero: (bDeviceClass) = (0x00)
2. Single Configuration
3. Multiple Interfaces

[Note]
WinXP SP2, Win2k3 SP1 and Vista supports this alternative requirement.
1‘. The class, subclass and protocol fields of the device are that of Interface Association Descriptor:
(bDeviceClass, bDeviceSubClass, bDeviceProtocol) = (0xEF, 0x02, 0x01)

When an USB device is plugged in to a PC, the system reads out the device descriptor of the device and makes these Device ID.

USB\VID_vvvv&PID_pppp
USB\VID_vvvv&PID_pppp&REV_rrrr
(vvvv, pppp, rrrr: four digit hex number for the VID, PID, device release number.
Matches to idVendor/ idProduct/ bcdDevice, defined in the device descriptor)

The system searches device database on the registry, installed by INF files.
When the system finds the Device ID in a device record, it assigns the device driver specified by the record.
However, when it cannot find any matched record, and the device Configuration satisfies above criteria,
the generic composite parent driver is loaded.
This parent driver parses the Configuration of the device, and assigns this Device ID to each Interfaces. 

USB\VID_vvvv&PID_pppp&MI_mm
USB\VID_vvvv&PID_pppp&REV_rrrr&MI_mm
(mm: Interface number of the corresponding function, two digit hex number)

As of the Interface which specifies a class, the system also assigns this Compatible ID.

USB\CLASS_cc
USB\CLASS_cc&SUBCLASS_ss
USB\CLASS_cc&SUBCLASS_ss&PROT_pp
(cc/ ss / pp: two digits hex number. bInterfaceClass/ bInterfaceSubClass/ bInterfaceProtocol, from the Interface descriptor)

The system searches these Device ID and Compatible ID in the device database again.
When it finds a matched record, it assigns the specified device driver to the Interface.
However, when it cannot find any matched record, it shows ‘New Hardware Wizard‘ to users and asks them to install the device driver.

Enumeration of the Composite Parent Device from MSDN
http://msdn2.microsoft.com/en-us/library/aa476434.aspx

3. Implementation

On USB application, firmware, device driver and host application are closely related.
It is desirable to make separate prototypes of firmwares and host applications for each Interface first.
After confirming them to work properly, combine them together.

3.1 Device firmware

When the source code is well organized, modification of the firmware is easy.
Based on one of the prototypes, copy a part of code from other prototypes and insert it to corresponding part of the base source code.
In other word, the source codes should be organized considering to make it a composite device.
When these parameters are defined by #define macro or enum instead of direct number in each prototype,
the combination of prototypes is done smoothly.

• Interface number
• Endpoint address
• Endpoint status (IDLE / HALT)

3.1.1 Descriptors

3.1.1.1 Device descriptor

• bDeviceClass: Must be assigned to zero
• idVendor, idProduct: VID/PID must be unique, to avoid conflict to other devices.

3.1.1.2 Configuration descriptor

• wTotalLength: The total number of bytes of Configuration set, includes all of Interface sets
• bNumInterfaces: Number of Interfaces included in this Configuration

Configuration set means these descriptors, for example.

Configuration descriptor
- Interface descriptor (0)
- - accessory descriptor, such as HID class descriptor, if any
- - Endpoint descriptors
- Interface descriptor (1)
- - accessory descriptor, such as HID class descriptor, if any
- - Endpoint descriptors

HID report descriptor and String descriptors are not included in the Configuration set.

3.1.1.3 Interface descriptors

• bInterfaceNumber: Index of Interfaces, starting from zero
• bInterfaceClass: Specify class code for this Interface

If any specific class code is not assigned to the Interface, set bInterfaceClass to 0xFF (Vendor specific). 0x00 (Reserved) would work, but 0xFF is better.

3.1.1.4 Endpoint descriptors

• bEndpointAddress: must be unique on each Endpoint descriptor

Any duplicated Endpoint across Interfaces is not allowed in a composite device.

3.1.2 Standard requests

3.1.2.1 Additional Descriptor handling
Get_Descriptor must support additional descriptors asked by the host.

• Configuration descriptor: return full Configuration set (see 3.1.1.2)
• Class-specific descriptors:

When the descriptor type in request (MSB of wValue) is not Device(1), Configuration(2) or String(3),
the request may be for class-specific descriptor (in full-speed devices).
In this case, wIndex field of the Setup data shows the Interface number in question.
According to the class specified by the Interface (wIndex),
Get_Descriptor must return the class-specific descriptor specified by the MSB of wValue.
When the class supports Set_Descriptor request, it must be handled similarly to Get_Descriptor.
Interface and Endpoint descriptors cannot be directly accessed with Get_Descriptor or Set_Descriptor.
Therefore, Get_Descriptor and Set_Descriptor have no need to support them.

3.1.2.2 Additional Interfaces handling
wIndex field of the Setup data shows the Interface number in question.
When this Interface number matches to the additional Interfaces, handle the requests as follows.

• Get_Status: return Zero
• Get_Interface: return current alternate Interface number
• Set_Interface: set current alternate Interface to one specified by the request

When the Interface in question doesn‘t have any alternate Interface, Get_Interface returns Zero.
And Set_Interface succeeds when the wValue is Zero, otherwise return STALL.

3.1.2.3 Additional Endpoints handling

• Get_Status: return HALT condition of the Endpoint
• Clear_Feature: recover the Endpoint from HALT
• Set_Feature: set the Endpoint to HALT
• Set_Configuration: Setup additional Endpoints

When Get_Status, Clear_Feature and Set_Feature are issued to an Endpoint, wIndex field of the Setup data indicates the Endpoint address.
When the Interfaces doesn‘t have any alternate Interface, set up the Endpoints in Set_Configuration request.
As of the Interface with any alternate Interface, set up the Endpoints belonging to the Interface in Set_Interface.

3.1.3 Class-specific requests

wIndex field of the Setup data of the request indicates the Interface to which this request is issued.
Therefore, dispatch the request by wIndex first, and copy the each handler for class-specific requests from the prototypes under each case.

3.1.4 Endpoint handling

When the Endpoint address and Endpoint status are defined by macro,
modification on this part finishes by copying the Endpoint handler of each prototype to the base one.

3.2 Device driver and host application

OS built-in class drivers are designed to work with composite devices.
In most case, these drivers are applicable to composite devices without any change of default INF file.
However, device drivers provided by vendors are not always designed to work with composite devices.
INF file and host application code should be modified for these drivers.
The device driver itself should work without any change.
Of course, rare exception may exist.

3.2.1 INF file

When the device driver requires an INF file even for single use, the INF file is required as a part of composite device.
The INF file defines the Device ID as follows.

USB\VID_vvvv&PID_pppp
USB\VID_vvvv&PID_pppp&REV_rrrr

For a composite device, the Interface number must be added to this Device ID.

USB\VID_vvvv&PID_pppp&MI_mm
USB\VID_vvvv&PID_pppp&REV_rrrr&MI_mm

For example, when you add the USB_Bulk function (Interface with bulk IN/OUT Endpoints)
to your composite device as the Interface number 1, the Device ID in the INF file (SilabsBulk.inf) is modified as follows.

USB\VID_vvvv&PID_pppp&MI_01
(vvvv, pppp: VID/PID must be unique)

3.2.2 Endpoint address and pipe name / device path name

When two or more devices are combined into a single composite device,
the Endpoint addresses must be often changed to fit to the newly designed device.
Usually, the pipe name and device path name from device drivers are designed to hide the Endpoint address.
Therefore, in most case, Endpoint address reassignment doesn‘t affect to the host application.

However, there are some drivers which expose the Endpoint address directly to the pipe name.
For these drivers, the host application must be modified to reflect the Endpoint address assignment.
Confirmation for this point is desirable before planning a new device.

• OS built-in class drivers hide Endpoint address behind its device path name.
• MS WinDDK bulkusb and isousb example driver hide Endpoint address behind the pipe name (a part of device path name).
• SiLabs USB_INT and USB_Bulk device drivers hide it behind the pipe name (a part of device path name).
• Cypress ezusb.sys driver hides Endpoint address behind its pipe number.
• Cypress CyUSB.sys driver exposes Endpoint address directly.
  But when the code follows the example of CCyUSBDevice::BulkInEndPt in CyAPI.chm,
  the Endpoint address is hidden behind the index of the Endpoint array.

When a device applies the same class to multiple Interfaces, the host application should be modified to distinguish these Interfaces. 

Enumeration of USB Composite Devices