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 */