[ Class and composite device support ]

This example implements CDC and HID composite device using IAD to SiLabs 'F320/'F340 DK.

Passed the USB compliance test, USBCV 1.3, ch9 and HID test.
Tested on modified HClient host app example on WinDDK for HID interface.
Tested on RealTerm and a custom test app (modified AN197SW.zip) for serial APIs
http://www.silabs.com/public/documents/software_doc/othersoftware/Microcontrollers/en/AN197SW.zip

See these topics for the implementation details of each class.
CDC implementation is based on
"USB CDC (Communication Device Class) implementation for 'F32x and 'F34x"
http://www.cygnal.org/ubb/Forum9/HTML/000945.html

HID implementation is based on 
"How to convert USB_Interrupt (USB_INT) to HID"
http://www.cygnal.org/ubb/Forum9/HTML/001193.html

The details of composite device implementation was discussed in this topic.
"USB Composite Device"
http://www.cygnal.org/ubb/Forum9/HTML/001050.html

[ Windows version ]
A composite device of CDC with IAD is supported on these Windows version.
- WinXP SP3
- Vista SP1

[ Installation ]
CDC device requires an INF file for the installation of your PC.
Specify the INF folder attached to the zip file, on the New Hardware dialog.


[ Select compiler - Keil or SDCC ]

On the SiLabs IDE, open one of these project files, according to the compiler.
	KEIL_USB_CDC_HID_IAD.wsp
	SDCC_USB_CDC_HID_IAD.wsp
Then, the project file handles everything.

For command line users,
	memory model:	small (Keil / SDCC)
	link library:	KEIL_FIFO_RW.lib (Keil)
			SDCC_FIFO_RW.lib (SDCC)

	The source code of these libraries are included in FIFO_RW_source folder.



[ Switch the MCU type - 'F32x, 'F340 ]

The MCU type is defined in USB_Type.h, as the include file.
Select one of appropriate include file for the device. 	USB_Type.h
	#include <C8051F320.h>
	//#include <C8051F340.h>

Then, the compiler sees the symbols in the include file, like C8051F320_H, and automatically dispatches the conditional compilation in the source code.

The USB engines of these MCUs are almost common, including register assignment. The major difference is just the number of supported endpoints;
	C8051F32x, 34x  IN1-3 / OUT1-3
Therefore, the the most of source code is common, except for USB_Main.c.
In USB_Main.c, the difference of peripherals on MCUs and Dev board configuration make the source code complicated with the MCU type switch. It may be better to split the USB_Main.c into each MCU type.



[ USB_Configuration.h ]

This include file lists up the essential parameters of the USB implementation.
VID/PID, revision number, MaxPacketSize of each EP.

Other than these parameters, these items for the endpoint setting are available.

- The endpoint usage        : USE_OUT_EP1, USE_IN_EP1, etc
- Double buffer for the EP  : ENABLE_OUT_EP1_DOUBLE_BUF, etc
- Isochronous EP (*1)       : ENABLE_OUT_EP1_ISO, etc
- Interrupt usage on the EP : ENABLE_OUT_EP1_INTERRUPT, etc

(*1) When this option is disabled, the EP is handled as a bulk or interrupt EP

Using these switches, you can quickly select the endpoint configuration. Also these switches ensure the proper handling on the standard request, without further modification of the code.

- ENABLE_SUSPEND_RESUME
This option enables suspend/resume interrupts on the code.
The actual handling of suspend/resume is implemented in the USB_Main.c, Usb_Suspend() and Usb_Resume().

- ENABLE_SOF_INTERRUPT
This option enables SOF interrupt. SOF interrupt is invoked by SOF (Start Of Frame) signaling on the USB bus, which gives handy 1 ms interval. Please note, SOF interrupt is generated by the engine, even when the device is not connected to host.

- ENABLE_INLINE_POLL_READ_WRITE
This option switches the definition of POLL_READ_BYTE and POLL_WRITE_BYTE between inline macro and function. Inline macro gives faster execution, but greater code size. The function implementation does vice-versa.


[ Where is the best place to initialize the USB-related variables? ]

When you need to initialize variables every time at the USB connection, these functions are the good place to implement it.
	Usb_Reset()         (USB_ISR.c)
	OR
	Set_Configuration() (USB_Standard_Requests.c)
	( Set_Interface() )
At the device connection to USB bus, host issues bus reset - Usb_Reset() is invoked.
Then, enumeration starts and Set_Configuration() is always called (almost) at the end of enumeration.
When the device has alternate interface(s), Set_Interface() will be called. But the device doesn't have any alternate interface, Set_Interface() is not called.

In this implementation, two flags, IN_FIFO_empty, OUT_FIFO_loaded, are initialized in Set_Configuration().



[ How to handle the endpoint(s) - interrupt or polling? ]

As of the EP1-3, either will do. Select appropriate option which fits to your requirement.
In this implementation, I showed a combined method.

- interrupt IN
When you already have large size of data on a buffer (more than the MaxPacketSize of the EP), interrupt gives better performance. Enable double buffer, too.

- interrupt OUT
When the host sends large size of data to the device, interrupt gives better performance. Enable double buffer, too.

- polling IN
When you don't have any new data to send to the host, leave the FIFO unloaded. Just when you get data to send, load the data to the FIFO in the main loop. Until the firmware loads data to the FIFO, the USB engine returns NAK to the host. And the host retries the transfer again and again without any error. This is the flow control mechanism built-in to the USB protocol.

- polling OUT
When you don't want to accept new data from host until the current process finishes, polling in the main loop gives smart coding. Until the firmware unloads the FIFO, the USB engine returns NAK to the host. And the host retries the transfer again and again without any error. This is also the flow control mechanism built-in to the USB protocol.

Around the access to the USB engine from the main loop, disable USB interrupt to prevent the conflict with the USB ISR.

When you apply the polling method, you may see the host app hangs, when the host app calls ReadFile / WriteFile synchronously. When these API is called synchronously, they don't return until the transfer finishes, then they block the execution of the host app. In this case, these APIs should be called in OVERLAPPED. Or use ReadFileEX or WriteFileEx, instead.


As of the default EP (EP0), it is the usual way to split the control transfer handling into interrupt and polling;
	SETUP stage           - interrupt
	DATA and STATUS stage - polling on main loop
However, I didn't take this approach on this implementation, because of the bug of Windows (*1) and the defect of this USB engine (*2). Handling control transfers as fast as possible in the USB ISR, the chance of hang reduces.

(*1) Bug of Windows
http://support.microsoft.com/kb/892050/en-us
In this bug, TT (transaction translator) issues the next control transfer prematurely.
This bug is not fixed until the next SP (WinXP SP3).

(*2) Defect of the USB engine
This USB engine has just one common FIFO for the EP0 IN/OUT. When new SETUP is prematurely issued by host while the engine (firmware) handles previous control transfer, the FIFO write from the firmware may overwrite the new SETUP on the FIFO. This causes hang on the control transfer handling.
When common IN/OUT FIFO is applied, the engine is usually equipped a mechanism to prevent the overwrite, because SETUP has priority. I can see this mechanism on most of engines on other manufacturers. However, SiLabs engine doesn't have this mechanism, it allows the overwrite. This is the background which is not told in this SiLabs KB article.
"USB Driver Freezing"
http://portal.knowledgebase.net/article.asp?article=194217&p=4120



[ Detailed implementation suggestions ]

In USB_Standard_Requests.c, I attached suggestions for these items.
In this implementation, I chose one of popular option. If you need other option, these suggestions will guide you how to modify this implementation.

	USB_Standard_Requests.c
	- HALT and STALL handling on interrupt and bulk EPs
	- Data toggle handling on interrupt and bulk EPs
	- Bus-powered/Self-powered
	- Suspend/Resume and Remote wakeup



[ Thanks to forum members ]
This implementation has been inspired by the discussion with members on SiLabs Forum,
Patryk, vanmierlo, frief, egawtry, ReneK, dsnook, MarcelJ, and many many other members.
Thanks to you all.


Enjoy!!

Tsueno