usb.h

AT91系列芯片的USB虚拟串口的源代码

/* ----------------------------------------------------------------------------
 *         ATMEL Microcontroller Software Support  -  ROUSSET  -
 * ----------------------------------------------------------------------------
 * Copyright (c) 2006, 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 disclaiimer below.
 *
 * - Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the disclaimer below in the documentation and/or
 * other materials provided with the distribution.
 *
 * 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.
 * ----------------------------------------------------------------------------
 */

/*
$Id: usb.h 121 2006-10-17 12:54:54Z jjoannic $
*/

#ifndef _USB_H
#define _USB_H

//------------------------------------------------------------------------------
//! \defgroup usb_std_struc USB standard structures
//! \brief Chapter 9 of the USB specification 2.0 (usb_20.pdf) describes a
//!        standard USB device framework. Several structures and associated
//!        constants have been defined on that model and are described here.
//! \see usb_20.pdf - Section 9
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
//! \defgroup usb_api_struct USB API Structures
//! \brief The USB API uses various custom structures to track the state of
//!        the USB controller, endpoints, and the like. These structures are
//!        described here.
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
//! \defgroup usb_api_methods USB API Methods
//! \brief  Methods provided by the USB API to manipulate a USB driver.
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
//! \defgroup usb_api_callbacks Callback API
//! \brief These callback functions are used by the USB API to notify the
//!        user application of incoming events or actions to perform.
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
//! \defgroup usb_std_req_hlr Standard Request Handler
//! \brief This module provides a way to easily handle standard standard
//!        requests.
//------------------------------------------------------------------------------

//------------------------------------------------------------------------------
//      Definitions
//------------------------------------------------------------------------------

// USB standard definitions
//---------------------------------------------------------
//! \ingroup usb_std_req_hlr
//! \defgroup std_dev_req Standard Device Requests
//! These are the standard request defined for a SETUP transaction. Please refer
//! to Section 9.4 of the USB 2.0 specification (usb_20.pdf) for more
//! information. Table 9.4 defines the bRequest values for each request.
//! \see S_usb_request
//! \see usb_20.pdf - Section 9.4
//! @{

//! \brief  Returns the status for the specified recipient.
//! \see    get_status_const
//! \see    usb_20.pdf - Section 9.4.5
#define USB_GET_STATUS                 0x00

//! \brief  Disables a specific feature of the device
//! \see    usb_20.pdf - Section 9.4.1
//! \see    clr_set_feat_const
#define USB_CLEAR_FEATURE              0x01

// Reserved for futur use              0x02

//! \brief  Enables a specific feature of the device
//! \see    clr_set_feat_const
//! \see    set_feat_const
//! \see    usb_20.pdf - 9.4.9
#define USB_SET_FEATURE                0x03

// Reserved for futur use              0x04

//! \brief  Sets the device address for subsequent accesses
//! \see    usb_20.pdf - Section 9.4.6
#define USB_SET_ADDRESS                0x05

//! \brief  Returns the specified descriptor if it exists
//! \see    usb_20.pdf - Section 9.4.3
#define USB_GET_DESCRIPTOR             0x06

//! \brief  Updates existing descriptors or creates new descriptors
//! \brief  This request is optional
//! \see    usb_20.pdf - Section 9.4.8
#define USB_SET_DESCRIPTOR             0x07

//! \brief  Returns the current configuration value of the device
//! \see    usb_20.pdf - Section 9.4.2
#define USB_GET_CONFIGURATION          0x08

//! \brief  Sets the configuration of the device
//! \see    usb_20.pdf - Section 9.4.7
#define USB_SET_CONFIGURATION          0x09

//! \brief  Returns the specified alternate setting for an interface
//! \see    usb_20.pdf - Section 9.4.4
#define USB_GET_INTERFACE              0x0A

//! \brief  Selects an alternate setting for the selected interface
//! \see    usb_20.pdf - Section 9.4.10
#define USB_SET_INTERFACE              0x0B

//! \brief  Sets and reports an endpoint synchronization frame
//! \see    usb_20.pdf - Section 9.4.11
#define USB_SYNCH_FRAME                0x0C
//! @}

//! \ingroup std_dev_req
//! \defgroup clr_set_feat_const Clear/Set Feature - Constants
//! \brief Useful constants when declaring a Clear Feature or Set Feature
//! standard request.
//! \see std_dev_req
//! \see S_usb_request
//! \see usb_20.pdf - Section 9.4 - Table 9.6
//! @{

//! \name Standard Feature Selectors
//! Possible values for the wValue field of the Clear Feature and Set Feature
//! standard requests.
//! @{

//! \brief Halt feature of an endpoint
#define USB_ENDPOINT_HALT              0x00

//! \brief Remote wake-up feature of the device
#define USB_DEVICE_REMOTE_WAKEUP       0x01

//! \brief USB test mode
#define USB_TEST_MODE                  0x02
//! @}
//! @}

//! \ingroup std_dev_req
//! \defgroup set_feat_const Set Feature - Constants
//! \brief Useful constants when declaring a Set Feature standard request
//! \see usb_20.pdf - Section 7.1.20
//! \see usb_20.pdf - Section 9.2.9 - Table 9.7
//! @{

//! \name Test Mode Selectors
//! \brief Test modes available to probe an USB device.
//! @{

//! \brief Tests the high-output drive level on the D+ line
#define TEST_J                         0x01

//! \brief Tests the high-output drive level on the D- line
#define TEST_K                         0x02

//! \brief Tests the output impedance, low-level output voltage and loading
//!        characteristics
#define TEST_SEO_NAK                   0x03

//! \brief Tests rise and fall times, eye patterns and jitter
#define TEST_PACKET                    0x04

//! \brief Tests the hub disconnect detection
#define TEST_FORCE_ENABLE              0x05
//! @}
//! @}

//! \ingroup std_dev_req
//! \defgroup get_set_desc_const Get/Set Descriptor - Constants
//! \brief Useful constants when declaring a Get Descriptor or Set Descriptor
//!        standard request
//! \see StdReq
//! \see S_usb_device_descriptor
//! \see S_usb_configuration_descriptor
//! \see S_usb_endpoint_descriptor
//! \see S_usb_device_qualifier_descriptor
//! \see S_USB_LANGUAGE_ENGLISH_US
//! \see usb_20.pdf - Section 9.5 - Table 9.5
//! @{

//! \name Descriptor Types
//! \brief Possible bDescriptorType values for the descriptor structures.
//!
//! They can be used with Get Descriptor and Set Descriptor standard requests
//! to retrieve/modify them
//! @{

//! \brief Device descriptor
#define USB_DEVICE_DESCRIPTOR                       0x01

//! \brief Configuration descriptor
#define USB_CONFIGURATION_DESCRIPTOR                0x02

//! \brief String descriptor
#define USB_STRING_DESCRIPTOR                       0x03

//! \brief Interface descriptor
#define USB_INTERFACE_DESCRIPTOR                    0x04

//! \brief Endpoint descriptor
#define USB_ENDPOINT_DESCRIPTOR                     0x05

//! \brief Device qualifier descriptor
#define USB_DEVICE_QUALIFIER_DESCRIPTOR             0x06

//! \brief Other speed configuration descriptor
#define USB_OTHER_SPEED_CONFIGURATION_DESCRIPTOR    0x07

//! \brief Interface power descriptor
#define USB_INTERFACE_POWER_DESCRIPTOR              0x08
//! @}
//! @}

//! \ingroup usb_std_struc
//! \defgroup ept_desc_const Endpoint Descriptor - Constants
//! \brief Useful constants when declaring an endpoint descriptor
//! \see S_usb_endpoint_descriptor
//! \see usb_20.pdf - Section 9.6.6 - Table 9.13
//! @{

//! \name  bEndpointAddress field
//! \brief Values for the bEndpointAddress field of an endpoint descriptor.
//! @{

//! \brief Defines an OUT endpoint
#define USB_ENDPOINT_OUT                            (0 << 7)

//! \brief Defines an IN endpoint
#define USB_ENDPOINT_IN                             (1 << 7)
//! @}

//! \name  bmAttributes field
//! \brief These are the four possible tranfer type values for the bmAttributes
//!        field of an endpoint descriptor.
//! @{

//! \brief Defines a CONTROL endpoint
#define ENDPOINT_TYPE_CONTROL          0x00

//! \brief Defines a ISOCHRONOUS endpoint
#define ENDPOINT_TYPE_ISOCHRONOUS      0x01

//! \brief Defines a BULK endpoint
#define ENDPOINT_TYPE_BULK             0x02

//! \brief Defines an INTERRUPT endpoint
#define ENDPOINT_TYPE_INTERRUPT        0x03
//! @}
//! @}

//! \name  bmRequestType field
//! \brief This bitmapped field identifies the characteristics of the specific
//!        request.
//! \see   usb_209.pdf - Table 9-2. Format of Setup Data
//! @{

//! \brief D6...5: Type
//! \brief Defines a standard request
#define USB_STANDARD_REQUEST                0x00

//! \brief Defines a class request
#define USB_CLASS_REQUEST                   0x01

//! \brief Defines a vendor request
#define USB_VENDOR_REQUEST                  0x02

//! \brief Get the type of bmRequestType
#define USB_REQUEST_TYPE(pSetup)            ((pSetup->bmRequestType & 0x60) >> 5)

//! \brief Get the receipient of bmRequestType
#define USB_REQUEST_RECIPIENT(pSetup)       (pSetup->bmRequestType & 0x1F)

//! \brief Recipient is the whole device
#define USB_RECIPIENT_DEVICE                0x00

//! \brief Recipient is an interface
#define USB_RECIPIENT_INTERFACE             0x01

//! \brief Recipient is an endpoint
#define USB_RECIPIENT_ENDPOINT              0x02

//! @}

//! \ingroup usb_std_struc
//! \defgroup ept_desc_macros Endpoint Descriptor - Macros
//! \brief Useful macros when declaring an endpoint descriptor
//! \see S_usb_endpoint_descriptor
//! \see usb_20.pdf - Section 9.6.6 - Table 9.13
//! @{

//! \name bEndpointAddress field
//! @{

//! \brief Returns an endpoint number
#define USB_ENDPOINT_NUMBER(bEndpointAddress)       (bEndpointAddress & 0x0F)

//! \brief Returns an endpoint direction (IN or OUT)
#define USB_ENDPOINT_DIRECTION(bEndpointAddress)    (bEndpointAddress & 0x80)
//! @}
//! @}

//! \ingroup usb_std_req_hlr
//! \defgroup usb_class_codes USB Class Codes
//! These are the class codes approved by the USB-IF organization. They can be
//! used for the bDeviceClass value of a device descriptor, or the
//! bInterfaceClass value of an interface descriptor.
//! \see S_usb_device_descriptor
//! \see S_usb_interface_descriptor
//! \see http://www.usb.org/developers/defined_class
//! @{

//! \brief Indicates that the class information is determined by the interface
//!        descriptor.
#define USB_CLASS_DEVICE                0x00

//! \brief Audio capable devices
#define USB_CLASS_AUDIO                 0x01

//! \brief Communication devices
#define USB_CLASS_COMMUNICATION         0x02

//! \brief Human-interface devices
#define USB_CLASS_HID                   0x03

//! \brief Human-interface devices requiring real-time physical feedback