SAMV71 Xplained Ultra Software Package 1.0

USBD_Protocol.h

Go to the documentation of this file.
00001 /**
00002  * \file
00003  *
00004  * \brief USB protocol definitions.
00005  *
00006  * This file contains the USB definitions and data structures provided by the
00007  * USB 2.0 specification.
00008  *
00009  * Copyright (C) 2009 Atmel Corporation. All rights reserved.
00010  *
00011  * \page License
00012  *
00013  * Redistribution and use in source and binary forms, with or without
00014  * modification, are permitted provided that the following conditions are met:
00015  *
00016  * 1. Redistributions of source code must retain the above copyright notice,
00017  * this list of conditions and the following disclaimer.
00018  *
00019  * 2. Redistributions in binary form must reproduce the above copyright notice,
00020  * this list of conditions and the following disclaimer in the documentation
00021  * and/or other materials provided with the distribution.
00022  *
00023  * 3. The name of Atmel may not be used to endorse or promote products derived
00024  * from this software without specific prior written permission.
00025  *
00026  * 4. This software may only be redistributed and used in connection with an
00027  * Atmel AVR product.
00028  *
00029  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
00030  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00031  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00032  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
00033  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00034  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00035  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00036  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00037  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00038  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
00039  * DAMAGE.
00040  */
00041 
00042 #ifndef _USB_PROTOCOL_H_
00043 #define _USB_PROTOCOL_H_
00044 
00045 
00046 /**
00047  * \ingroup usb_group
00048  * \defgroup usb_protocol_group USB Protocol Definitions
00049  *
00050  * This module defines constants and data structures provided by the USB
00051  * 2.0 specification.
00052  *
00053  * @{
00054  */
00055 
00056 //! Value for field bcdUSB
00057 #define  USB_V2_0    0x0200 //!< USB Specification version 2.00
00058 
00059 /*! \name Generic definitions (Class, subclass and protocol)
00060  */
00061 //! @{
00062 #define  NO_CLASS                0x00
00063 #define  NO_SUBCLASS             0x00
00064 #define  NO_PROTOCOL             0x00
00065 //! @}
00066 
00067 //! \name IAD (Interface Association Descriptor) constants
00068 //! @{
00069 #define  CLASS_IAD               0xEF
00070 #define  SUB_CLASS_IAD           0x02
00071 #define  PROTOCOL_IAD            0x01
00072 //! @}
00073 
00074 //! \name Apple VID & PID for host application
00075 //! @{
00076 #define  USB_VID_APPLE           0x05AC
00077 #define  USB_PID_IPOD            0x1200
00078 #define  USB_PID_IPOD_SHUFFLE    0x1300
00079 //! @}
00080 
00081 /**
00082  * \brief USB request data transfer direction (bmRequestType)
00083  */
00084 #define  USB_REQ_DIR_OUT         (0<<7) //!< Host to device
00085 #define  USB_REQ_DIR_IN          (1<<7) //!< Device to host
00086 #define  USB_REQ_DIR_MASK        (1<<7) //!< Mask
00087 
00088 /**
00089  * \brief USB request types (bmRequestType)
00090  */
00091 #define  USB_REQ_TYPE_STANDARD   (0<<5) //!< Standard request
00092 #define  USB_REQ_TYPE_CLASS      (1<<5) //!< Class-specific request
00093 #define  USB_REQ_TYPE_VENDOR     (2<<5) //!< Vendor-specific request
00094 #define  USB_REQ_TYPE_MASK       (3<<5) //!< Mask
00095 
00096 /**
00097  * \brief USB recipient codes (bmRequestType)
00098  */
00099 #define  USB_REQ_RECIP_DEVICE    (0<<0) //!< Recipient device
00100 #define  USB_REQ_RECIP_INTERFACE (1<<0) //!< Recipient interface
00101 #define  USB_REQ_RECIP_ENDPOINT  (2<<0) //!< Recipient endpoint
00102 #define  USB_REQ_RECIP_OTHER     (3<<0) //!< Recipient other
00103 #define  USB_REQ_RECIP_MASK      (0x1F) //!< Mask
00104 
00105 /**
00106  * \brief Standard USB requests (bRequest)
00107  */
00108 enum usb_reqid {
00109     USB_REQ_GET_STATUS = 0,
00110     USB_REQ_CLEAR_FEATURE = 1,
00111     USB_REQ_SET_FEATURE = 3,
00112     USB_REQ_SET_ADDRESS = 5,
00113     USB_REQ_GET_DESCRIPTOR = 6,
00114     USB_REQ_SET_DESCRIPTOR = 7,
00115     USB_REQ_GET_CONFIGURATION = 8,
00116     USB_REQ_SET_CONFIGURATION = 9,
00117     USB_REQ_GET_INTERFACE = 10,
00118     USB_REQ_SET_INTERFACE = 11,
00119     USB_REQ_SYNCH_FRAME = 12
00120 };
00121 
00122 /**
00123  * \brief Standard USB device status flags
00124  *
00125  */
00126 enum usb_device_status {
00127     USB_DEV_STATUS_BUS_POWERED = 0,
00128     USB_DEV_STATUS_SELF_POWERED = 1,
00129     USB_DEV_STATUS_REMOTEWAKEUP = 2
00130 };
00131 
00132 /**
00133  * \brief Standard USB Interface status flags
00134  *
00135  */
00136 enum usb_interface_status {
00137     USB_IFACE_STATUS_RESERVED = 0
00138 };
00139 
00140 /**
00141  * \brief Standard USB endpoint status flags
00142  *
00143  */
00144 enum usb_endpoint_status {
00145     USB_EP_STATUS_HALTED = 1
00146 };
00147 
00148 /**
00149  * \brief Standard USB device feature flags
00150  *
00151  * \note valid for SetFeature request.
00152  */
00153 enum usb_device_feature {
00154     USB_DEV_FEATURE_REMOTE_WAKEUP = 1,  //!< Remote wakeup enabled
00155     USB_DEV_FEATURE_TEST_MODE = 2,  //!< USB test mode
00156     USB_DEV_FEATURE_OTG_B_HNP_ENABLE = 3,
00157     USB_DEV_FEATURE_OTG_A_HNP_SUPPORT = 4,
00158     USB_DEV_FEATURE_OTG_A_ALT_HNP_SUPPORT = 5
00159 };
00160 
00161 /**
00162  * \brief Test Mode possible on HS USB device 
00163  *
00164  * \note valid for USB_DEV_FEATURE_TEST_MODE request.
00165  */
00166 enum usb_device_hs_test_mode {
00167     USB_DEV_TEST_MODE_J = 1,
00168     USB_DEV_TEST_MODE_K = 2,
00169     USB_DEV_TEST_MODE_SE0_NAK = 3,
00170     USB_DEV_TEST_MODE_PACKET = 4,
00171     USB_DEV_TEST_MODE_FORCE_ENABLE = 5
00172 };
00173 
00174 /**
00175  * \brief Standard USB endpoint feature/status flags
00176  */
00177 enum usb_endpoint_feature {
00178     USB_EP_FEATURE_HALT = 0
00179 };
00180 
00181 /**
00182  * \brief Standard USB Test Mode Selectors
00183  */
00184 enum usb_test_mode_selector {
00185     USB_TEST_J = 0x01,
00186     USB_TEST_K = 0x02,
00187     USB_TEST_SE0_NAK = 0x03,
00188     USB_TEST_PACKET = 0x04,
00189     USB_TEST_FORCE_ENABLE = 0x05
00190 };
00191 
00192 /**
00193  * \brief Standard USB descriptor types
00194  */
00195 enum usb_descriptor_type {
00196     USB_DT_DEVICE = 1,
00197     USB_DT_CONFIGURATION = 2,
00198     USB_DT_STRING = 3,
00199     USB_DT_INTERFACE = 4,
00200     USB_DT_ENDPOINT = 5,
00201     USB_DT_DEVICE_QUALIFIER = 6,
00202     USB_DT_OTHER_SPEED_CONFIGURATION = 7,
00203     USB_DT_INTERFACE_POWER = 8,
00204     USB_DT_OTG = 9,
00205     USB_DT_IAD = 0x0B
00206 };
00207 
00208 /**
00209  * \brief Standard USB endpoint transfer types
00210  */
00211 enum usb_ep_type {
00212     USB_EP_TYPE_CONTROL = 0x00,
00213     USB_EP_TYPE_ISOCHRONOUS = 0x01,
00214     USB_EP_TYPE_BULK = 0x02,
00215     USB_EP_TYPE_INTERRUPT = 0x03,
00216     USB_EP_TYPE_MASK = 0x03
00217 };
00218 
00219 /**
00220  * \brief Standard USB language IDs for string descriptors
00221  */
00222 enum usb_langid {
00223     USB_LANGID_EN_US = 0x0409   //!< English (United States)
00224 };
00225 
00226 /**
00227  * \brief Mask selecting the index part of an endpoint address
00228  */
00229 #define  USB_EP_ADDR_MASK     0x0f
00230 /**
00231  * \brief Endpoint transfer direction is IN
00232  */
00233 #define  USB_EP_DIR_IN        0x80
00234 /**
00235  * \brief Endpoint transfer direction is OUT
00236  */
00237 #define  USB_EP_DIR_OUT       0x00
00238 
00239 /**
00240  * \brief Maximum length in bytes of a USB descriptor
00241  *
00242  * The maximum length of a USB descriptor is limited by the 8-bit
00243  * bLength field.
00244  */
00245 #define  USB_MAX_DESC_LEN     255
00246 
00247 /*
00248  * 2-byte alignment requested for all USB structures.
00249  */
00250 //COMPILER_PACK_SET(1)
00251 
00252 /**
00253  * \brief A USB Device SETUP request
00254  *
00255  * The data payload of SETUP packets always follows this structure.
00256  */
00257 typedef struct {
00258     uint8_t bmRequestType;
00259     uint8_t bRequest;
00260     le16_t wValue;
00261     le16_t wIndex;
00262     le16_t wLength;
00263 } usb_setup_req_t;
00264 
00265 /**
00266  * \brief Standard USB device descriptor stucture
00267  */
00268 typedef struct {
00269     uint8_t bLength;
00270     uint8_t bDescriptorType;
00271     le16_t bcdUSB;
00272     uint8_t bDeviceClass;
00273     uint8_t bDeviceSubClass;
00274     uint8_t bDeviceProtocol;
00275     uint8_t bMaxPacketSize0;
00276     le16_t idVendor;
00277     le16_t idProduct;
00278     le16_t bcdDevice;
00279     uint8_t iManufacturer;
00280     uint8_t iProduct;
00281     uint8_t iSerialNumber;
00282     uint8_t bNumConfigurations;
00283 } usb_dev_desc_t;
00284 
00285 /**
00286  * \brief Standard USB device qualifier descriptor structure
00287  *
00288  * This descriptor contains information about the device when running at
00289  * the "other" speed (i.e. if the device is currently operating at high
00290  * speed, this descriptor can be used to determine what would change if
00291  * the device was operating at full speed.)
00292  */
00293 typedef struct {
00294     uint8_t bLength;
00295     uint8_t bDescriptorType;
00296     le16_t bcdUSB;
00297     uint8_t bDeviceClass;
00298     uint8_t bDeviceSubClass;
00299     uint8_t bDeviceProtocol;
00300     uint8_t bMaxPacketSize0;
00301     uint8_t bNumConfigurations;
00302     uint8_t bReserved;
00303 } usb_dev_qual_desc_t;
00304 
00305 
00306 /**
00307  * \brief Standard USB Interface Association Descriptor structure
00308  */
00309 typedef struct {
00310     uint8_t bLength;    //!< size of this descriptor in bytes
00311     uint8_t bDescriptorType;    //!< INTERFACE descriptor type
00312     uint8_t bFirstInterface;    //!< Number of interface
00313     uint8_t bInterfaceCount;    //!< value to select alternate setting
00314     uint8_t bFunctionClass; //!< Class code assigned by the USB
00315     uint8_t bFunctionSubClass;  //!< Sub-class code assigned by the USB
00316     uint8_t bFunctionProtocol;  //!< Protocol code assigned by the USB
00317     uint8_t iFunction;  //!< Index of string descriptor
00318 } usb_association_desc_t;
00319 
00320 
00321 /**
00322  * \brief Standard USB configuration descriptor structure
00323  */
00324 typedef struct {
00325     uint8_t bLength;
00326     uint8_t bDescriptorType;
00327     le16_t wTotalLength;
00328     uint8_t bNumInterfaces;
00329     uint8_t bConfigurationValue;
00330     uint8_t iConfiguration;
00331     uint8_t bmAttributes;
00332     uint8_t bMaxPower;
00333 } usb_conf_desc_t;
00334 
00335 
00336 #define  USB_CONFIG_ATTR_MUST_SET         (1 << 7)  //!< Must always be set
00337 #define  USB_CONFIG_ATTR_BUS_POWERED      (0 << 6)  //!< Bus-powered
00338 #define  USB_CONFIG_ATTR_SELF_POWERED     (1 << 6)  //!< Self-powered
00339 #define  USB_CONFIG_ATTR_REMOTE_WAKEUP    (1 << 5)  //!< remote wakeup supported
00340 
00341 #define  USB_CONFIG_MAX_POWER(ma)         (((ma) + 1) / 2)  //!< Max power in mA
00342 
00343 /**
00344  * \brief Standard USB association descriptor structure
00345  */
00346 typedef struct {
00347     uint8_t bLength;              //!< Size of this descriptor in bytes
00348     uint8_t bDescriptorType;      //!< Interface descriptor type
00349     uint8_t bFirstInterface;      //!< Number of interface
00350     uint8_t bInterfaceCount;      //!< value to select alternate setting
00351     uint8_t bFunctionClass;       //!< Class code assigned by the USB
00352     uint8_t bFunctionSubClass;    //!< Sub-class code assigned by the USB
00353     uint8_t bFunctionProtocol;    //!< Protocol code assigned by the USB
00354     uint8_t iFunction;            //!< Index of string descriptor
00355 } usb_iad_desc_t;
00356 
00357 /**
00358  * \brief Standard USB interface descriptor structure
00359  */
00360 typedef struct {
00361     uint8_t bLength;
00362     uint8_t bDescriptorType;
00363     uint8_t bInterfaceNumber;
00364     uint8_t bAlternateSetting;
00365     uint8_t bNumEndpoints;
00366     uint8_t bInterfaceClass;
00367     uint8_t bInterfaceSubClass;
00368     uint8_t bInterfaceProtocol;
00369     uint8_t iInterface;
00370 } usb_iface_desc_t;
00371 
00372 /**
00373  * \brief Standard USB endpoint descriptor stcuture
00374  */
00375 typedef struct {
00376     uint8_t bLength;
00377     uint8_t bDescriptorType;
00378     uint8_t bEndpointAddress;
00379     uint8_t bmAttributes;
00380     le16_t wMaxPacketSize;
00381     uint8_t bInterval;
00382 } usb_ep_desc_t;
00383 
00384 
00385 /**
00386  * \brief A standard USB string descriptor sructure
00387  */
00388 typedef struct {
00389     uint8_t bLength;
00390     uint8_t bDescriptorType;
00391 } usb_str_desc_t;
00392 
00393 typedef struct {
00394     usb_str_desc_t desc;
00395     le16_t string[1];
00396 } usb_str_lgid_desc_t;
00397 
00398 COMPILER_PACK_RESET()
00399 
00400 //! @}
00401 
00402 #endif /* _USB_PROTOCOL_H_ */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines