src/common/usb_spec.h

   1 /*
   2  * The Clear BSD License
   3  * Copyright (c) 2015 - 2016, Freescale Semiconductor, Inc.
   4  * Copyright 2016 NXP
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without modification,
   8  * are permitted (subject to the limitations in the disclaimer below) provided
   9  * that the following conditions are met:
  10  *
  11  * o Redistributions of source code must retain the above copyright notice, this list
  12  *   of conditions and the following disclaimer.
  13  *
  14  * o Redistributions in binary form must reproduce the above copyright notice, this
  15  *   list of conditions and the following disclaimer in the documentation and/or
  16  *   other materials provided with the distribution.
  17  *
  18  * o Neither the name of the copyright holder nor the names of its
  19  *   contributors may be used to endorse or promote products derived from this
  20  *   software without specific prior written permission.
  21  *
  22  * NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE.
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  24  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  25  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  26  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
  27  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  28  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  30  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  32  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 #ifndef __USB_SPEC_H__
  36 #define __USB_SPEC_H__
  37
  38 /*******************************************************************************
  39  * Definitions
  40  ******************************************************************************/
  41
  42 /* USB speed (the value cannot be changed because EHCI QH use the value directly)*/
  43 #define USB_SPEED_FULL (0x00U)
  44 #define USB_SPEED_LOW (0x01U)
  45 #define USB_SPEED_HIGH (0x02U)
  46
  47 /* Set up packet structure */
  48 typedef struct _usb_setup_struct
  49 {
  50     uint8_t bmRequestType;
  51     uint8_t bRequest;
  52     uint16_t wValue;
  53     uint16_t wIndex;
  54     uint16_t wLength;
  55 } usb_setup_struct_t;
  56
  57 /* USB  standard descriptor endpoint type */
  58 #define USB_ENDPOINT_CONTROL (0x00U)
  59 #define USB_ENDPOINT_ISOCHRONOUS (0x01U)
  60 #define USB_ENDPOINT_BULK (0x02U)
  61 #define USB_ENDPOINT_INTERRUPT (0x03U)
  62
  63 /* USB  standard descriptor transfer direction (cannot change the value because iTD use the value directly) */
  64 #define USB_OUT (0U)
  65 #define USB_IN (1U)
  66
  67 /* USB standard descriptor length */
  68 #define USB_DESCRIPTOR_LENGTH_DEVICE (0x12U)
  69 #define USB_DESCRIPTOR_LENGTH_CONFIGURE (0x09U)
  70 #define USB_DESCRIPTOR_LENGTH_INTERFACE (0x09U)
  71 #define USB_DESCRIPTOR_LENGTH_ENDPOINT (0x07U)
  72 #define USB_DESCRIPTOR_LENGTH_DEVICE_QUALITIER (0x0AU)
  73 #define USB_DESCRIPTOR_LENGTH_OTG_DESCRIPTOR (5U)
  74 #define USB_DESCRIPTOR_LENGTH_BOS_DESCRIPTOR (5U)
  75
  76 /* USB Device Capability Type Codes */
  77 #define USB_DESCRIPTOR_TYPE_DEVICE_CAPABILITY_WIRELESS (0x01U)
  78 #define USB_DESCRIPTOR_TYPE_DEVICE_CAPABILITY_USB20_EXTENSION (0x02U)
  79 #define USB_DESCRIPTOR_TYPE_DEVICE_CAPABILITY_SUPERSPEED (0x03U)
  80
  81 /* USB standard descriptor type */
  82 #define USB_DESCRIPTOR_TYPE_DEVICE (0x01U)
  83 #define USB_DESCRIPTOR_TYPE_CONFIGURE (0x02U)
  84 #define USB_DESCRIPTOR_TYPE_STRING (0x03U)
  85 #define USB_DESCRIPTOR_TYPE_INTERFACE (0x04U)
  86 #define USB_DESCRIPTOR_TYPE_ENDPOINT (0x05U)
  87 #define USB_DESCRIPTOR_TYPE_DEVICE_QUALITIER (0x06U)
  88 #define USB_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIGURATION (0x07U)
  89 #define USB_DESCRIPTOR_TYPE_INTERFAACE_POWER (0x08U)
  90 #define USB_DESCRIPTOR_TYPE_OTG (0x09U)
  91 #define USB_DESCRIPTOR_TYPE_INTERFACE_ASSOCIATION (0x0BU)
  92 #define USB_DESCRIPTOR_TYPE_BOS (0x0F)
  93 #define USB_DESCRIPTOR_TYPE_DEVICE_CAPABILITY (0x10)
  94
  95 #define USB_DESCRIPTOR_TYPE_HID (0x21U)
  96 #define USB_DESCRIPTOR_TYPE_HID_REPORT (0x22U)
  97 #define USB_DESCRIPTOR_TYPE_HID_PHYSICAL (0x23U)
  98
  99 /* USB standard request type */
 100 #define USB_REQUEST_TYPE_DIR_MASK (0x80U)
 101 #define USB_REQUEST_TYPE_DIR_SHIFT (7U)
 102 #define USB_REQUEST_TYPE_DIR_OUT (0x00U)
 103 #define USB_REQUEST_TYPE_DIR_IN (0x80U)
 104
 105 #define USB_REQUEST_TYPE_TYPE_MASK (0x60U)
 106 #define USB_REQUEST_TYPE_TYPE_SHIFT (5U)
 107 #define USB_REQUEST_TYPE_TYPE_STANDARD (0U)
 108 #define USB_REQUEST_TYPE_TYPE_CLASS (0x20U)
 109 #define USB_REQUEST_TYPE_TYPE_VENDOR (0x40U)
 110
 111 #define USB_REQUEST_TYPE_RECIPIENT_MASK (0x1FU)
 112 #define USB_REQUEST_TYPE_RECIPIENT_SHIFT (0U)
 113 #define USB_REQUEST_TYPE_RECIPIENT_DEVICE (0x00U)
 114 #define USB_REQUEST_TYPE_RECIPIENT_INTERFACE (0x01U)
 115 #define USB_REQUEST_TYPE_RECIPIENT_ENDPOINT (0x02U)
 116 #define USB_REQUEST_TYPE_RECIPIENT_OTHER (0x03U)
 117
 118 /* USB standard request */
 119 #define USB_REQUEST_STANDARD_GET_STATUS (0x00U)
 120 #define USB_REQUEST_STANDARD_CLEAR_FEATURE (0x01U)
 121 #define USB_REQUEST_STANDARD_SET_FEATURE (0x03U)
 122 #define USB_REQUEST_STANDARD_SET_ADDRESS (0x05U)
 123 #define USB_REQUEST_STANDARD_GET_DESCRIPTOR (0x06U)
 124 #define USB_REQUEST_STANDARD_SET_DESCRIPTOR (0x07U)
 125 #define USB_REQUEST_STANDARD_GET_CONFIGURATION (0x08U)
 126 #define USB_REQUEST_STANDARD_SET_CONFIGURATION (0x09U)
 127 #define USB_REQUEST_STANDARD_GET_INTERFACE (0x0AU)
 128 #define USB_REQUEST_STANDARD_SET_INTERFACE (0x0BU)
 129 #define USB_REQUEST_STANDARD_SYNCH_FRAME (0x0CU)
 130
 131 /* USB standard request GET Status */
 132 #define USB_REQUEST_STANDARD_GET_STATUS_DEVICE_SELF_POWERED_SHIFT (0U)
 133 #define USB_REQUEST_STANDARD_GET_STATUS_DEVICE_REMOTE_WARKUP_SHIFT (1U)
 134
 135 #define USB_REQUEST_STANDARD_GET_STATUS_ENDPOINT_HALT_MASK (0x01U)
 136 #define USB_REQUEST_STANDARD_GET_STATUS_ENDPOINT_HALT_SHIFT (0U)
 137
 138 #define USB_REQUEST_STANDARD_GET_STATUS_OTG_STATUS_SELECTOR (0xF000U)
 139
 140 /* USB standard request CLEAR/SET feature */
 141 #define USB_REQUEST_STANDARD_FEATURE_SELECTOR_ENDPOINT_HALT (0U)
 142 #define USB_REQUEST_STANDARD_FEATURE_SELECTOR_DEVICE_REMOTE_WAKEUP (1U)
 143 #define USB_REQUEST_STANDARD_FEATURE_SELECTOR_DEVICE_TEST_MODE (2U)
 144 #define USB_REQUEST_STANDARD_FEATURE_SELECTOR_B_HNP_ENABLE (3U)
 145 #define USB_REQUEST_STANDARD_FEATURE_SELECTOR_A_HNP_SUPPORT (4U)
 146 #define USB_REQUEST_STANDARD_FEATURE_SELECTOR_A_ALT_HNP_SUPPORT (5U)
 147
 148 /* USB standard descriptor configure bmAttributes */
 149 #define USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_D7_MASK (0x80U)
 150 #define USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_D7_SHIFT (7U)
 151
 152 #define USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_SELF_POWERED_MASK (0x40U)
 153 #define USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_SELF_POWERED_SHIFT (6U)
 154
 155 #define USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_REMOTE_WAKEUP_MASK (0x20U)
 156 #define USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_REMOTE_WAKEUP_SHIFT (5U)
 157
 158 /* USB standard descriptor endpoint bmAttributes */
 159 #define USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_MASK (0x80U)
 160 #define USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_SHIFT (7U)
 161 #define USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_OUT (0U)
 162 #define USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_IN (0x80U)
 163
 164 #define USB_DESCRIPTOR_ENDPOINT_ADDRESS_NUMBER_MASK (0x0FU)
 165 #define USB_DESCRIPTOR_ENDPOINT_ADDRESS_NUMBER_SHFIT (0U)
 166
 167 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_TYPE_MASK (0x03U)
 168 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_NUMBER_SHFIT (0U)
 169
 170 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_SYNC_TYPE_MASK (0x0CU)
 171 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_SYNC_TYPE_SHFIT (2U)
 172 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_SYNC_TYPE_NO_SYNC (0x00U)
 173 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_SYNC_TYPE_ASYNC (0x04U)
 174 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_SYNC_TYPE_ADAPTIVE (0x08U)
 175 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_SYNC_TYPE_SYNC (0x0CU)
 176
 177 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_USAGE_TYPE_MASK (0x30U)
 178 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_USAGE_TYPE_SHFIT (4U)
 179 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_USAGE_TYPE_DATA_ENDPOINT (0x00U)
 180 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_USAGE_TYPE_FEEDBACK_ENDPOINT (0x10U)
 181 #define USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_USAGE_TYPE_IMPLICIT_FEEDBACK_DATA_ENDPOINT (0x20U)
 182
 183 #define USB_DESCRIPTOR_ENDPOINT_MAXPACKETSIZE_SIZE_MASK (0x07FFu)
 184 #define USB_DESCRIPTOR_ENDPOINT_MAXPACKETSIZE_MULT_TRANSACTIONS_MASK (0x1800u)
 185 #define USB_DESCRIPTOR_ENDPOINT_MAXPACKETSIZE_MULT_TRANSACTIONS_SHFIT (11U)
 186
 187 /* USB standard descriptor otg bmAttributes */
 188 #define USB_DESCRIPTOR_OTG_ATTRIBUTES_SRP_MASK (0x01u)
 189 #define USB_DESCRIPTOR_OTG_ATTRIBUTES_HNP_MASK (0x02u)
 190 #define USB_DESCRIPTOR_OTG_ATTRIBUTES_ADP_MASK (0x04u)
 191
 192 /* USB standard descriptor device capability usb20 extension bmAttributes */
 193 #define USB_DESCRIPTOR_DEVICE_CAPABILITY_USB20_EXTENSION_LPM_MASK (0x02U)
 194 #define USB_DESCRIPTOR_DEVICE_CAPABILITY_USB20_EXTENSION_LPM_SHIFT (1U)
 195 #define USB_DESCRIPTOR_DEVICE_CAPABILITY_USB20_EXTENSION_BESL_MASK (0x04U)
 196 #define USB_DESCRIPTOR_DEVICE_CAPABILITY_USB20_EXTENSION_BESL_SHIFT (2U)
 197
 198
 199 /* Language structure */
 200 typedef struct _usb_language
 201 {
 202     uint8_t **string;    /* The Strings descriptor array */
 203     uint32_t *length;    /* The strings descriptor length array */
 204     uint16_t languageId; /* The language id of current language */
 205 } usb_language_t;
 206
 207 typedef struct _usb_language_list
 208 {
 209     uint8_t *languageString;      /* The String 0U pointer */
 210     uint32_t stringLength;        /* The String 0U Length */
 211     usb_language_t *languageList; /* The language list */
 212     uint8_t count;                /* The language count */
 213 } usb_language_list_t;
 214
 215 typedef struct _usb_descriptor_common
 216 {
 217     uint8_t bLength;         /* Size of this descriptor in bytes */
 218     uint8_t bDescriptorType; /* DEVICE Descriptor Type */
 219     uint8_t bData[1];        /* Data */
 220 } usb_descriptor_common_t;
 221
 222 typedef struct _usb_descriptor_device
 223 {
 224     uint8_t bLength;            /* Size of this descriptor in bytes */
 225     uint8_t bDescriptorType;    /* DEVICE Descriptor Type */
 226     uint8_t bcdUSB[2];          /* UUSB Specification Release Number in Binary-Coded Decimal, e.g. 0x0200U */
 227     uint8_t bDeviceClass;       /* Class code */
 228     uint8_t bDeviceSubClass;    /* Sub-Class code */
 229     uint8_t bDeviceProtocol;    /* Protocol code */
 230     uint8_t bMaxPacketSize0;    /* Maximum packet size for endpoint zero */
 231     uint8_t idVendor[2];        /* Vendor ID (assigned by the USB-IF) */
 232     uint8_t idProduct[2];       /* Product ID (assigned by the manufacturer) */
 233     uint8_t bcdDevice[2];       /* Device release number in binary-coded decimal */
 234     uint8_t iManufacturer;      /* Index of string descriptor describing manufacturer */
 235     uint8_t iProduct;           /* Index of string descriptor describing product */
 236     uint8_t iSerialNumber;      /* Index of string descriptor describing the device serial number */
 237     uint8_t bNumConfigurations; /* Number of possible configurations */
 238 } usb_descriptor_device_t;
 239
 240 typedef struct _usb_descriptor_configuration
 241 {
 242     uint8_t bLength;             /* Descriptor size in bytes = 9U */
 243     uint8_t bDescriptorType;     /* CONFIGURATION type = 2U or 7U */
 244     uint8_t wTotalLength[2];     /* Length of concatenated descriptors */
 245     uint8_t bNumInterfaces;      /* Number of interfaces, this configuration. */
 246     uint8_t bConfigurationValue; /* Value to set this configuration. */
 247     uint8_t iConfiguration;      /* Index to configuration string */
 248     uint8_t bmAttributes;        /* Configuration characteristics */
 249     uint8_t bMaxPower;           /* Maximum power from bus, 2 mA units */
 250 } usb_descriptor_configuration_t;
 251
 252 typedef struct _usb_descriptor_interface
 253 {
 254     uint8_t bLength;
 255     uint8_t bDescriptorType;
 256     uint8_t bInterfaceNumber;
 257     uint8_t bAlternateSetting;
 258     uint8_t bNumEndpoints;
 259     uint8_t bInterfaceClass;
 260     uint8_t bInterfaceSubClass;
 261     uint8_t bInterfaceProtocol;
 262     uint8_t iInterface;
 263 } usb_descriptor_interface_t;
 264
 265 typedef struct _usb_descriptor_endpoint
 266 {
 267     uint8_t bLength;
 268     uint8_t bDescriptorType;
 269     uint8_t bEndpointAddress;
 270     uint8_t bmAttributes;
 271     uint8_t wMaxPacketSize[2];
 272     uint8_t bInterval;
 273 } usb_descriptor_endpoint_t;
 274
 275 typedef struct _usb_descriptor_binary_device_object_store
 276 {
 277     uint8_t bLength;            /* Descriptor size in bytes = 5U */
 278     uint8_t bDescriptorType;    /* BOS Descriptor type = 0FU*/
 279     uint8_t wTotalLength[2];    /*Length of this descriptor and all of its sub descriptors*/
 280     uint8_t bNumDeviceCaps;     /*The number of separate device capability descriptors in the BOS*/
 281 } usb_descriptor_bos_t;
 282
 283 typedef struct _usb_descriptor_usb20_extension
 284 {
 285     uint8_t bLength;            /* Descriptor size in bytes = 7U */
 286     uint8_t bDescriptorType;    /* DEVICE CAPABILITY Descriptor type = 0x10U*/
 287     uint8_t bDevCapabilityType;  /*Length of this descriptor and all of its sub descriptors*/
 288     uint8_t bmAttributes[4];     /*Bitmap encoding of supported device level features.*/
 289 } usb_descriptor_usb20_extension_t;
 290
 291 typedef union _usb_descriptor_union
 292 {
 293     usb_descriptor_common_t common;               /* Common descriptor */
 294     usb_descriptor_device_t device;               /* Device descriptor */
 295     usb_descriptor_configuration_t configuration; /* Configuration descriptor */
 296     usb_descriptor_interface_t interface;         /* Interface descriptor */
 297     usb_descriptor_endpoint_t endpoint;           /* Endpoint descriptor */
 298 } usb_descriptor_union_t;
 299
 300 #endif /* __USB_SPEC_H__ */