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
gen_bmRequestType(dev_req_dir dir,dev_req_type type,dev_req_recp recp)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
usb_debug(const char * fmt,...)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
373