SAMV71 Xplained Ultra Software Package 1.5

composite.dir

00001 /* ----------------------------------------------------------------------------
00002  *         ATMEL Microcontroller Software Support 
00003  * ----------------------------------------------------------------------------
00004  * Copyright (c) 2008, Atmel Corporation
00005  *
00006  * All rights reserved.
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *
00011  * - Redistributions of source code must retain the above copyright notice,
00012  * this list of conditions and the disclaimer below.
00013  *
00014  * Atmel's name may not be used to endorse or promote products derived from
00015  * this software without specific prior written permission.
00016  *
00017  * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
00018  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00019  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00020  * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
00021  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00022  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
00023  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00024  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00025  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00026  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027  * ----------------------------------------------------------------------------
00028  */
00029 
00030 /** \dir usb/device/composite
00031 
00032   \section Purpose
00033   
00034   This directory provides definitions, structs and functions for a USB 
00035   Composite device demos, to implement Multi-Function USB devices.
00036   
00037   \section Contents
00038   There are three things for the implement of the composite device driver:
00039   - Implement the function driver structs and functions for the device
00040     function, to initialize, to handle function specific requests and
00041     dispach standard requests in USBD callbacks, to read/write through
00042     assigned USB endpoints.
00043   - Implement the composite driver structs for the device,
00044     to initialize, to handle device specific requests and dispach
00045     standard requests in USBD callbacks, to read/write through assigned USB
00046     endpoints,
00047   - Create the composite device's descriptors that should be passed to
00048     the USBDDriver instance on initialization, so that the host can 
00049     recognize the device as a "composite" device.
00050   
00051   For more information, please refer to \ref usbd_composite_drv.
00052 */
00053 
00054 /** \page usbd_composite_drv USB Composite Devices Drivers
00055  
00056  This page describes how to use the \ref usbd_framework to produce a USB
00057  Composite Device Driver, which appears as two USB Functions on host.
00058  
00059  Details about the USB can be found in the <i>USB specification 2.0</i>,
00060  respectively.
00061  
00062  \section References
00063  - <a href="http://www.usb.org/developers/docs/usb_20_122909-2.zip">
00064    Universal Serial Bus Revision 2.0 specification
00065    </a> (.zip file format, size 10.9 MB)
00066  - <a href="http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf">
00067    Interface Association Descriptor
00068    </a>
00069  - \ref usbd_framework "AT91 USB device framework"
00070  - \ref usbd_enum "USB Device Enumeration"
00071  - \ref usbd_cdc_serial_drv "USB CDC(Serial) Device Driver"
00072  - \ref usbd_msd_drv "USB MSD Device Driver"
00073  - \ref usbd_hid_kbd_drv "USB HID(Keyboard) Device Driver"
00074  - \ref usbd_audio_speaker_drv "USB Audio(Speaker) Device Driver"
00075  
00076  \section composite_basic Composite Basics
00077  See \subpage usb_composite_basic
00078  
00079  \section Architecture
00080  The Composite driver is based on
00081  \ref usbd_framework_arch "USB Device Framework Architecture".
00082  
00083  \image html UsbCompositeSWArch.png "Software Architecture Using the AT91 USB Framework"
00084 
00085  \section Descriptors
00086 
00087  \subsection usb_composite_devdesc Device Descriptor
00088  The Device descriptor of a composite device is very basic according to the
00089  definition in section 9.6.1, <i>Universal Serial Bus Specification, Revision
00090  2.0</i>, but some of the fields may have different values based on if there
00091  is multi-interface function in the device: <i>bDeviceClass</i>,
00092  <i>bDeviceSubClass</i>, <i>bDeviceProtocol</i> set to zero for a device
00093  without multi-interface function inside; <i>bDeviceClass</i>,
00094  <i>bDeviceSubClass</i>, <i>bDeviceProtocol</i> set to EFH, 02H, 01H for a
00095  device with multi-interface function inside, such as CDC or Audio class
00096  function, as shown below:
00097  
00098  \code
00099         // Composite Device Descriptor
00100         const USBDeviceDescriptor deviceDescriptor = {
00101                 sizeof(USBDeviceDescriptor),
00102                 USBGenericDescriptor_DEVICE,
00103                 USBDeviceDescriptor_USB2_00,
00104               #if defined(usb_HIDMSD)
00105                 0x00,
00106                 0x00,
00107                 0x00,
00108               #else
00109                 0xEF,// MI
00110                 0x02,//
00111                 0x01,//
00112               #endif
00113                 BOARD_USB_ENDPOINTS_MAXPACKETSIZE(0),
00114                 COMPOSITEDDriverDescriptors_VENDORID,
00115                 COMPOSITEDDriverDescriptors_PRODUCTID,
00116                 COMPOSITEDDriverDescriptors_RELEASE,
00117                 0, // No string descriptor for manufacturer
00118                 1, // Index of product string descriptor is #1
00119                 0, // No string descriptor for serial number
00120                 1 // Device has 1 possible configuration
00121         };
00122  \endcode
00123 
00124  Note that the Vendor ID is a special value attributed by the USB-IF
00125  organization. The product ID can be chosen freely by the vendor.
00126  The HID and MSD class functions are all single-interface functions,
00127  so the corresponding fields are set to zeros.
00128  
00129  \subsection usb_composite_cfgdesc Configuration Descriptor
00130  
00131  It's just standard one as defined in section 9.6.3, <i>Universal Serial Bus
00132  Specification, Revision 2.0</i>, with <i>wTotalLength</i> set to the total
00133  length of all standard and function specific descriptors followed,
00134  <i>bNumInterface</i> set to the summary number of interfaces of all functions
00135  used.
00136  
00137  \code
00138         // Composite Configuration Descriptor
00139         {
00140                 sizeof(USBConfigurationDescriptor),
00141                 USBGenericDescriptor_CONFIGURATION,
00142                 sizeof(CompositeDriverConfigurationDescriptors),
00143                 COMPOSITEDDriverDescriptors_NUMINTERFACE,
00144                 1, // This is configuration #1
00145                 0, // No string descriptor for this configuration
00146                 BOARD_USB_BMATTRIBUTES,
00147                 USBConfigurationDescriptor_POWER(100)
00148         },
00149  \endcode
00150  
00151  When the Configuration descriptor is requested by the host
00152  (by using the GET_DESCRIPTOR command), the device must also send all the
00153  related descriptors, i.e. IAD, Interface, Endpoint and Class-specific
00154  descriptors. It is convenient to create a single structure to hold all this
00155  data, for sending everything in one trunk.
00156  
00157  \subsection IAD
00158  See \ref usb_composite_iad.
00159  
00160  \subsection usb_composite_ifepdesc Interface, Class-Specific & Endpoint Descriptors
00161  
00162  All these descriptors are almost the same as their definitions in a single USB
00163  device, except the interface index related or endpoint addresses related
00164  settings. Please refer to the following projects:
00165  - MSD: \ref usbd_msd_drv, \ref usb_massstorage
00166  - CDC: \ref usbd_cdc_serial_drv, \ref usb_cdc_serial
00167  - HID: \ref usbd_hid_kbd_drv, \ref usb_hid_keyboard
00168  - Audio: \ref usbd_audio_speaker_drv, \ref usb_audio_speaker
00169  
00170  \subsection usb_composite_strdesc String Descriptors
00171  
00172  Several descriptors can be commented with a String Descriptor. The latter is
00173  completely optional and does not have any effect on the detection of the
00174  device by the operating system. Whether or not to include them is entirely up
00175  to the programmer.
00176  
00177  There is one exception to this rule when using the MSD class. According to the
00178  specification, there must be a <b>Serial Number</b> string. It must contains at
00179  least 12 characters, and these character must only be either letters (a-z, A-Z)
00180  or numbers (0-9). This cause no problem for the driver in practice, but this is
00181  a strict requirement for certification. Also please remember that string
00182  descriptors use the <b>Unicode</b> format.
00183  
00184  \section Requests
00185 
00186  The composite itself does not define any special requests, but the device
00187  functions do.
00188 
00189  Each function in the device has its own requests handler. The device invokes
00190  one of the function requests handler first, when the return value of the
00191  handler indicates the request is handled by the device function, then the
00192  device request handler return directly, but if it is not handled, the device
00193  request handler calls next function request handler to check it. It will be
00194  forwarded to the standard request handler if there is no valid handler for
00195  this request.
00196 
00197  In the device function request handlers, <i>wIndex</i> of the request is
00198  checked first to confirm that the request is accepted by the function
00199  (interface). Then check if it is a standard request and handle it in two
00200  different way.
00201   
00202  \image html UsbCompositeRequestHandler.png "General Request Handler for Composite Device"
00203  
00204  For class-specific request, refer to their related documents:
00205  - MSD: \ref usbd_msd_drv, \ref usb_massstorage
00206  - CDC: \ref usbd_cdc_serial_drv, \ref usb_cdc_serial
00207  - HID: \ref usbd_hid_kbd_drv, \ref usb_hid_keyboard
00208  - Audio: \ref usbd_audio_speaker_drv, \ref usb_audio_speaker
00209 
00210  \section Notifications
00211  
00212  Notifications are supported only if CDC serial port device function is
00213  included, please refer to \ref usbd_cdc_serial_drv.
00214  
00215  \section Callbacks
00216  
00217  The function in the device may need some callbacks to handle the USB events,
00218  such as configured or changed interface.
00219  
00220  \subsection composite_hid_kbd_cb HID Keybard Function Callbacks
00221  For a HID Keyboard, the device function should start reporting to host through
00222  interrupt endpoint as soon as the device is configured, so
00223  USBDDriverCallbacks_ConfigurationChanged() should be re-implement to monitor
00224  the configured status of the device, and then forward the event to the
00225  device function to handle it. For more details, see \ref usbd_hid_kbd_drv.
00226  
00227  \subsection composite_aud_cb Audio Speaker Function Callbacks
00228  The USB Audio Speaker defines alternative interfaces to control the USB
00229  bandwidth, so there is a callback defined to handle the event of AT91 USB
00230  Device Framework. The function is
00231  USBDDriverCallbacks_InterfaceSettingChanged(), which should be
00232  re-implemented to replace the original one.
00233  AUDDFunctionCallbacks_InterfaceSettingChanged() is invoked and then let the
00234  Audio Device Function to handle the event. For more details,
00235  see \ref usbd_audio_speaker_drv.
00236  
00237  \section composite_driver_demo Composite Device Examples
00238  
00239  \subsection HID+MSD
00240  
00241  \image html UsbCompositeHidMsdArch.png "HID MSD Composite Driver Architecture"
00242  
00243  Device descriptors:
00244  \code
00245         typedef struct {
00246                 // Standard configuration descriptor.
00247                 USBConfigurationDescriptor configuration;
00248                 // --- HID
00249                 USBInterfaceDescriptor hidInterface;
00250                 HIDDescriptor hid;
00251                 USBEndpointDescriptor hidInterruptIn;
00252                 USBEndpointDescriptor hidInterruptOut;
00253                 // --- MSD
00254                 // Mass storage interface descriptor.
00255                 USBInterfaceDescriptor msdInterface;
00256                 // Bulk-out endpoint descriptor.
00257                 USBEndpointDescriptor msdBulkOut;
00258                 // Bulk-in endpoint descriptor.
00259                 USBEndpointDescriptor msdBulkIn;
00260         } __attribute__ ((packed)) CompositeDriverConfigurationDescriptors;
00261  \endcode
00262  
00263  \subsection HID+Audio
00264 
00265  \image html UsbCompositeHidAudioArch.png "HID Audio Composite Device Architecture"
00266  
00267  Device descriptors:
00268  \code
00269         typedef struct {
00270                 // Standard configuration descriptor.
00271                 USBConfigurationDescriptor configuration;
00272                 // --- HID
00273                 USBInterfaceDescriptor hidInterface;
00274                 HIDDescriptor hid;
00275                 USBEndpointDescriptor hidInterruptIn;
00276                 USBEndpointDescriptor hidInterruptOut;
00277                 // --- AUDIO
00278                 // IAD 1
00279                 USBInterfaceAssociationDescriptor audIAD;
00280                 // Audio control interface.
00281                 USBInterfaceDescriptor audInterface;
00282                 // Descriptors for the audio control interface.
00283                 AUDDSpeakerDriverAudioControlDescriptors audControl;
00284                 // -- AUDIO out
00285                 // Streaming out interface descriptor (with no endpoint, required).
00286                 USBInterfaceDescriptor audStreamingOutNoIsochronous;
00287                 // Streaming out interface descriptor.
00288                 USBInterfaceDescriptor audStreamingOut;
00289                 // Audio class descriptor for the streaming out interface.
00290                 AUDStreamingInterfaceDescriptor audStreamingOutClass;
00291                 // Stream format descriptor.
00292                 AUDFormatTypeOneDescriptor1 audStreamingOutFormatType;
00293                 // Streaming out endpoint descriptor.
00294                 AUDEndpointDescriptor audStreamingOutEndpoint;
00295                 // Audio class descriptor for the streaming out endpoint.
00296                 AUDDataEndpointDescriptor audStreamingOutDataEndpoint;
00297         } __attribute__ ((packed)) CompositeDriverConfigurationDescriptors;
00298  \endcode
00299  
00300  \subsection CDC+HID
00301 
00302  \image html UsbCompositeCdcHidArch.png "CDC HID Composite Device Architecture"
00303 
00304  Device descriptors:
00305  \code
00306         typedef struct {
00307                 // Standard configuration descriptor.
00308                 USBConfigurationDescriptor configuration;
00309                 // --- CDC 0
00310                 // IAD 0
00311                 USBInterfaceAssociationDescriptor cdcIAD0;
00312                 // Communication interface descriptor
00313                 USBInterfaceDescriptor cdcCommunication0;
00314                 // CDC header functional descriptor.
00315                 CDCHeaderDescriptor cdcHeader0;
00316                 // CDC call management functional descriptor.
00317                 CDCCallManagementDescriptor cdcCallManagement0;
00318                 // CDC abstract control management functional descriptor.
00319                 CDCAbstractControlManagementDescriptor cdcAbstractControlManagement0;
00320                 // CDC union functional descriptor (with one slave interface).
00321                 CDCUnionDescriptor cdcUnion0;
00322                 // Notification endpoint descriptor.
00323                 USBEndpointDescriptor cdcNotification0;
00324                 // Data interface descriptor.
00325                 USBInterfaceDescriptor cdcData0;
00326                 // Data OUT endpoint descriptor.
00327                 USBEndpointDescriptor cdcDataOut0;
00328                 // Data IN endpoint descriptor.
00329                 USBEndpointDescriptor cdcDataIn0;
00330                 // --- HID
00331                 USBInterfaceDescriptor hidInterface;
00332                 HIDDescriptor hid;
00333                 USBEndpointDescriptor hidInterruptIn;
00334                 USBEndpointDescriptor hidInterruptOut;
00335         } __attribute__ ((packed)) CompositeDriverConfigurationDescriptors;
00336  \endcode
00337  
00338  \subsection CDC+MSD
00339 
00340  \image html UsbCompositeCdcMsdArch.png "CDC MSD Composite Device Architecture"
00341 
00342  Device descriptors:
00343  \code
00344         typedef struct {
00345                 // Standard configuration descriptor.
00346                 USBConfigurationDescriptor configuration;
00347                 // --- CDC 0
00348                 // IAD 0
00349                 USBInterfaceAssociationDescriptor cdcIAD0;
00350                 // Communication interface descriptor
00351                 USBInterfaceDescriptor cdcCommunication0;
00352                 // CDC header functional descriptor.
00353                 CDCHeaderDescriptor cdcHeader0;
00354                 // CDC call management functional descriptor.
00355                 CDCCallManagementDescriptor cdcCallManagement0;
00356                 // CDC abstract control management functional descriptor.
00357                 CDCAbstractControlManagementDescriptor cdcAbstractControlManag
00358                 // CDC union functional descriptor (with one slave interface).
00359                 CDCUnionDescriptor cdcUnion0;
00360                 // Notification endpoint descriptor.
00361                 USBEndpointDescriptor cdcNotification0;
00362                 // Data interface descriptor.
00363                 USBInterfaceDescriptor cdcData0;
00364                 // Data OUT endpoint descriptor.
00365                 USBEndpointDescriptor cdcDataOut0;
00366                 // Data IN endpoint descriptor.
00367                 USBEndpointDescriptor cdcDataIn0;
00368                 // --- MSD
00369                 // Mass storage interface descriptor.
00370                 USBInterfaceDescriptor msdInterface;
00371                 // Bulk-out endpoint descriptor.
00372                 USBEndpointDescriptor msdBulkOut;
00373                 // Bulk-in endpoint descriptor.
00374                 USBEndpointDescriptor msdBulkIn;
00375         } __attribute__ ((packed)) CompositeDriverConfigurationDescriptors;
00376  \endcode
00377  
00378  \subsection CDC+Audio
00379 
00380  \image html UsbCompositeCdcAudioArch.png "CDC Audio Composite Device Architecture"
00381 
00382  Device descriptors:
00383  \code
00384         typedef struct {
00385                 // Standard configuration descriptor.
00386                 USBConfigurationDescriptor configuration;
00387                 // --- CDC 0
00388                 // IAD 0
00389                 USBInterfaceAssociationDescriptor cdcIAD0;
00390                 // Communication interface descriptor
00391                 USBInterfaceDescriptor cdcCommunication0;
00392                 // CDC header functional descriptor.
00393                 CDCHeaderDescriptor cdcHeader0;
00394                 // CDC call management functional descriptor.
00395                 CDCCallManagementDescriptor cdcCallManagement0;
00396                 // CDC abstract control management functional descriptor.
00397                 CDCAbstractControlManagementDescriptor cdcAbstractControlManagement0;
00398                 // CDC union functional descriptor (with one slave interface).
00399                 CDCUnionDescriptor cdcUnion0;
00400                 // Notification endpoint descriptor.
00401                 USBEndpointDescriptor cdcNotification0;
00402                 // Data interface descriptor.
00403                 USBInterfaceDescriptor cdcData0;
00404                 // Data OUT endpoint descriptor.
00405                 USBEndpointDescriptor cdcDataOut0;
00406                 // Data IN endpoint descriptor.
00407                 USBEndpointDescriptor cdcDataIn0;
00408                 // --- AUDIO
00409                 // IAD 1
00410                 USBInterfaceAssociationDescriptor audIAD;
00411                 // Audio control interface.
00412                 USBInterfaceDescriptor audInterface;
00413                 // Descriptors for the audio control interface.
00414                 AUDDSpeakerDriverAudioControlDescriptors audControl;
00415                 // -- AUDIO out
00416                 // Streaming out interface descriptor (with no endpoint, required).
00417                 USBInterfaceDescriptor audStreamingOutNoIsochronous;
00418                 // Streaming out interface descriptor.
00419                 USBInterfaceDescriptor audStreamingOut;
00420                 // Audio class descriptor for the streaming out interface.
00421                 AUDStreamingInterfaceDescriptor audStreamingOutClass;
00422                 // Stream format descriptor.
00423                 AUDFormatTypeOneDescriptor1 audStreamingOutFormatType;
00424                 // Streaming out endpoint descriptor.
00425                 AUDEndpointDescriptor audStreamingOutEndpoint;
00426                 // Audio class descriptor for the streaming out endpoint.
00427                 AUDDataEndpointDescriptor audStreamingOutDataEndpoint;
00428         } __attribute__ ((packed)) CompositeDriverConfigurationDescriptors;
00429  \endcode
00430  
00431  \subsection CDC+CDC(Dual CDC)
00432 
00433  \image html UsbCompositeCdcCdcArch.png "Dual CDC Composite Device Architecture"
00434 
00435  Device descriptors:
00436  \code
00437         typedef struct {
00438                 // Standard configuration descriptor.
00439                 USBConfigurationDescriptor configuration;
00440                 // --- CDC 0
00441                 // IAD 0
00442                 USBInterfaceAssociationDescriptor cdcIAD0;
00443                 // Communication interface descriptor
00444                 USBInterfaceDescriptor cdcCommunication0;
00445                 // CDC header functional descriptor.
00446                 CDCHeaderDescriptor cdcHeader0;
00447                 // CDC call management functional descriptor.
00448                 CDCCallManagementDescriptor cdcCallManagement0;
00449                 // CDC abstract control management functional descriptor.
00450                 CDCAbstractControlManagementDescriptor cdcAbstractControlManagement0;
00451                 // CDC union functional descriptor (with one slave interface).
00452                 CDCUnionDescriptor cdcUnion0;
00453                 // Notification endpoint descriptor.
00454                 USBEndpointDescriptor cdcNotification0;
00455                 // Data interface descriptor.
00456                 USBInterfaceDescriptor cdcData0;
00457                 // Data OUT endpoint descriptor.
00458                 USBEndpointDescriptor cdcDataOut0;
00459                 // Data IN endpoint descriptor.
00460                 USBEndpointDescriptor cdcDataIn0;
00461                 // --- CDC 1
00462                 // IAD 1
00463                 USBInterfaceAssociationDescriptor cdcIAD1;
00464                 // Communication interface descriptor
00465                 USBInterfaceDescriptor cdcCommunication1;
00466                 // CDC header functional descriptor.
00467                 CDCHeaderDescriptor cdcHeader1;
00468                 // CDC call management functional descriptor.
00469                 CDCCallManagementDescriptor cdcCallManagement1;
00470                 // CDC abstract control management functional descriptor.
00471                 CDCAbstractControlManagementDescriptor cdcAbstractControlManagement1;
00472                 // CDC union functional descriptor (with one slave interface).
00473                 CDCUnionDescriptor cdcUnion1;
00474                 // Notification endpoint descriptor.
00475                 USBEndpointDescriptor cdcNotification1;
00476                 // Data interface descriptor.
00477                 USBInterfaceDescriptor cdcData1;
00478                 // Data OUT endpoint descriptor.
00479                 USBEndpointDescriptor cdcDataOut1;
00480                 // Data IN endpoint descriptor.
00481                 USBEndpointDescriptor cdcDataIn1;
00482         } __attribute__ ((packed)) CompositeDriverConfigurationDescriptors;
00483  \endcode
00484 
00485  \section composite_main Main Application
00486  
00487  Normally the main application code can be divided into four parts:
00488  - initialization
00489  - interrupt handlers
00490  - callback handlers
00491  - main loop
00492  See the source code and the device related application notes for more details.
00493  
00494  \subsection Initialization
00495  
00496  This part initializes all peripherals and drivers, depending on the functions
00497  which are included. Normally there are following general initializations:
00498  - debug initialization
00499  - USB Vbus detect (PIO) initialization
00500  - composite device driver initialization
00501  - initializations are based on the working functions:
00502    - clock PIO and clock settings for USB Audio device
00503    - HID keyboard PIO initialization
00504    - AC97 or SPI & SSC or DAC for Audio playback initialization
00505    - MSD Media and LUN initialization
00506    - extra initializations may be needed for timers.
00507 
00508  \subsection usb_composite_irq_handler Interrupt Handlers
00509  
00510  This part includes the necessary handler for Vbus detect, the media handler for
00511  MSD device function, USART handler for CDC serial port, and the SSC handler for
00512  Audio device function if needed. One extra handler may be needed for the
00513  timer or PIT or SYSTICK.
00514  
00515  \subsection Callbacks
00516  
00517  Some of the device function requires callback handler to execute the request
00518  from host, such as the mute state changed by the host, or data received or
00519  sent, so that another transfer can be started.
00520  
00521  \subsection usb_composite_main_loop Main Loop
00522  
00523  All driver function is non-blocked function, and many of them is called in the
00524  main loop, to receive data from the host, to scan the input keys and send
00525  report to host (for HID), to run the state machine (for MSD).
00526 
00527  \section composite_host_driver Using a Generic Host Driver
00528  
00529  The device functions are generally supported by Microsoft Windows, but for
00530  composite device, some patches are needed. All the composite devices above are
00531  tested under windows XP (SP3) and works fine. For CDC serial port, additional
00532  windows driver file (.inf) is required.
00533  
00534  \subsection usb_composite_win_patch Windows Patches
00535  See \ref usb_composite_win_driver_up.
00536  
00537  \subsection usb_composite_win_cdc_inf Windows Driver Files for CDC Serial Function
00538  
00539  In order to make windows recognize the CDC serial device correctly, it is
00540  necessary to write a .inf file. Please refer to \ref usbd_cdc_serial_drv for
00541  detailed information. Only one thing should be modified to match the composite
00542  device function installation.
00543  
00544  For composite devices, the hardware ID is made up of the Vender ID, the Product
00545  ID and (optionally) the Device Release Number and the start interface number of
00546  the function. Those values are extracted from the device descriptors provided
00547  during the enumeration phase, the following is the example of the modification
00548  for the dual-port CDC serial:
00549  
00550  \code
00551 [AtmelMfg]
00552 %USBtoSerialConverter%=USBtoSer.Install,USB\VID_03EB&PID_6119&MI_00 ; 1st 
00553 COM device
00554 %USBtoSerialConverter%=USBtoSer.Install,USB\VID_03EB&PID_6119&MI_02 ; 2nd COM device 
00555  \endcode
00556  
00557  When a new device is plugged in for the first time, Windows looks for an
00558  appropriate specific or generic driver to use it. The composite device will be
00559  recognized as ˇ°USB Composite Deviceˇ±. Then Windows search the driver for the
00560  functions inside the composite device.
00561  
00562  Please refer to the driver function related application notes for more details.
00563  The final installation file is as following:
00564  
00565  \code
00566 [Version]
00567 Signature="$Chicago$"
00568 Class=Ports
00569 ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318}
00570 Provider=%ATMEL%
00571 DriverVer=09/12/2006,1.1.1.5
00572 [DestinationDirs]
00573 DefaultDestDir=12
00574 [Manufacturer]
00575 %ATMEL%=AtmelMfg
00576 [AtmelMfg]
00577 %USBtoSerialConverter%=USBtoSer.Install,USB\VID_03EB&PID_6127&MI_00
00578 %USBtoSerialConverter%=USBtoSer.Install,USB\VID_03EB&PID_6128&MI_00
00579 %USBtoSerialConverter%=USBtoSer.Install,USB\VID_03EB&PID_6129&MI_00
00580 %USBtoSerialConverter%=USBtoSer.Install,USB\VID_03EB&PID_6119&MI_00
00581 %USBtoSerialConverter%=USBtoSer.Install,USB\VID_03EB&PID_6119&MI_02
00582 [USBtoSer.Install]
00583 include=mdmcpq.inf
00584 CopyFiles=FakeModemCopyFileSection
00585 AddReg=USBtoSer.AddReg
00586 [USBtoSer.AddReg]
00587 HKR,,DevLoader,,*ntkern
00588 HKR,,NTMPDriver,,usbser.sys
00589 HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider"
00590 [USBtoSer.Install.Services]
00591 AddService=usbser,0x00000002,USBtoSer.AddService
00592 [USBtoSer.AddService]
00593 DisplayName=%USBSer%
00594 ServiceType=1
00595 StartType=3
00596 ErrorControl=1
00597 ServiceBinary=%12%\usbser.sys
00598 [Strings]
00599 ATMEL="ATMEL Corp."
00600 USBtoSerialConverter="AT91 USB to Serial Converter"
00601 USBSer="USB Serial Driver"
00602  \endcode
00603 
00604  */
00605 
00606 /** \page usb_composite_basic USB Composite Basics
00607  
00608  This page gives generic details on the USB Composite Devices.
00609  
00610  \section Purpose
00611 
00612  The Universal Serial Bus (USB) offers an easy way to connect PC with portable
00613  devices and to expand external peripherals. Usually a USB device provides a
00614  single function to the host, such as a storage disk, serial RS-232 port,
00615  digital microphone, or speakers, so one function occupies one USB port.
00616  Nevertheless, to allow several functions through a single physical port, the
00617  USB specification mentions two kinds of devices:
00618  - Composite device: a device has multiple logical interfaces controlled
00619    independently of each other. A single physical logical address is used
00620    for the device.
00621  - Compound device: a separate hub with multiple functions attached.
00622 
00623  Composite devices are an efficient solution to reduce the number of hub and USB
00624  cables. To set an example a device being in the same time modem and audio
00625  speaker requires only a single USB cable.
00626  
00627  \section Architecture
00628  
00629  \subsection usb_composite_layers USB Composite Composition
00630  Shows different communication flows between composite clients
00631  (host side) and functions (device side).
00632 
00633  \image html UsbCompositeComposition.png "USB composite composition"
00634  
00635  \subsection usb_composite_if USB Composite Interfaces
00636  Interfaces descriptors for composite devices includes all functions' interfaces.
00637  - <i>bInterfaceNumber</i> should start from 0 and then increased by one;
00638  - the interfaces that used in the same function should be placed together, that is,
00639    the value of <i>bInterfaceNumber</i> should be contiguous;
00640  - if two or more interfaces are associated to one device function (such as CDC), the
00641    Interface Association Descriptor (IAD, \ref usb_composite_iad) is used.
00642 
00643  Following is architecture of interface for single/multi interface functions.
00644 
00645  \image html UsbCompositeSingleIF.png "USB Composite Device with SINGLE-interface-functions"
00646 
00647  \image html UsbCompositeMultiIF.png "USB Composite Device with MULTI-interface-functions"
00648  
00649  \subsection usb_composite_iad Interface Association Descriptor
00650  
00651  The Interface Association Descriptor (IAD) is a new standard descriptor defined
00652  in USB Engineering Change Notice, to allow a device to describe which interfaces
00653  are associated with the same device function. This allows the Operation System
00654  to bind all of the appropriate interfaces to the same driver instance for the
00655  function. Please see USB ENGINEERING CHANGE NOTICE (Title:
00656  <a href="http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf">
00657  Interface Association Descriptor</a>) for detailed information.
00658  
00659  The IAD is used to describe that two or more interfaces are associated to the
00660  same function. The 'association' includes two or more interfaces and all of
00661  their alternative setting interfaces. A device must use an IAD for each multi-
00662  interfaced device function. An IAD is always returned as part of the
00663  configuration information returned by a GetConfigurationDescriptor request. It
00664  must be located before the interface descriptors (including all alternate
00665  settings) for the interfaces it associates with. All of the interface numbers
00666  in a particular set of associated interfaces must be contiguous. Following
00667  shows the standard interface association descriptor includes function class,
00668  subclass and protocol fields. The values in these fields can be the same as the
00669  values from interface class, subclass and protocol from any one of the
00670  associated interfaces.
00671 
00672 <table>
00673 <tr><td><b>Offset</b></td>
00674     <td><b>Field</b></td>
00675     <td><b>Size</b></td>
00676     <td><b>Value</b></td>
00677     <td><b>Description</b></td></tr>
00678 <tr><td>0</td>
00679     <td>bLength</td>
00680     <td>1</td>
00681     <td>Number</td>
00682     <td>Size of descriptor in bytes</td></tr>
00683 <tr><td>1</td>
00684     <td>bDescriptorType</td>
00685     <td>1</td>
00686     <td>Constant</td>
00687     <td>INTERFACE ASSOCIATION Descriptor</td></tr>
00688 <tr><td>2</td>
00689     <td>bFirstInterface</td>
00690     <td>1</td>
00691     <td>Number</td>
00692     <td>Interface Number of the first interface that is associated with this function.</td></tr>
00693 <tr><td>3</td>
00694     <td>bInterfaceCount</td>
00695     <td>1</td>
00696     <td>Number</td>
00697     <td>Number of contiguous interfaces that are associated with this function.</td></tr>
00698 <tr><td>4</td>
00699     <td>bFunctionClass</td>
00700     <td>1</td>
00701     <td>Class</td>
00702     <td>Class code (assigned by USB-IF).<br>
00703         A value of zero is not allowed in this descriptor.
00704         If this field is FFH, the function class is vendor-
00705         specific.<br>
00706         All Other values are reserved for assignment 
00707         by the USB-IF.</td></tr>
00708 <tr><td>5</td>
00709     <td>bFunctionSubClass</td>
00710     <td>1</td>
00711     <td>SubClass</td>
00712     <td>Subclass code (assigned by USB-IF).<br>
00713         If the bFunctionClass field is not set to FFH all 
00714         values are reserved for assignment by the 
00715         USB-IF.</td></tr>
00716 <tr><td>6</td>
00717     <td>bFunctionProtocol</td>
00718     <td>1</td>
00719     <td>Protocol</td>
00720     <td>Protocol code (assigned by USB-IF).<br>
00721         These codes are qualified by the values of the 
00722         bFunctionClass and bFunctionSubClass fields.</td></tr>
00723 <tr><td>7</td>
00724     <td>iFunction</td>
00725     <td>1</td>
00726     <td>Index</td>
00727     <td>Index of string descriptor which describes this 
00728         function.</td></tr>
00729 </table> 
00730  
00731  Since this particular feature was not included in earlier versions of the
00732  USB specification, there is issue about how existing USB OS implementations
00733  will support devices that use this descriptor. It is strongly recommended 
00734  that the device implementation utilizing the interface association descriptor 
00735  use the Multi-interface Function Class code in the device descriptor. The 
00736  Multi-Interface Function Class code is documented on the 
00737  http://www.usb.org/developers/docs web site.
00738  
00739  \subsection Requests
00740  
00741  No special request is used for a composite device, all requests are defined by
00742  the device function that is integrated.
00743 
00744  \section usb_composite_basic_driver Host Drivers
00745  See \subpage usb_composite_host_driver "Composite Host Drivers"
00746  */
00747 
00748 /** \page usb_composite_host_driver Composite Host Drivers
00749  This page describes host support drivers for USB Composite Devices.
00750  
00751  Usually the Operating System supports the composite device via two part of
00752  drivers - composite driver and the function drivers depending on the functions
00753  that are integrated. The OS will recognize the USB device as a composite
00754  device first then distinguish the included functions and install their driver
00755  modules one by one. Then the functions will appear as normal separated
00756  devices for OS to access.
00757 
00758  Most OSs now include generic drivers for a wide variety of USB classes. This
00759  makes developing a function device simpler, since the host complexity is now
00760  handled by the OS. Manufacturers can thus concentrate on the device itself,
00761  not on developing specific host drivers.
00762  
00763  As described before in \ref usb_composite_basic, the IAD of multi-interface
00764  USB devices is a new feature introduced for composite device, there may be
00765  issues about how existing USB OS implementations will support devices with
00766  IAD. For Linux, it is supported now. For Windows you can refer to
00767  <a href="http://www.microsoft.com/whdc/archive/IAD.mspx">
00768  Support for USB Interface Association Descriptor in Windows</a>,
00769  but patches may needed, only Windows XP with some hot fix or service pack 3 
00770  or later updates fully support this feature now (See
00771  \subpage usb_composite_win_driver_up).
00772 
00773  Here is a brief list of the various function implementations supported by
00774  several OSs (for CDC maybe additional .inf file is required to install
00775  the device but the driver files themselves are from windows source disk):
00776  - Windows (see
00777    <a href="http://msdn.microsoft.com/en-us/library/ms794253.aspx">
00778    Windows Supported USB Classes</a> for more)
00779    - MSD: USB Storage disks
00780    - HID: USB Keyboard, Mouse, etc.
00781    - Audio: USB Desktop speaker, recorder.
00782    - CDC: Abstract Control Model, Remote NDIS ...
00783  - Linux (see <a href="http://www.linux-usb.org/devices.html">
00784    Linux Device Driver Support</a> for more)
00785    - MSD: USB Storage disks
00786    - HID: USB Keyboard, Mouse, etc.
00787    - CDC: Abstract Control Model
00788    - CDC: Ethernet Model
00789 
00790  Please refer to the sections about the functions or the class implement
00791  application notes for details about the OS compatibility on the device
00792  driver.
00793 
00794  */
00795 
00796 /** \page usb_composite_win_driver_up Windows Driver Update For Composite
00797  
00798   The composite device is generally supported by Microsoft windows, but some
00799   patches are needed for muti-interface functions such as CDC & Audio. The
00800   example composite devices are tested under windows XP (SP3). For CDC
00801   serial port, additional windows driver file (CompositeCDCSerial.inf) can
00802   be found at at91lib\\usb\\device\\composite\\drv\\CompositeCDCSerial.inf.
00803  
00804   The following is alternate update to fix the composite device support
00805   on windows XP:
00806 
00807   \section install_win_sp3 Install Windows Service Pack 3 (SP3)
00808  
00809   All the fixes for USB generic driver are included in window XP service pack
00810   3. It can be found at
00811   <a href="http://technet.microsoft.com/zh-cn/windows/bb794714(en-us).aspx">
00812   http://technet.microsoft.com/zh-cn/windows/bb794714(en-us).aspx</a>.
00813  
00814   \section install_win_hotfix Install Windows Hot Fixes
00815  
00816   Two hot fixes are necessary for window to recognize the composite device
00817   correctly:
00818   -# http://support.microsoft.com/kb/814560
00819   -# http://support.microsoft.com/kb/918365
00820  */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines