src/jtag/drivers/OpenULINK/include/usb.h

   1 /***************************************************************************
   2  *   Copyright (C) 2011 by Martin Schmoelzer                               *
   3  *   <martin.schmoelzer@student.tuwien.ac.at>                              *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   This program is distributed in the hope that it will be useful,       *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  19  ***************************************************************************/
  20
  21 #ifndef __USB_H
  22 #define __USB_H
  23
  24 #include "shorttypes.h"
  25 #include "reg_ezusb.h"
  26
  27 #include <stdbool.h>
  28
  29 #define NULL        (void*)0;
  30
  31 /* High and Low byte of a word (u16) */
  32 #define HI8(word)   (u8)(((u16)word >> 8) & 0xff)
  33 #define LO8(word)   (u8)((u16)word & 0xff)
  34
  35 /* Convenience functions */
  36 #define STALL_EP0()   EP0CS |= EP0STALL
  37 #define CLEAR_IRQ()   EXIF &= ~USBINT
  38
  39 /*********** USB descriptors. See section 9.5 of the USB 1.1 spec **********/
  40
  41 /* USB Descriptor Types. See USB 1.1 spec, page 187, table 9-5 */
  42 #define DESCRIPTOR_TYPE_DEVICE         0x01
  43 #define DESCRIPTOR_TYPE_CONFIGURATION  0x02
  44 #define DESCRIPTOR_TYPE_STRING         0x03
  45 #define DESCRIPTOR_TYPE_INTERFACE      0x04
  46 #define DESCRIPTOR_TYPE_ENDPOINT       0x05
  47
  48 #define STR_DESCR(len,...) { len*2+2, DESCRIPTOR_TYPE_STRING, { __VA_ARGS__ } }
  49
  50 /** USB Device Descriptor. See USB 1.1 spec, pp. 196 - 198 */
  51 struct usb_device_descriptor {
  52   u8  bLength;             ///< Size of this descriptor in bytes.
  53   u8  bDescriptorType;     ///< DEVICE Descriptor Type.
  54   u16 bcdUSB;              ///< USB specification release number (BCD).
  55   u8  bDeviceClass;        ///< Class code.
  56   u8  bDeviceSubClass;     ///< Subclass code.
  57   u8  bDeviceProtocol;     ///< Protocol code.
  58   u8  bMaxPacketSize0;     ///< Maximum packet size for EP0 (8, 16, 32, 64).
  59   u16 idVendor;            ///< USB Vendor ID.
  60   u16 idProduct;           ///< USB Product ID.
  61   u16 bcdDevice;           ///< Device Release Number (BCD).
  62   u8  iManufacturer;       ///< Index of manufacturer string descriptor.
  63   u8  iProduct;            ///< Index of product string descriptor.
  64   u8  iSerialNumber;       ///< Index of string descriptor containing serial #.
  65   u8  bNumConfigurations;  ///< Number of possible configurations.
  66 };
  67
  68 /** USB Configuration Descriptor. See USB 1.1 spec, pp. 199 - 200 */
  69 struct usb_config_descriptor {
  70   u8  bLength;             ///< Size of this descriptor in bytes.
  71   u8  bDescriptorType;     ///< CONFIGURATION descriptor type.
  72   u16 wTotalLength;        ///< Combined total length of all descriptors.
  73   u8  bNumInterfaces;      ///< Number of interfaces in this configuration.
  74   u8  bConfigurationValue; ///< Value used to select this configuration.
  75   u8  iConfiguration;      ///< Index of configuration string descriptor.
  76   u8  bmAttributes;        ///< Configuration characteristics.
  77   u8  MaxPower;            ///< Maximum power consumption in 2 mA units.
  78 };
  79
  80 /** USB Interface Descriptor. See USB 1.1 spec, pp. 201 - 203 */
  81 struct usb_interface_descriptor {
  82   u8  bLength;             ///< Size of this descriptor in bytes.
  83   u8  bDescriptorType;     ///< INTERFACE descriptor type.
  84   u8  bInterfaceNumber;    ///< Interface number.
  85   u8  bAlternateSetting;   ///< Value used to select alternate setting.
  86   u8  bNumEndpoints;       ///< Number of endpoints used by this interface.
  87   u8  bInterfaceClass;     ///< Class code.
  88   u8  bInterfaceSubclass;  ///< Subclass code.
  89   u8  bInterfaceProtocol;  ///< Protocol code.
  90   u8  iInterface;          ///< Index of interface string descriptor.
  91 };
  92
  93 /** USB Endpoint Descriptor. See USB 1.1 spec, pp. 203 - 204 */
  94 struct usb_endpoint_descriptor {
  95   u8  bLength;             ///< Size of this descriptor in bytes.
  96   u8  bDescriptorType;     ///< ENDPOINT descriptor type.
  97   u8  bEndpointAddress;    ///< Endpoint Address: USB 1.1 spec, table 9-10.
  98   u8  bmAttributes;        ///< Endpoint Attributes: USB 1.1 spec, table 9-10.
  99   u16 wMaxPacketSize;      ///< Maximum packet size for this endpoint.
 100   u8  bInterval;           ///< Polling interval (in ms) for this endpoint.
 101 };
 102
 103 /** USB Language Descriptor. See USB 1.1 spec, pp. 204 - 205 */
 104 struct usb_language_descriptor {
 105   u8  bLength;             ///< Size of this descriptor in bytes.
 106   u8  bDescriptorType;     ///< STRING descriptor type.
 107   u16 wLANGID[];           ///< LANGID codes.
 108 };
 109
 110 /** USB String Descriptor. See USB 1.1 spec, pp. 204 - 205 */
 111 struct usb_string_descriptor {
 112   u8  bLength;             ///< Size of this descriptor in bytes.
 113   u8  bDescriptorType;     ///< STRING descriptor type.
 114   u16 bString[];           ///< UNICODE encoded string.
 115 };
 116
 117 /********************** USB Control Endpoint 0 related *********************/
 118
 119 /** USB Control Setup Data. See USB 1.1 spec, pp. 183 - 185 */
 120 struct setup_data {
 121   u8  bmRequestType;       ///< Characteristics of a request.
 122   u8  bRequest;            ///< Specific request.
 123   u16 wValue;              ///< Field that varies according to request.
 124   u16 wIndex;              ///< Field that varies according to request.
 125   u16 wLength;             ///< Number of bytes to transfer in data stage.
 126 };
 127
 128 /* External declarations for variables that need to be accessed outside of
 129  * the USB module */
 130 extern volatile bool EP2_out;
 131 extern volatile bool EP2_in;
 132 extern volatile __xdata __at 0x7FE8 struct setup_data setup_data;
 133
 134 /*
 135  * USB Request Types (bmRequestType): See USB 1.1 spec, page 183, table 9-2
 136  *
 137  * Bit 7: Data transfer direction
 138  *    0 = Host-to-device
 139  *    1 = Device-to-host
 140  * Bit 6...5: Type
 141  *    0 = Standard
 142  *    1 = Class
 143  *    2 = Vendor
 144  *    3 = Reserved
 145  * Bit 4...0: Recipient
 146  *    0 = Device
 147  *    1 = Interface
 148  *    2 = Endpoint
 149  *    3 = Other
 150  *    4...31 = Reserved
 151  */
 152
 153 #define USB_DIR_OUT             0x00
 154 #define USB_DIR_IN              0x80
 155
 156 #define USB_REQ_TYPE_STANDARD   (0x00 << 5)
 157 #define USB_REQ_TYPE_CLASS      (0x01 << 5)
 158 #define USB_REQ_TYPE_VENDOR     (0x02 << 5)
 159 #define USB_REQ_TYPE_RESERVED   (0x03 << 5)
 160
 161 #define USB_RECIP_DEVICE        0x00
 162 #define USB_RECIP_INTERFACE     0x01
 163 #define USB_RECIP_ENDPOINT      0x02
 164 #define USB_RECIP_OTHER         0x03
 165
 166 /* bmRequestType for USB Standard Requests */
 167
 168 /* Clear Interface Request */
 169 #define CF_DEVICE    (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
 170 #define CF_INTERFACE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
 171 #define CF_ENDPOINT  (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_ENDPOINT)
 172
 173 /* Get Configuration Request */
 174 #define GC_DEVICE    (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
 175
 176 /* Get Descriptor Request */
 177 #define GD_DEVICE    (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
 178
 179 /* Get Interface Request */
 180 #define GI_INTERFACE (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
 181
 182 /* Get Status Request: See USB 1.1 spec, page 190 */
 183 #define GS_DEVICE    (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
 184 #define GS_INTERFACE (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
 185 #define GS_ENDPOINT  (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_ENDPOINT)
 186
 187 /* Set Address Request is handled by EZ-USB core */
 188
 189 /* Set Configuration Request */
 190 #define SC_DEVICE    (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
 191
 192 /* Set Descriptor Request */
 193 #define SD_DEVICE    (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
 194
 195 /* Set Feature Request */
 196 #define SF_DEVICE    (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
 197 #define SF_INTERFACE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
 198 #define SF_ENDPOINT  (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_ENDPOINT)
 199
 200 /* Set Interface Request */
 201 #define SI_INTERFACE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
 202
 203 /* Synch Frame Request */
 204 #define SY_ENDPOINT  (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_ENDPOINT)
 205
 206 /* USB Requests (bRequest): See USB 1.1 spec, table 9-4 on page 187 */
 207 #define GET_STATUS               0
 208 #define CLEAR_FEATURE            1
 209 // Value '2' is reserved for future use
 210 #define SET_FEATURE              3
 211 // Value '4' is reserved for future use
 212 #define SET_ADDRESS              5
 213 #define GET_DESCRIPTOR           6
 214 #define SET_DESCRIPTOR           7
 215 #define GET_CONFIGURATION        8
 216 #define SET_CONFIGURATION        9
 217 #define GET_INTERFACE           10
 218 #define SET_INTERFACE           11
 219 #define SYNCH_FRAME             12
 220
 221 /* Standard Feature Selectors: See USB 1.1 spec, table 9-6 on page 188 */
 222 #define DEVICE_REMOTE_WAKEUP     1
 223 #define ENDPOINT_HALT            0
 224
 225 /************************** EZ-USB specific stuff **************************/
 226
 227 /** USB Interrupts. See AN2131-TRM, page 9-4 for details */
 228 enum usb_isr {
 229   SUDAV_ISR = 13,
 230   SOF_ISR,
 231   SUTOK_ISR,
 232   SUSPEND_ISR,
 233   USBRESET_ISR,
 234   IBN_ISR,
 235   EP0IN_ISR,
 236   EP0OUT_ISR,
 237   EP1IN_ISR,
 238   EP1OUT_ISR,
 239   EP2IN_ISR,
 240   EP2OUT_ISR,
 241   EP3IN_ISR,
 242   EP3OUT_ISR,
 243   EP4IN_ISR,
 244   EP4OUT_ISR,
 245   EP5IN_ISR,
 246   EP5OUT_ISR,
 247   EP6IN_ISR,
 248   EP6OUT_ISR,
 249   EP7IN_ISR,
 250   EP7OUT_ISR
 251 };
 252
 253 /*************************** Function Prototypes ***************************/
 254
 255 __xdata u8* usb_get_endpoint_cs_reg(u8 ep);
 256 void usb_reset_data_toggle(u8 ep);
 257
 258 bool usb_handle_get_status(void);
 259 bool usb_handle_clear_feature(void);
 260 bool usb_handle_set_feature(void);
 261 bool usb_handle_get_descriptor(void);
 262 void usb_handle_set_interface(void);
 263
 264 void usb_handle_setup_data(void);
 265 void usb_init(void);
 266
 267 #endif