1 /* Copyright (c) 2019-2025 Allwinner Technology Co., Ltd. ALL rights reserved. 2 3 * Allwinner is a trademark of Allwinner Technology Co.,Ltd., registered in 4 * the the People's Republic of China and other countries. 5 * All Allwinner Technology Co.,Ltd. trademarks are used with permission. 6 7 * DISCLAIMER 8 * THIRD PARTY LICENCES MAY BE REQUIRED TO IMPLEMENT THE SOLUTION/PRODUCT. 9 * IF YOU NEED TO INTEGRATE THIRD PART'S TECHNOLOGY (SONY, DTS, DOLBY, AVS OR MPEGLA, ETC.) 10 * IN ALLWINNER'SDK OR PRODUCTS, YOU SHALL BE SOLELY RESPONSIBLE TO OBTAIN 11 * ALL APPROPRIATELY REQUIRED THIRD PARTY LICENCES. 12 * ALLWINNER SHALL HAVE NO WARRANTY, INDEMNITY OR OTHER OBLIGATIONS WITH RESPECT TO MATTERS 13 * COVERED UNDER ANY REQUIRED THIRD PARTY LICENSE. 14 * YOU ARE SOLELY RESPONSIBLE FOR YOUR USAGE OF THIRD PART'S TECHNOLOGY. 15 16 17 * THIS SOFTWARE IS PROVIDED BY ALLWINNER"AS IS" AND TO THE MAXIMUM EXTENT 18 * PERMITTED BY LAW, ALLWINNER EXPRESSLY DISCLAIMS ALL WARRANTIES OF ANY KIND, 19 * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION REGARDING 20 * THE TITLE, NON-INFRINGEMENT, ACCURACY, CONDITION, COMPLETENESS, PERFORMANCE 21 * OR MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 22 * IN NO EVENT SHALL ALLWINNER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 24 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 * LOSS OF USE, DATA, OR PROFITS, OR BUSINESS INTERRUPTION) 26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 27 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 29 * OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef __USB_CH9_H__ 33 #define __USB_CH9_H__ 34 35 #include <stdint.h> 36 37 /* CONTROL REQUEST SUPPORT */ 38 39 /* 40 * USB directions 41 * 42 * This bit flag is used in endpoint descriptors' bEndpointAddress field. 43 * It's also one of three fields in control requests bRequestType. 44 */ 45 #define USB_DIR_OUT 0 /* to device */ 46 #define USB_DIR_IN 0x80 /* to host */ 47 48 /* 49 * USB types, the second of three bRequestType fields 50 */ 51 #define USB_TYPE_MASK (0x03 << 5) 52 #define USB_TYPE_STANDARD (0x00 << 5) 53 #define USB_TYPE_CLASS (0x01 << 5) 54 #define USB_TYPE_VENDOR (0x02 << 5) 55 #define USB_TYPE_RESERVED (0x03 << 5) 56 57 /* 58 * USB recipients, the third of three bRequestType fields 59 */ 60 #define USB_RECIP_MASK 0x1f 61 #define USB_RECIP_DEVICE 0x00 62 #define USB_RECIP_INTERFACE 0x01 63 #define USB_RECIP_ENDPOINT 0x02 64 #define USB_RECIP_OTHER 0x03 65 /* From Wireless USB 1.0 */ 66 #define USB_RECIP_PORT 0x04 67 #define USB_RECIP_RPIPE 0x05 68 69 /* 70 * Standard requests, for the bRequest field of a SETUP packet. 71 * 72 * These are qualified by the bRequestType field, so that for example 73 * TYPE_CLASS or TYPE_VENDOR specific feature flags could be retrieved 74 * by a GET_STATUS request. 75 */ 76 #define USB_REQ_GET_STATUS 0x00 77 #define USB_REQ_CLEAR_FEATURE 0x01 78 #define USB_REQ_SET_FEATURE 0x03 79 #define USB_REQ_SET_ADDRESS 0x05 80 #define USB_REQ_GET_DESCRIPTOR 0x06 81 #define USB_REQ_SET_DESCRIPTOR 0x07 82 #define USB_REQ_GET_CONFIGURATION 0x08 83 #define USB_REQ_SET_CONFIGURATION 0x09 84 #define USB_REQ_GET_INTERFACE 0x0A 85 #define USB_REQ_SET_INTERFACE 0x0B 86 #define USB_REQ_SYNCH_FRAME 0x0C 87 #define USB_REQ_SET_SEL 0x30 88 #define USB_REQ_SET_ISOCH_DELAY 0x31 89 90 #define USB_REQ_SET_ENCRYPTION 0x0D /* Wireless USB */ 91 #define USB_REQ_GET_ENCRYPTION 0x0E 92 #define USB_REQ_RPIPE_ABORT 0x0E 93 #define USB_REQ_SET_HANDSHAKE 0x0F 94 #define USB_REQ_RPIPE_RESET 0x0F 95 #define USB_REQ_GET_HANDSHAKE 0x10 96 #define USB_REQ_SET_CONNECTION 0x11 97 #define USB_REQ_SET_SECURITY_DATA 0x12 98 #define USB_REQ_GET_SECURITY_DATA 0x13 99 #define USB_REQ_SET_WUSB_DATA 0x14 100 #define USB_REQ_LOOPBACK_DATA_WRITE 0x15 101 #define USB_REQ_LOOPBACK_DATA_READ 0x16 102 #define USB_REQ_SET_INTERFACE_DS 0x17 103 104 /* specific requests for USB Power Delivery */ 105 #define USB_REQ_GET_PARTNER_PDO 20 106 #define USB_REQ_GET_BATTERY_STATUS 21 107 #define USB_REQ_SET_PDO 22 108 #define USB_REQ_GET_VDM 23 109 #define USB_REQ_SEND_VDM 24 110 111 /* The Link Power Management (LPM) ECN defines USB_REQ_TEST_AND_SET command, 112 * used by hubs to put ports into a new L1 suspend state, except that it 113 * forgot to define its number ... 114 */ 115 116 /* 117 * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and 118 * are read as a bit array returned by USB_REQ_GET_STATUS. (So there 119 * are at most sixteen features of each type.) Hubs may also support a 120 * new USB_REQ_TEST_AND_SET_FEATURE to put ports into L1 suspend. 121 */ 122 #define USB_DEVICE_SELF_POWERED 0 /* (read only) */ 123 #define USB_DEVICE_REMOTE_WAKEUP 1 /* dev may initiate wakeup */ 124 #define USB_DEVICE_TEST_MODE 2 /* (wired high speed only) */ 125 #define USB_DEVICE_BATTERY 2 /* (wireless) */ 126 #define USB_DEVICE_B_HNP_ENABLE 3 /* (otg) dev may initiate HNP */ 127 #define USB_DEVICE_WUSB_DEVICE 3 /* (wireless)*/ 128 #define USB_DEVICE_A_HNP_SUPPORT 4 /* (otg) RH port supports HNP */ 129 #define USB_DEVICE_A_ALT_HNP_SUPPORT 5 /* (otg) other RH port does */ 130 #define USB_DEVICE_DEBUG_MODE 6 /* (special devices only) */ 131 132 /* 133 * Test Mode Selectors 134 * See USB 2.0 spec Table 9-7 135 */ 136 #define TEST_J 1 137 #define TEST_K 2 138 #define TEST_SE0_NAK 3 139 #define TEST_PACKET 4 140 #define TEST_FORCE_EN 5 141 142 /* 143 * New Feature Selectors as added by USB 3.0 144 * See USB 3.0 spec Table 9-7 145 */ 146 #define USB_DEVICE_U1_ENABLE 48 /* dev may initiate U1 transition */ 147 #define USB_DEVICE_U2_ENABLE 49 /* dev may initiate U2 transition */ 148 #define USB_DEVICE_LTM_ENABLE 50 /* dev may send LTM */ 149 #define USB_INTRF_FUNC_SUSPEND 0 /* function suspend */ 150 151 #define USB_INTR_FUNC_SUSPEND_OPT_MASK 0xFF00 152 /* 153 * Suspend Options, Table 9-8 USB 3.0 spec 154 */ 155 #define USB_INTRF_FUNC_SUSPEND_LP (1 << (8 + 0)) 156 #define USB_INTRF_FUNC_SUSPEND_RW (1 << (8 + 1)) 157 158 /* 159 * Interface status, Figure 9-5 USB 3.0 spec 160 */ 161 #define USB_INTRF_STAT_FUNC_RW_CAP 1 162 #define USB_INTRF_STAT_FUNC_RW 2 163 164 #define USB_ENDPOINT_HALT 0 /* IN/OUT will STALL */ 165 166 /* Bit array elements as returned by the USB_REQ_GET_STATUS request. */ 167 #define USB_DEV_STAT_U1_ENABLED 2 /* transition into U1 state */ 168 #define USB_DEV_STAT_U2_ENABLED 3 /* transition into U2 state */ 169 #define USB_DEV_STAT_LTM_ENABLED 4 /* Latency tolerance messages */ 170 171 /* 172 * Feature selectors from Table 9-8 USB Power Delivery spec 173 */ 174 #define USB_DEVICE_BATTERY_WAKE_MASK 40 175 #define USB_DEVICE_OS_IS_PD_AWARE 41 176 #define USB_DEVICE_POLICY_MODE 42 177 #define USB_PORT_PR_SWAP 43 178 #define USB_PORT_GOTO_MIN 44 179 #define USB_PORT_RETURN_POWER 45 180 #define USB_PORT_ACCEPT_PD_REQUEST 46 181 #define USB_PORT_REJECT_PD_REQUEST 47 182 #define USB_PORT_PORT_PD_RESET 48 183 #define USB_PORT_C_PORT_PD_CHANGE 49 184 #define USB_PORT_CABLE_PD_RESET 50 185 #define USB_DEVICE_CHARGING_POLICY 54 186 187 /** 188 * struct usb_ctrlrequest - SETUP data for a USB device control request 189 * @bRequestType: matches the USB bmRequestType field 190 * @bRequest: matches the USB bRequest field 191 * @wValue: matches the USB wValue field (le16 byte order) 192 * @wIndex: matches the USB wIndex field (le16 byte order) 193 * @wLength: matches the USB wLength field (le16 byte order) 194 * 195 * This structure is used to send control requests to a USB device. It matches 196 * the different fields of the USB 2.0 Spec section 9.3, table 9-2. See the 197 * USB spec for a fuller description of the different fields, and what they are 198 * used for. 199 * 200 * Note that the driver for any interface can issue control requests. 201 * For most devices, interfaces don't coordinate with each other, so 202 * such requests may be made at any time. 203 */ 204 struct usb_ctrlrequest { 205 uint8_t bRequestType; 206 uint8_t bRequest; 207 uint16_t wValue; 208 uint16_t wIndex; 209 uint16_t wLength; 210 }; 211 212 /*-------------------------------------------------------------------------*/ 213 214 /* 215 * STANDARD DESCRIPTORS ... as returned by GET_DESCRIPTOR, or 216 * (rarely) accepted by SET_DESCRIPTOR. 217 * 218 * Note that all multi-byte values here are encoded in little endian 219 * byte order "on the wire". Within the kernel and when exposed 220 * through the Linux-USB APIs, they are not converted to cpu byte 221 * order; it is the responsibility of the client code to do this. 222 * The single exception is when device and configuration descriptors (but 223 * not other descriptors) are read from usbfs (i.e. /proc/bus/usb/BBB/DDD); 224 * in this case the fields are converted to host endianness by the kernel. 225 */ 226 227 /* 228 * Descriptor types ... USB 2.0 spec table 9.5 229 */ 230 #define USB_DT_DEVICE 0x01 231 #define USB_DT_CONFIG 0x02 232 #define USB_DT_STRING 0x03 233 #define USB_DT_INTERFACE 0x04 234 #define USB_DT_ENDPOINT 0x05 235 #define USB_DT_DEVICE_QUALIFIER 0x06 236 #define USB_DT_OTHER_SPEED_CONFIG 0x07 237 #define USB_DT_INTERFACE_POWER 0x08 238 /* these are from a minor usb 2.0 revision (ECN) */ 239 #define USB_DT_OTG 0x09 240 #define USB_DT_DEBUG 0x0a 241 #define USB_DT_INTERFACE_ASSOCIATION 0x0b 242 /* these are from the Wireless USB spec */ 243 #define USB_DT_SECURITY 0x0c 244 #define USB_DT_KEY 0x0d 245 #define USB_DT_ENCRYPTION_TYPE 0x0e 246 #define USB_DT_BOS 0x0f 247 #define USB_DT_DEVICE_CAPABILITY 0x10 248 #define USB_DT_WIRELESS_ENDPOINT_COMP 0x11 249 #define USB_DT_WIRE_ADAPTER 0x21 250 #define USB_DT_RPIPE 0x22 251 #define USB_DT_CS_RADIO_CONTROL 0x23 252 /* From the T10 UAS specification */ 253 #define USB_DT_PIPE_USAGE 0x24 254 /* From the USB 3.0 spec */ 255 #define USB_DT_SS_ENDPOINT_COMP 0x30 256 /* From the USB 3.1 spec */ 257 #define USB_DT_SSP_ISOC_ENDPOINT_COMP 0x31 258 259 /* Conventional codes for class-specific descriptors. The convention is 260 * defined in the USB "Common Class" Spec (3.11). Individual class specs 261 * are authoritative for their usage, not the "common class" writeup. 262 */ 263 #define USB_DT_CS_DEVICE (USB_TYPE_CLASS | USB_DT_DEVICE) 264 #define USB_DT_CS_CONFIG (USB_TYPE_CLASS | USB_DT_CONFIG) 265 #define USB_DT_CS_STRING (USB_TYPE_CLASS | USB_DT_STRING) 266 #define USB_DT_CS_INTERFACE (USB_TYPE_CLASS | USB_DT_INTERFACE) 267 #define USB_DT_CS_ENDPOINT (USB_TYPE_CLASS | USB_DT_ENDPOINT) 268 269 /* All standard descriptors have these 2 fields at the beginning */ 270 struct usb_descriptor_header { 271 uint8_t bLength; 272 uint8_t bDescriptorType; 273 }; 274 275 276 /*-------------------------------------------------------------------------*/ 277 278 /* USB_DT_DEVICE: Device descriptor */ 279 struct usb_device_descriptor { 280 uint8_t bLength; 281 uint8_t bDescriptorType; 282 283 uint16_t bcdUSB; 284 uint8_t bDeviceClass; 285 uint8_t bDeviceSubClass; 286 uint8_t bDeviceProtocol; 287 uint8_t bMaxPacketSize0; 288 uint16_t idVendor; 289 uint16_t idProduct; 290 uint16_t bcdDevice; 291 uint8_t iManufacturer; 292 uint8_t iProduct; 293 uint8_t iSerialNumber; 294 uint8_t bNumConfigurations; 295 }; 296 297 #define USB_DT_DEVICE_SIZE 18 298 299 300 /* 301 * Device and/or Interface Class codes 302 * as found in bDeviceClass or bInterfaceClass 303 * and defined by www.usb.org documents 304 */ 305 #define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */ 306 #define USB_CLASS_AUDIO 1 307 #define USB_CLASS_COMM 2 308 #define USB_CLASS_HID 3 309 #define USB_CLASS_PHYSICAL 5 310 #define USB_CLASS_STILL_IMAGE 6 311 #define USB_CLASS_PRINTER 7 312 #define USB_CLASS_MASS_STORAGE 8 313 #define USB_CLASS_HUB 9 314 #define USB_CLASS_CDC_DATA 0x0a 315 #define USB_CLASS_CSCID 0x0b /* chip+ smart card */ 316 #define USB_CLASS_CONTENT_SEC 0x0d /* content security */ 317 #define USB_CLASS_VIDEO 0x0e 318 #define USB_CLASS_WIRELESS_CONTROLLER 0xe0 319 #define USB_CLASS_MISC 0xef 320 #define USB_CLASS_APP_SPEC 0xfe 321 #define USB_CLASS_VENDOR_SPEC 0xff 322 323 #define USB_SUBCLASS_VENDOR_SPEC 0xff 324 325 /*-------------------------------------------------------------------------*/ 326 327 /* USB_DT_CONFIG: Configuration descriptor information. 328 * 329 * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the 330 * descriptor type is different. Highspeed-capable devices can look 331 * different depending on what speed they're currently running. Only 332 * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG 333 * descriptors. 334 */ 335 struct usb_config_descriptor { 336 uint8_t bLength; 337 uint8_t bDescriptorType; 338 339 uint16_t wTotalLength; 340 uint8_t bNumInterfaces; 341 uint8_t bConfigurationValue; 342 uint8_t iConfiguration; 343 uint8_t bmAttributes; 344 uint8_t bMaxPower; 345 }; 346 347 #define USB_DT_CONFIG_SIZE 9 348 349 /* from config descriptor bmAttributes */ 350 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */ 351 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */ 352 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */ 353 #define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */ 354 355 /*-------------------------------------------------------------------------*/ 356 357 /* USB_DT_STRING: String descriptor */ 358 struct usb_string_descriptor { 359 uint8_t bLength; 360 uint8_t bDescriptorType; 361 362 uint16_t wData[1]; /* UTF-16LE encoded */ 363 }; 364 365 /* note that "string" zero is special, it holds language codes that 366 * the device supports, not Unicode characters. 367 */ 368 369 /*-------------------------------------------------------------------------*/ 370 371 /* USB_DT_INTERFACE: Interface descriptor */ 372 struct usb_interface_descriptor { 373 uint8_t bLength; 374 uint8_t bDescriptorType; 375 376 uint8_t bInterfaceNumber; 377 uint8_t bAlternateSetting; 378 uint8_t bNumEndpoints; 379 uint8_t bInterfaceClass; 380 uint8_t bInterfaceSubClass; 381 uint8_t bInterfaceProtocol; 382 uint8_t iInterface; 383 }; 384 385 #define USB_DT_INTERFACE_SIZE 9 386 387 /*-------------------------------------------------------------------------*/ 388 389 /* USB_DT_ENDPOINT: Endpoint descriptor */ 390 struct usb_endpoint_descriptor { 391 uint8_t bLength; 392 uint8_t bDescriptorType; 393 394 uint8_t bEndpointAddress; 395 uint8_t bmAttributes; 396 uint16_t wMaxPacketSize; 397 uint8_t bInterval; 398 399 /* NOTE: these two are _only_ in audio endpoints. */ 400 /* use USB_DT_ENDPOINT*_SIZE in bLength, not sizeof. */ 401 uint8_t bRefresh; 402 uint8_t bSynchAddress; 403 }; 404 405 #define USB_DT_ENDPOINT_SIZE 7 406 #define USB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */ 407 408 409 /* 410 * Endpoints 411 */ 412 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */ 413 #define USB_ENDPOINT_DIR_MASK 0x80 414 415 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */ 416 #define USB_ENDPOINT_XFER_CONTROL 0 417 #define USB_ENDPOINT_XFER_ISOC 1 418 #define USB_ENDPOINT_XFER_BULK 2 419 #define USB_ENDPOINT_XFER_INT 3 420 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80 421 422 #define USB_EP_MAXP_MULT_SHIFT 11 423 #define USB_EP_MAXP_MULT_MASK (3 << USB_EP_MAXP_MULT_SHIFT) 424 #define USB_EP_MAXP_MULT(m) \ 425 (((m) & USB_EP_MAXP_MULT_MASK) >> USB_EP_MAXP_MULT_SHIFT) 426 427 /* The USB 3.0 spec redefines bits 5:4 of bmAttributes as interrupt ep type. */ 428 #define USB_ENDPOINT_INTRTYPE 0x30 429 #define USB_ENDPOINT_INTR_PERIODIC (0 << 4) 430 #define USB_ENDPOINT_INTR_NOTIFICATION (1 << 4) 431 432 #define USB_ENDPOINT_SYNCTYPE 0x0c 433 #define USB_ENDPOINT_SYNC_NONE (0 << 2) 434 #define USB_ENDPOINT_SYNC_ASYNC (1 << 2) 435 #define USB_ENDPOINT_SYNC_ADAPTIVE (2 << 2) 436 #define USB_ENDPOINT_SYNC_SYNC (3 << 2) 437 438 #define USB_ENDPOINT_USAGE_MASK 0x30 439 #define USB_ENDPOINT_USAGE_DATA 0x00 440 #define USB_ENDPOINT_USAGE_FEEDBACK 0x10 441 #define USB_ENDPOINT_USAGE_IMPLICIT_FB 0x20 /* Implicit feedback Data endpoint */ 442 443 444 445 446 #endif /*__USB_CH9_H__*/ 447