cdc-serial.dir

本程序是以前程序的升级

/* ----------------------------------------------------------------------------
 *         ATMEL Microcontroller Software Support 
 * ----------------------------------------------------------------------------
 * Copyright (c) 2008, Atmel Corporation
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the disclaimer below.
 *
 * Atmel's name may not be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
 * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * ----------------------------------------------------------------------------
 */

//------------------------------------------------------------------------------
/// \dir
///
/// !!!Purpose
///
/// This directory provides definitions, structs and functions for a USB CDC
/// %device - USB CDC Serial Converter demo, to implement an USB Serial COM port
/// driver.
///
/// !!!Contents
///
/// There are two things for the implement of the USB CDC Serial %device driver:
/// - Implement the CDC Serial driver structs and functions for the %device,
///   to initialize, to handle CDC-specific requests and dispach
///   standard requests in USBD callbacks, to read/write through assigned USB
///   endpoints,
/// - Create the CDC Serial device's descriptors that should be passed to
///   the USBDDriver instance on initialization, so that the host can 
///   recognize the %device as a USB CDC Serial COM port %device.
///
/// For more information about what a particular group contains, please refer to
/// "USB CDC Serial Device".
//------------------------------------------------------------------------------

/**
 \page "USB CDC Serial Device"
 This page describes how to use the USB framework to produce a USB CDC Serial
 Device driver, which appears as a virtual COM port on host.

 !!!References
 - "AT91 USB device framework"
 - "USB Device Enumeration"
 - <a href="http://www.usb.org/developers/docs/usb_20_040908.zip">
   Universal Serial Bus Revision 2.0 specification
   </a> (.zip file format, size 9.80 MB)
 - <a href="http://www.usb.org/developers/devclass_docs/CDC1.2_WMC1.1.zip">
   Communication Device Class Documents</a> (.zip file format)
 - Abstract Control Model Serial Emulation (USB Class Definitions for
   Communication Devices, section 3.6.2.1).

 !!!Communication Device Class

 You can get some basic information about the Communication Device Class.

 !!Purpose

 CDC is used to connect communication devices, such as modems (digital or
 analog), telephones or networking devices. Its generic framework supports a
 wide variety of physical layers (xDSL, ATM, etc.) and protocols.

 In this document, CDC is used to implement a USB to a serial data converter.
 A USB to serial converter can be used in this case to bridge a legacy RS-232
 interface with a USB port.

 !!Architecture
 ...
 
 !Communication Class Interface
 The #Communication Class Interface# is used for %device management. It
 includes requests to manage the %device state, its responses, as well as
 event notifications. This interface can also be optionally used for call
 management, i.e., setting up and terminating calls as well as managing
 their parameters.

 The interface requires at least one endpoint (#Default EP0#) to used for
 %device management. Optionally, another endpoint can be dedicated to
 event notification. This will usually be an #Interrupt IN# endpoint.

 !Data Class Interface
 The #Data Class Interface# is used for generic data transmissions. It provides
 a means for a communication %device to actually transfer data to and from the
 host. In addition, it also enables the multiplexing of data and commands on
 the same interface, through the use of wrappers.

 %Endpoints for this interface must exist in pairs of the same type. This is
 necessary to allow both IN and OUT communication. Only the #Bulk# and
 #Isochronous# types can be used for these %endpoints.

 \image CDCArchitecture.png "CDC Class Driver Architecture"

 !Models
 To account for the wide variety of existing communication devices, several
 #models# have been defined, for more details you can refer to CDC spec. 1.1.
 - POTS (Plain Old Telephone Service)
    - Direct Line Control Model
    - Datapump Model
    - Abstract Control Model (ACM)
 - Telephone
    - Telephone Control Model
 - ISDN
    - Multi-Channel Model
    - USB CAPI Model
 - Networking
    - Ethernet Networking Model
    - ATM Networking Control Model

 !Class-specific Descriptors
 CDC-specific information is described using Functional Descriptors. They
 define various parameters of an interface, such as how the %device handles
 call management, or model-specific attributes.

 Since the CDC specification defines quite a number of functional descriptors,
 they are not detailed here. Instead, they are presented in the various case
 studies of this document in which they are used.

 !!Host Drivers
 Most Operating Systems (OS) now include generic drivers for a wide variety of
 USB classes. This makes developing a %device simpler, since the host complexity
 is now handled by the OS. Manufacturers can thus concentrate on the %device
 itself, not on developing specific host drivers.

 Here is a brief list of the various CDC implementations supported by several
 OS:
 - Windows
     - Abstract Control Model
     - Remote NDIS
 - Linux
     - Abstract Control Model
     - Ethernet Model

 !!!USB to Serial Converter
 This section describes the implementation of the USB to serial converter using
 the CDC class and the AT91 USB Device Framework.

 !!Bridging a Legacy Device and a Host with USB-Serial Converter
 \image USB-SerialConverter.png

 !!Model
 The CDC specification defines a model which suits this application perfectly:
 the #Abstract Control Model (ACM)#. It implements the requests and
 notifications necessary to communicate with an RS-232 interface.

 The Abstract Control Model requires two interfaces, one #Communication Class
 Interface# and one #Data Class Interface#. Each of them must have two
 associated endpoints. The former shall have one endpoint dedicated to %device
 management (default Control endpoint 0) and one for events notification
 (additional Interrupt IN endpoint).

 The Data Class Interface needs two endpoints through which to carry data to
 and from the host. Depending on the application, these endpoints can either
 be Bulk or Isochronous. In the case of a USB to serial converter, using Bulk
 endpoints is probably more appropriate, since the reliability of the
 transmission is important and the data transfers are not time-critical.

 !!Descriptors
 The descriptors are modtly standard ones. The following code examples thus
 use the structures described in the "AT91 USB device framework".

 For CDC-specific descriptors, some new types are defined:
 - CDCHeaderDescriptor
 - CDCCallManagementDescriptor
 - CDCAbstractControlManagementDescriptor
 - CDCUnionDescriptor

 All the descriptors can be found in CDCDSerialDriverDescriptors.c.

 !Device Descriptor
 \code
const USBDeviceDescriptor deviceDescriptor = {
    sizeof(USBDeviceDescriptor),
    USBGenericDescriptor_DEVICE,
    USBDeviceDescriptor_USB2_00,
    CDCDeviceDescriptor_CLASS,
    CDCDeviceDescriptor_SUBCLASS,
    CDCDeviceDescriptor_PROTOCOL,
    BOARD_USB_ENDPOINTS_MAXPACKETSIZE(0),
    CDCDSerialDriverDescriptors_VENDORID,
    CDCDSerialDriverDescriptors_PRODUCTID,
    CDCDSerialDriverDescriptors_RELEASE,
    0, // No string descriptor for manufacturer
    1, // Index of product string descriptor is #1
    0, // No string descriptor for serial number
    1 // Device has 1 possible configuration
};
 \endcode
 The Vendor ID and Product ID fields are used to determine which driver to use
 when the %device is enumerated. The Vendor ID is provided by the USB-IF
 organization after registration; the product ID is completely vendor-specific.
 In the example implementation provided with this document, the Atmel vendor ID
 (03EBh) is used along with a custom product ID (6119h).

 The configuration descriptor is followed by interface, endpoint and class-
 specific descriptors.
\code
const CDCDSerialDriverConfigurationDescriptors configurationDescriptors[];
\endcode

 !Configuration Descriptor
\code
    {
        sizeof(USBConfigurationDescriptor),
        USBGenericDescriptor_CONFIGURATION,
        sizeof(CDCDSerialDriverConfigurationDescriptors),
        2, // There are two interfaces in this configuration
        1, // This is configuration #1
        0, // No string descriptor for this configuration
        BOARD_USB_BMATTRIBUTES,
        USBConfigurationDescriptor_POWER(100)
    },
\endcode

 !Communication Class Interface Descriptor
 The bInterfaceClass should be set to 0x02 and bInterfaceSubClass should be set
 to 0x02.
\code
    {
        sizeof(USBInterfaceDescriptor),
        USBGenericDescriptor_INTERFACE,
        0, // This is interface #0
        0, // This is alternate setting #0 for this interface
        1, // This interface uses 1 endpoint
        CDCCommunicationInterfaceDescriptor_CLASS,
        CDCCommunicationInterfaceDescriptor_ABSTRACTCONTROLMODEL,
        CDCCommunicationInterfaceDescriptor_NOPROTOCOL,
        0  // No string descriptor for this interface
    },
\endcode

 !Functional - Header Descriptor
\code
    {
        sizeof(CDCHeaderDescriptor),
        CDCGenericDescriptor_INTERFACE,
        CDCGenericDescriptor_HEADER,
        CDCGenericDescriptor_CDC1_10
    },
\endcode

 !Functional - Call Management Descriptor
\code
    {
        sizeof(CDCCallManagementDescriptor),
        CDCGenericDescriptor_INTERFACE,
        CDCGenericDescriptor_CALLMANAGEMENT,
        CDCCallManagementDescriptor_SELFCALLMANAGEMENT,
        0 // No associated data interface
    },
\endcode

 !Functional - Abstract Control Management Descriptor
\code
    {
        sizeof(CDCAbstractControlManagementDescriptor),
        CDCGenericDescriptor_INTERFACE,
        CDCGenericDescriptor_ABSTRACTCONTROLMANAGEMENT,
        CDCAbstractControlManagementDescriptor_LINE
    },
\endcode

 !Functional - Union Descriptor
\code
    {
        sizeof(CDCUnionDescriptor),
        CDCGenericDescriptor_INTERFACE,
        CDCGenericDescriptor_UNION,
        0, // Number of master interface is #0
        1 // First slave interface is #1
    },
\endcode

 !Notification Endpoint Descriptor
 The EP is defined as CDCDSerialDriverDescriptors_NOTIFICATION.
\code
    {
        sizeof(USBEndpointDescriptor), 
        USBGenericDescriptor_ENDPOINT,
        USBEndpointDescriptor_ADDRESS(USBEndpointDescriptor_IN,
                     CDCDSerialDriverDescriptors_NOTIFICATION),
        USBEndpointDescriptor_INTERRUPT,
        MIN(BOARD_USB_ENDPOINTS_MAXPACKETSIZE(
                     CDCDSerialDriverDescriptors_NOTIFICATION),
            USBEndpointDescriptor_MAXINTERRUPTSIZE_FS),
        10 // Endpoint is polled every 10ms
    },
\endcode

 !Data Class Interface Descriptor
\code
    {
        sizeof(USBInterfaceDescriptor),
        USBGenericDescriptor_INTERFACE,
        1, // This is interface #1
        0, // This is alternate setting #0 for this interface
        2, // This interface uses 2 endpoints
        CDCDataInterfaceDescriptor_CLASS,
        CDCDataInterfaceDescriptor_SUBCLASS,
        CDCDataInterfaceDescriptor_NOPROTOCOL,
        0  // No string descriptor for this interface
    },
\endcode

 !Data Endpoint Descriptors
 The EPs are defined as CDCDSerialDriverDescriptors_DATAOUT &
 CDCDSerialDriverDescriptors_DATAIN.
\code