usb.h

AT91SAM9261的USB设备驱动程序

#define USB_CLASS_DIAGNOSTIC_DEVICE     0xDC

//! \brief Wireless controller devices
#define USB_CLASS_WIRELESS_CONTROLLER   0xE0

//! \brief Miscellaneous devices
#define USB_CLASS_MISCELLANEOUS         0xEF

//! \brief Application-specific class code
#define USB_CLASS_APPLICATION_SPECIFIC  0xFE

//! \brief Vendor-specific class code
#define USB_CLASS_VENDOR_SPECIFIC       0xFF
//! @}

//! \ingroup usb_std_struc
//! \defgroup dev_desc_const Device Descriptor - Constants
//! Several useful constants when declaring a device descriptor
//! \see S_usb_device_descriptor
//! \see S_usb_device_qualifier_descriptor
//! \see usb_20.pdf - Section 9.6.1 - Table 9.8
//! @{

//! \name USB specification release codes
//! @{

//! bcdUSB field - USB 2.0 specification code
#define USB2_00                     0x0200
#define USB1_10                     0x0110
//! @}

//! \name Vendor IDs
//! @{

//! idVendor - ATMEL Vendor ID
#define USB_VENDOR_ATMEL            0x03EB
//! @}
//! @}

//! \ingroup usb_std_struc
//! \defgroup cfg_desc_const Configuration Descriptor - Constants
//! Several useful constants when declaring a configuration descriptor
//! \see S_usb_configuration_descriptor
//! \see usb_20.pdf - Section 9.6.3 - Table 9.10
//! @{

//! \name bmAttributes field
//! \brief These are the possible values for the bmAttributes field of a
//!        S_usb_configuration_descriptor.
//! @{

//! \brief Device is bus-powered and does not support remote wakeup
#define USB_CONFIG_BUS_NOWAKEUP    0x80

//! \brief Device is self-powered and does not support remote wakeup
#define USB_CONFIG_SELF_NOWAKEUP   0xC0

//! \brief Device is bus-powered and supports remote wakeup
#define USB_CONFIG_BUS_WAKEUP      0xA0

//! \brief Device is self-powered and supports remote wakeup
#define USB_CONFIG_SELF_WAKEUP     0xE0
//! @}

//! \name Power consumption
//! @{

//! Power consumption macro for the Configuration descriptor
#define USB_POWER_MA(power)        (power/2)
//! @}
//! @}

//! \ingroup usb_std_struc
//! \defgroup str_desc_const String Descriptor - Constants
//! \brief Useful constants when declaring a string descriptor.
//! \see S_usb_string_descriptor
//! \see USB_LANGIDs.pdf
//! @{

//! \name Language IDs
//! \brief These are the supported language IDs as defined by the USB-IF group.
//!        They can be used to specified the languages supported by the string
//!        descriptors of a USB device.
//! @{

//! \brief English (United States)
#define USB_LANGUAGE_ENGLISH_US     0x0409
//! @}
//! @}

//! \ingroup usb_std_struc
//! \defgroup str_desc_macros String Descriptor - Macros
//! \brief Several useful macros when declaring a string descriptor.
//! \see S_usb_string_descriptor
//! @{

//! Converts an ASCII character to its Unicode equivalent
#define USB_UNICODE(a)                      (a), 0x00

//! Calculates the size of a string descriptor given the number of ASCII
//! characters in it
#define USB_STRING_DESCRIPTOR_SIZE(size)    ((size * 2) + 2)
//! @}

//! \ingroup usb_api_methods
//! \defgroup usb_api_ret_val Standard return values
//! \brief Values returned by the API methods.
//! @{

//! \brief Last method has completed successfully
#define USB_STATUS_SUCCESS      0

//! \brief Method was aborted because the recipient (device, endpoint, ...) was
//!        busy
#define USB_STATUS_LOCKED       1

//! \brief Method was aborted because of abnormal status
#define USB_STATUS_ABORTED      2

//! \brief Method was aborted because the endpoint or the device has been reset
#define USB_STATUS_RESET        3
//! @}

// Device State
//! \ingroup S_usb_struc
//! \defgroup S_usb_dev_state USB Device States
//! \brief Constant values used to track which USB state the device is currently
//!        in.
//! @{

//! Attached state
#define USB_STATE_ATTACHED                          (1 << 0)

//! Powered state
#define USB_STATE_POWERED                           (1 << 1)

//! Default state
#define USB_STATE_DEFAULT                           (1 << 2)

//! Address state
#define USB_STATE_ADDRESS                           (1 << 3)

//! Configured state
#define USB_STATE_CONFIGURED                        (1 << 4)

//! Suspended state
#define USB_STATE_SUSPENDED                         (1 << 5)

//! @}

//------------------------------------------------------------------------------
//      Structures
//------------------------------------------------------------------------------

// USB standard structures
//-------------------------
//! \ingroup usb_std_struc
//! \brief This structure represents a standard SETUP request
//! \see usb_20.pdf - Section 9.3 - Table 9.2
typedef struct {


    unsigned char   bmRequestType:8;    //!< Characteristics of the request
    unsigned char   bRequest:8;         //!< Particular request
    unsigned short  wValue:16;          //!< Request-specific parameter
    unsigned short  wIndex:16;          //!< Request-specific parameter
    unsigned short  wLength:16;         //!< Length of data for the data phase

} S_usb_request;

//! \ingroup usb_std_struc
//! \brief This descriptor structure is used to provide information on
//!        various parameters of the device
//!
//! Usage example:
//! \include S_usb_device_descriptor_example.c
//! \see usb_20.pdf - Section 9.6.1
__packed typedef struct {

   unsigned char  bLength;              //!< Size of this descriptor in bytes
   unsigned char  bDescriptorType;      //!< DEVICE descriptor type
   unsigned short bscUSB;               //!< USB specification release number
   unsigned char  bDeviceClass;         //!< Class code
   unsigned char  bDeviceSubClass;      //!< Subclass code
   unsigned char  bDeviceProtocol;      //!< Protocol code
   unsigned char  bMaxPacketSize0;      //!< Control endpoint 0 max. packet size
   unsigned short idVendor;             //!< Vendor ID
   unsigned short idProduct;            //!< Product ID
   unsigned short bcdDevice;            //!< Device release number
   unsigned char  iManufacturer;        //!< Index of manu. string descriptor
   unsigned char  iProduct;             //!< Index of prod. string descriptor
   unsigned char  iSerialNumber;        //!< Index of S.N.  string descriptor
   unsigned char  bNumConfigurations;   //!< Number of possible configurations

}  S_usb_device_descriptor;

//! \ingroup usb_std_struc
//! \brief This is the standard configuration descriptor structure. It is used
//!        to report the current configuration of the device.
//!
//! Usage example:
//! \include S_usb_configuration_descriptor_example.c
//! \see usb_20.pdf - Section 9.6.3
__packed typedef struct {

   unsigned char  bLength;              //!< Size of this descriptor in bytes
   unsigned char  bDescriptorType;      //!< CONFIGURATION descriptor type
   unsigned short wTotalLength;         //!< Total length of data returned
                                        //!< for this configuration
   unsigned char  bNumInterfaces;       //!< Number of interfaces for this
                                        //!< configuration
   unsigned char  bConfigurationValue;  //!< Value to use as an argument for
                                        //!< the Set Configuration request to
                                        //!< select this configuration
   unsigned char  iConfiguration;       //!< Index of string descriptor
                                        //!< describing this configuration
   unsigned char  bmAttibutes;          //!< Configuration characteristics
   unsigned char  bMaxPower;            //!< Maximum power consumption of the
                                        //!< device
} S_usb_configuration_descriptor;

//! \ingroup usb_std_struc
//! \brief Standard interface descriptor. Used to describe a specific interface
//!        of a configuration.
//!
//! Usage example:
//! \include S_usb_interface_descriptor_example.c
//! \see usb_20.pdf - Section 9.6.5
__packed typedef struct {

   unsigned char bLength;               //!< Size of this descriptor in bytes
   unsigned char bDescriptorType;       //!< INTERFACE descriptor type
   unsigned char bInterfaceNumber;      //!< Number of this interface
   unsigned char bAlternateSetting;     //!< Value used to select this alternate
                                        //!< setting
   unsigned char bNumEndpoints;         //!< Number of endpoints used by this
                                        //!< interface (excluding endpoint zero)
   unsigned char bInterfaceClass;       //!< Class code
   unsigned char bInterfaceSubClass;    //!< Sub-class
   unsigned char bInterfaceProtocol;    //!< Protocol code
   unsigned char iInterface;            //!< Index of string descriptor
                                        //!< describing this interface
} S_usb_interface_descriptor;

//! \ingroup usb_std_struc
//! \brief This structure is the standard endpoint descriptor. It contains
//!        the necessary information for the host to determine the bandwidth
//!        required by the endpoint.
//!
//! Usage example:
//! \include S_usb_endpoint_descriptor_example.c
//! \see usb_20.pdf - Section 9.6.6
__packed typedef struct {

   unsigned char  bLength;              //!< Size of this descriptor in bytes
   unsigned char  bDescriptorType;      //!< ENDPOINT descriptor type
   unsigned char  bEndpointAddress;     //!< Address of the endpoint on the USB
                                        //!< device described by this descriptor
   unsigned char  bmAttributes;         //!< Endpoint attributes when configured
   unsigned short wMaxPacketSize;       //!< Maximum packet size this endpoint
                                        //!< is capable of sending or receiving
   unsigned char  bInterval;            //!< Interval for polling endpoint for
                                        //!< data transfers
} S_usb_endpoint_descriptor;

//! \ingroup usb_std_struc
//! \brief The device qualifier structure provide information on a high-speed
//!        capable device if the device was operating at the other speed.
//!
//! Usage example:
//! \include S_usb_device_qualifier_descriptor_example.c
//! \see usb_20.pdf - Section 9.6.2
__packed typedef struct {

   unsigned char  bLength;              //!< Size of this descriptor in bytes
   unsigned char  bDescriptorType;      //!< DEVICE_QUALIFIER descriptor type
   unsigned short bscUSB;               //!< USB specification release number
   unsigned char  bDeviceClass;         //!< Class code
   unsigned char  bDeviceSubClass;      //!< Sub-class code
   unsigned char  bDeviceProtocol;      //!< Protocol code
   unsigned char  bMaxPacketSize0;      //!< Control endpoint 0 max. packet size
   unsigned char  bNumConfigurations;   //!< Number of possible configurations
   unsigned char  bReserved;            //!< Reserved for future use, must be 0

} S_usb_device_qualifier_descriptor;

//! \ingroup usb_std_struc
//! \brief The S_usb_language_id structure represents the string descriptor
//!        zero, used to specify the languages supported by the device. This
//!        structure only define one language ID.
//!
//! Usage example:
//! \include S_usb_language_id_example.c
//! \see usb_20.pdf - Section 9.6.7 - Table 9.15
__packed typedef struct {

   unsigned char  bLength;               //!< Size of this descriptor in bytes
   unsigned char  bDescriptorType;       //!< STRING descriptor type
   unsigned short wLANGID;               //!< LANGID code zero

} S_usb_language_id;

// USB Framework
//---------------

typedef struct _S_usb S_usb;

//! \ingroup usb_api_callbacks
//! \brief Initialization callback function
//!
//! This callback is invoked whenever the USB API is initialized using the
//! USB_Init function. It should perform the following operations:
//! \li If an OS is being used, install the USB driver
//! \li Configure the USB controller interrupt
//! \li Configure the VBus monitoring interrupt
//! \attention Implementation of this callback is \b mandatory
//! \see USB_Init
//! \see S_usb
typedef void (*S_usb_init)(const S_usb *);

//! \ingroup usb_api_callbacks
//! \brief Reset callback function
//!
//! Invoked whenever the device is reset by the host. This function should
//! perform initialization or re-initialization of the user application.
//! \attention Implementation of this callback is \b optional
//! \see USB_Handler
//! \see S_usb
typedef void (*S_usb_reset)(const S_usb *);

//! \ingroup usb_api_callbacks
//! \brief Suspend callback function
//!
//! Invoked when the device is suspended by the host or detached from the bus.
//! If the device must enter low-power mode when suspended, then the necessary
//! code must be implemented here.
//! \see USB_Attach
//! \see USB_Handler
//! \see S_usb
typedef void (*S_usb_suspend)(const S_usb *);