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

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