usb.h
1 /* 2 * 3 * Copyright (C) 2008 coresystems GmbH 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #ifndef __USB_H 30 #define __USB_H 31 #include <libpayload.h> 32 #include <pci/pci.h> 33 #include <stdint.h> 34 35 typedef enum { host_to_device = 0, device_to_host = 1 } dev_req_dir; 36 typedef enum { standard_type = 0, class_type = 1, vendor_type = 37 2, reserved_type = 3 38 } dev_req_type; 39 typedef enum { dev_recp = 0, iface_recp = 1, endp_recp = 2, other_recp = 3 40 } dev_req_recp; 41 42 enum { 43 DT_DEV = 1, 44 DT_CFG = 2, 45 DT_STR = 3, 46 DT_INTF = 4, 47 DT_ENDP = 5, 48 }; 49 50 typedef enum { 51 GET_STATUS = 0, 52 CLEAR_FEATURE = 1, 53 SET_FEATURE = 3, 54 SET_ADDRESS = 5, 55 GET_DESCRIPTOR = 6, 56 SET_DESCRIPTOR = 7, 57 GET_CONFIGURATION = 8, 58 SET_CONFIGURATION = 9, 59 GET_INTERFACE = 10, 60 SET_INTERFACE = 11, 61 SYNCH_FRAME = 12 62 } bRequest_Codes; 63 64 typedef enum { 65 ENDPOINT_HALT = 0, 66 DEVICE_REMOTE_WAKEUP = 1, 67 TEST_MODE = 2 68 } feature_selectors; 69 70 /* SetAddress() recovery interval (USB 2.0 specification 9.2.6.3 */ 71 #define SET_ADDRESS_MDELAY 2 72 73 /* 74 * USB sets an upper limit of 5 seconds for any transfer to be completed. 75 * 76 * Data originally from EHCI driver: 77 * Tested with some USB2.0 flash sticks: 78 * TUR turn around took about 2.2s for the slowest (13fe:3800), maximum 79 * of 250ms for the others. 80 * 81 * SET ADDRESS on xHCI controllers. 82 * The USB specification indicates that devices must complete processing 83 * of a SET ADDRESS request within 50 ms. However, some hubs were found 84 * to take more than 100 ms to complete a SET ADDRESS request on a 85 * downstream port. 86 */ 87 #define USB_MAX_PROCESSING_TIME_US (5 * 1000 * 1000) 88 89 #define USB_FULL_LOW_SPEED_FRAME_US 1000 90 91 typedef struct { 92 unsigned char bDescLength; 93 unsigned char bDescriptorType; 94 unsigned char bNbrPorts; 95 union { 96 struct { 97 unsigned long logicalPowerSwitchingMode:2; 98 unsigned long isCompoundDevice:1; 99 unsigned long overcurrentProtectionMode:2; 100 unsigned long ttThinkTime:2; 101 unsigned long arePortIndicatorsSupported:1; 102 unsigned long:8; 103 } __packed; 104 unsigned short wHubCharacteristics; 105 } __packed; 106 unsigned char bPowerOn2PwrGood; 107 unsigned char bHubContrCurrent; 108 char DeviceRemovable[]; 109 } __packed hub_descriptor_t; 110 111 typedef struct { 112 unsigned char bLength; 113 unsigned char bDescriptorType; 114 unsigned short bcdUSB; 115 unsigned char bDeviceClass; 116 unsigned char bDeviceSubClass; 117 unsigned char bDeviceProtocol; 118 unsigned char bMaxPacketSize0; 119 unsigned short idVendor; 120 unsigned short idProduct; 121 unsigned short bcdDevice; 122 unsigned char iManufacturer; 123 unsigned char iProduct; 124 unsigned char iSerialNumber; 125 unsigned char bNumConfigurations; 126 } __packed device_descriptor_t; 127 128 typedef struct { 129 unsigned char bLength; 130 unsigned char bDescriptorType; 131 unsigned short wTotalLength; 132 unsigned char bNumInterfaces; 133 unsigned char bConfigurationValue; 134 unsigned char iConfiguration; 135 unsigned char bmAttributes; 136 unsigned char bMaxPower; 137 } __packed configuration_descriptor_t; 138 139 typedef struct { 140 unsigned char bLength; 141 unsigned char bDescriptorType; 142 unsigned char bInterfaceNumber; 143 unsigned char bAlternateSetting; 144 unsigned char bNumEndpoints; 145 unsigned char bInterfaceClass; 146 unsigned char bInterfaceSubClass; 147 unsigned char bInterfaceProtocol; 148 unsigned char iInterface; 149 } __packed interface_descriptor_t; 150 151 typedef struct { 152 unsigned char bLength; 153 unsigned char bDescriptorType; 154 unsigned char bEndpointAddress; 155 unsigned char bmAttributes; 156 unsigned short wMaxPacketSize; 157 unsigned char bInterval; 158 } __packed endpoint_descriptor_t; 159 160 typedef struct { 161 unsigned char bLength; 162 unsigned char bDescriptorType; 163 unsigned short bcdHID; 164 unsigned char bCountryCode; 165 unsigned char bNumDescriptors; 166 unsigned char bReportDescriptorType; 167 unsigned short wReportDescriptorLength; 168 } __packed hid_descriptor_t; 169 170 typedef struct { 171 union { 172 struct { 173 dev_req_recp req_recp:5; 174 dev_req_type req_type:2; 175 dev_req_dir data_dir:1; 176 } __packed; 177 unsigned char bmRequestType; 178 } __packed; 179 unsigned char bRequest; 180 unsigned short wValue; 181 unsigned short wIndex; 182 unsigned short wLength; 183 } __packed dev_req_t; 184 185 struct usbdev_hc; 186 typedef struct usbdev_hc hci_t; 187 188 struct usbdev; 189 typedef struct usbdev usbdev_t; 190 191 typedef enum { SETUP, IN, OUT } direction_t; 192 typedef enum { CONTROL = 0, ISOCHRONOUS = 1, BULK = 2, INTERRUPT = 3 193 } endpoint_type; 194 195 typedef struct { 196 usbdev_t *dev; 197 int endpoint; 198 direction_t direction; 199 int toggle; 200 int maxpacketsize; 201 endpoint_type type; 202 int interval; /* expressed as binary logarithm of the number 203 of microframes (i.e. t = 125us * 2^interval) */ 204 } endpoint_t; 205 206 typedef enum { 207 UNKNOWN_SPEED = -1, 208 FULL_SPEED = 0, 209 LOW_SPEED = 1, 210 HIGH_SPEED = 2, 211 SUPER_SPEED = 3, 212 SUPER_SPEED_PLUS = 4, 213 } usb_speed; 214 215 struct usbdev { 216 hci_t *controller; 217 endpoint_t endpoints[32]; 218 int num_endp; 219 int address; // USB address 220 int hub; // hub, device is attached to 221 int port; // port where device is attached 222 usb_speed speed; 223 u32 quirks; // quirks field. got to love usb 224 void *data; 225 device_descriptor_t *descriptor; 226 configuration_descriptor_t *configuration; 227 void (*init) (usbdev_t *dev); 228 void (*destroy) (usbdev_t *dev); 229 void (*poll) (usbdev_t *dev); 230 }; 231 232 typedef enum { OHCI = 0, UHCI = 1, EHCI = 2, XHCI = 3, DWC2 = 4} hc_type; 233 234 struct usbdev_hc { 235 hci_t *next; 236 uintptr_t reg_base; 237 pcidev_t pcidev; // 0 if not used (eg on ARM) 238 hc_type type; 239 int latest_address; 240 usbdev_t *devices[128]; // dev 0 is root hub, 127 is last addressable 241 242 /* start(): Resume operation. */ 243 void (*start) (hci_t *controller); 244 /* stop(): Stop operation but keep controller initialized. */ 245 void (*stop) (hci_t *controller); 246 /* reset(): Perform a controller reset. The controller needs to 247 be (re)initialized afterwards to work (again). */ 248 void (*reset) (hci_t *controller); 249 /* init(): Initialize a (previously reset) controller 250 to a working state. */ 251 void (*init) (hci_t *controller); 252 /* shutdown(): Stop operation, detach host controller and shutdown 253 this driver instance. After calling shutdown() any 254 other usage of this hci_t* is invalid. */ 255 void (*shutdown) (hci_t *controller); 256 257 int (*bulk) (endpoint_t *ep, int size, u8 *data, int finalize); 258 int (*control) (usbdev_t *dev, direction_t pid, int dr_length, 259 void *devreq, int data_length, u8 *data); 260 void* (*create_intr_queue) (endpoint_t *ep, int reqsize, int reqcount, int reqtiming); 261 void (*destroy_intr_queue) (endpoint_t *ep, void *queue); 262 u8* (*poll_intr_queue) (void *queue); 263 void *instance; 264 265 /* set_address(): Tell the USB device its address (xHCI 266 controllers want to do this by 267 themselves). Also, allocate the usbdev 268 structure, initialize enpoint 0 269 (including MPS) and return it. */ 270 usbdev_t *(*set_address) (hci_t *controller, usb_speed speed, 271 int hubport, int hubaddr); 272 /* finish_device_config(): Another hook for xHCI, 273 returns 0 on success. */ 274 int (*finish_device_config) (usbdev_t *dev); 275 /* destroy_device(): Finally, destroy all structures that 276 were allocated during set_address() 277 and finish_device_config(). */ 278 void (*destroy_device) (hci_t *controller, int devaddr); 279 }; 280 281 hci_t *usb_add_mmio_hc(hc_type type, void *bar); 282 hci_t *new_controller (void); 283 void detach_controller (hci_t *controller); 284 void usb_poll (void); 285 usbdev_t *init_device_entry (hci_t *controller, int num); 286 287 int usb_decode_mps0 (usb_speed speed, u8 bMaxPacketSize0); 288 int speed_to_default_mps(usb_speed speed); 289 int set_feature (usbdev_t *dev, int endp, int feature, int rtype); 290 int get_status (usbdev_t *dev, int endp, int rtype, int len, void *data); 291 int get_descriptor (usbdev_t *dev, int rtype, int descType, int descIdx, 292 void *data, size_t len); 293 int set_configuration (usbdev_t *dev); 294 int clear_feature (usbdev_t *dev, int endp, int feature, int rtype); 295 int clear_stall (endpoint_t *ep); 296 _Bool is_usb_speed_ss(usb_speed speed); 297 298 void usb_nop_init (usbdev_t *dev); 299 void usb_hub_init (usbdev_t *dev); 300 void usb_hid_init (usbdev_t *dev); 301 void usb_msc_init (usbdev_t *dev); 302 void usb_generic_init (usbdev_t *dev); 303 304 int closest_usb2_hub(const usbdev_t *dev, int *const addr, int *const port); 305 306 static inline unsigned char 307 gen_bmRequestType (dev_req_dir dir, dev_req_type type, dev_req_recp recp) 308 { 309 return (dir << 7) | (type << 5) | recp; 310 } 311 312 /* default "set address" handler */ 313 usbdev_t *generic_set_address (hci_t *controller, usb_speed speed, 314 int hubport, int hubaddr); 315 316 void usb_detach_device(hci_t *controller, int devno); 317 int usb_attach_device(hci_t *controller, int hubaddress, int port, 318 usb_speed speed); 319 320 u32 pci_quirk_check(pcidev_t controller); 321 u32 usb_quirk_check(u16 vendor, u16 device); 322 int usb_interface_check(u16 vendor, u16 device); 323 324 #define USB_QUIRK_MSC_FORCE_PROTO_SCSI (1 << 0) 325 #define USB_QUIRK_MSC_FORCE_PROTO_ATAPI (1 << 1) 326 #define USB_QUIRK_MSC_FORCE_PROTO_UFI (1 << 2) 327 #define USB_QUIRK_MSC_FORCE_PROTO_RBC (1 << 3) 328 #define USB_QUIRK_MSC_FORCE_TRANS_BBB (1 << 4) 329 #define USB_QUIRK_MSC_FORCE_TRANS_CBI (1 << 5) 330 #define USB_QUIRK_MSC_FORCE_TRANS_CBI_I (1 << 6) 331 #define USB_QUIRK_MSC_NO_TEST_UNIT_READY (1 << 7) 332 #define USB_QUIRK_MSC_SHORT_INQUIRY (1 << 8) 333 #define USB_QUIRK_HUB_NO_USBSTS_PCD (1 << 9) 334 #define USB_QUIRK_TEST (1 << 31) 335 #define USB_QUIRK_NONE 0 336 337 static inline void __attribute__((format(printf, 1, 2))) usb_debug(const char *fmt, ...) 338 { 339 #ifdef USB_DEBUG 340 va_list ap; 341 va_start(ap, fmt); 342 vprintf(fmt, ap); 343 va_end(ap); 344 #endif 345 } 346 347 /** 348 * To be implemented by libpayload-client. It's called by the USB 349 * stack just before iterating over known devices to poll them for 350 * status change. 351 */ 352 void __attribute__((weak)) usb_poll_prepare (void); 353 354 /** 355 * To be implemented by libpayload-client. It's called by the USB stack 356 * when a new USB device is found which isn't claimed by a built in driver, 357 * so the client has the chance to know about it. 358 * 359 * @param dev descriptor for the USB device 360 */ 361 void __attribute__((weak)) usb_generic_create (usbdev_t *dev); 362 363 /** 364 * To be implemented by libpayload-client. It's called by the USB stack 365 * when it finds out that a USB device is removed which wasn't claimed by a 366 * built in driver. 367 * 368 * @param dev descriptor for the USB device 369 */ 370 void __attribute__((weak)) usb_generic_remove (usbdev_t *dev); 371 372 #endif