xref: /illumos-kvm-cmd/hw/usb.h (revision 68396ea9)
1 /*
2  * QEMU USB API
3  *
4  * Copyright (c) 2005 Fabrice Bellard
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to deal
8  * in the Software without restriction, including without limitation the rights
9  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10  * copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22  * THE SOFTWARE.
23  */
24 
25 #include "block.h"
26 #include "qdev.h"
27 #include "qemu-queue.h"
28 
29 #define USB_TOKEN_SETUP 0x2d
30 #define USB_TOKEN_IN    0x69 /* device -> host */
31 #define USB_TOKEN_OUT   0xe1 /* host -> device */
32 
33 /* specific usb messages, also sent in the 'pid' parameter */
34 #define USB_MSG_ATTACH   0x100
35 #define USB_MSG_DETACH   0x101
36 #define USB_MSG_RESET    0x102
37 
38 #define USB_RET_NODEV  (-1)
39 #define USB_RET_NAK    (-2)
40 #define USB_RET_STALL  (-3)
41 #define USB_RET_BABBLE (-4)
42 #define USB_RET_ASYNC  (-5)
43 
44 #define USB_SPEED_LOW   0
45 #define USB_SPEED_FULL  1
46 #define USB_SPEED_HIGH  2
47 #define USB_SPEED_SUPER 3
48 
49 #define USB_SPEED_MASK_LOW   (1 << USB_SPEED_LOW)
50 #define USB_SPEED_MASK_FULL  (1 << USB_SPEED_FULL)
51 #define USB_SPEED_MASK_HIGH  (1 << USB_SPEED_HIGH)
52 #define USB_SPEED_MASK_SUPER (1 << USB_SPEED_SUPER)
53 
54 #define USB_STATE_NOTATTACHED 0
55 #define USB_STATE_ATTACHED    1
56 //#define USB_STATE_POWERED     2
57 #define USB_STATE_DEFAULT     3
58 //#define USB_STATE_ADDRESS     4
59 //#define	USB_STATE_CONFIGURED  5
60 #define USB_STATE_SUSPENDED   6
61 
62 #define USB_CLASS_AUDIO			1
63 #define USB_CLASS_COMM			2
64 #define USB_CLASS_HID			3
65 #define USB_CLASS_PHYSICAL		5
66 #define USB_CLASS_STILL_IMAGE		6
67 #define USB_CLASS_PRINTER		7
68 #define USB_CLASS_MASS_STORAGE		8
69 #define USB_CLASS_HUB			9
70 #define USB_CLASS_CDC_DATA		0x0a
71 #define USB_CLASS_CSCID			0x0b
72 #define USB_CLASS_CONTENT_SEC		0x0d
73 #define USB_CLASS_APP_SPEC		0xfe
74 #define USB_CLASS_VENDOR_SPEC		0xff
75 
76 #define USB_DIR_OUT			0
77 #define USB_DIR_IN			0x80
78 
79 #define USB_TYPE_MASK			(0x03 << 5)
80 #define USB_TYPE_STANDARD		(0x00 << 5)
81 #define USB_TYPE_CLASS			(0x01 << 5)
82 #define USB_TYPE_VENDOR			(0x02 << 5)
83 #define USB_TYPE_RESERVED		(0x03 << 5)
84 
85 #define USB_RECIP_MASK			0x1f
86 #define USB_RECIP_DEVICE		0x00
87 #define USB_RECIP_INTERFACE		0x01
88 #define USB_RECIP_ENDPOINT		0x02
89 #define USB_RECIP_OTHER			0x03
90 
91 #define DeviceRequest ((USB_DIR_IN|USB_TYPE_STANDARD|USB_RECIP_DEVICE)<<8)
92 #define DeviceOutRequest ((USB_DIR_OUT|USB_TYPE_STANDARD|USB_RECIP_DEVICE)<<8)
93 #define InterfaceRequest \
94         ((USB_DIR_IN|USB_TYPE_STANDARD|USB_RECIP_INTERFACE)<<8)
95 #define InterfaceOutRequest \
96         ((USB_DIR_OUT|USB_TYPE_STANDARD|USB_RECIP_INTERFACE)<<8)
97 #define EndpointRequest ((USB_DIR_IN|USB_TYPE_STANDARD|USB_RECIP_ENDPOINT)<<8)
98 #define EndpointOutRequest \
99         ((USB_DIR_OUT|USB_TYPE_STANDARD|USB_RECIP_ENDPOINT)<<8)
100 #define ClassInterfaceRequest \
101         ((USB_DIR_IN|USB_TYPE_CLASS|USB_RECIP_INTERFACE)<<8)
102 #define ClassInterfaceOutRequest \
103         ((USB_DIR_OUT|USB_TYPE_CLASS|USB_RECIP_INTERFACE)<<8)
104 
105 #define USB_REQ_GET_STATUS		0x00
106 #define USB_REQ_CLEAR_FEATURE		0x01
107 #define USB_REQ_SET_FEATURE		0x03
108 #define USB_REQ_SET_ADDRESS		0x05
109 #define USB_REQ_GET_DESCRIPTOR		0x06
110 #define USB_REQ_SET_DESCRIPTOR		0x07
111 #define USB_REQ_GET_CONFIGURATION	0x08
112 #define USB_REQ_SET_CONFIGURATION	0x09
113 #define USB_REQ_GET_INTERFACE		0x0A
114 #define USB_REQ_SET_INTERFACE		0x0B
115 #define USB_REQ_SYNCH_FRAME		0x0C
116 
117 #define USB_DEVICE_SELF_POWERED		0
118 #define USB_DEVICE_REMOTE_WAKEUP	1
119 
120 #define USB_DT_DEVICE			0x01
121 #define USB_DT_CONFIG			0x02
122 #define USB_DT_STRING			0x03
123 #define USB_DT_INTERFACE		0x04
124 #define USB_DT_ENDPOINT			0x05
125 #define USB_DT_DEVICE_QUALIFIER         0x06
126 #define USB_DT_OTHER_SPEED_CONFIG       0x07
127 
128 #define USB_ENDPOINT_XFER_CONTROL	0
129 #define USB_ENDPOINT_XFER_ISOC		1
130 #define USB_ENDPOINT_XFER_BULK		2
131 #define USB_ENDPOINT_XFER_INT		3
132 
133 typedef struct USBBus USBBus;
134 typedef struct USBPort USBPort;
135 typedef struct USBDevice USBDevice;
136 typedef struct USBDeviceInfo USBDeviceInfo;
137 typedef struct USBPacket USBPacket;
138 
139 typedef struct USBDesc USBDesc;
140 typedef struct USBDescID USBDescID;
141 typedef struct USBDescDevice USBDescDevice;
142 typedef struct USBDescConfig USBDescConfig;
143 typedef struct USBDescIface USBDescIface;
144 typedef struct USBDescEndpoint USBDescEndpoint;
145 typedef struct USBDescOther USBDescOther;
146 typedef struct USBDescString USBDescString;
147 
148 struct USBDescString {
149     uint8_t index;
150     char *str;
151     QLIST_ENTRY(USBDescString) next;
152 };
153 
154 /* definition of a USB device */
155 struct USBDevice {
156     DeviceState qdev;
157     USBDeviceInfo *info;
158     USBPort *port;
159     char *port_path;
160     void *opaque;
161 
162     int speed;
163     uint8_t addr;
164     char product_desc[32];
165     int auto_attach;
166     int attached;
167 
168     int32_t state;
169     uint8_t setup_buf[8];
170     uint8_t data_buf[1024];
171     int32_t remote_wakeup;
172     int32_t setup_state;
173     int32_t setup_len;
174     int32_t setup_index;
175 
176     QLIST_HEAD(, USBDescString) strings;
177     const USBDescDevice *device;
178     const USBDescConfig *config;
179 };
180 
181 struct USBDeviceInfo {
182     DeviceInfo qdev;
183     int (*init)(USBDevice *dev);
184 
185     /*
186      * Process USB packet.
187      * Called by the HC (Host Controller).
188      *
189      * Returns length of the transaction
190      * or one of the USB_RET_XXX codes.
191      */
192     int (*handle_packet)(USBDevice *dev, USBPacket *p);
193 
194     /*
195      * Called when device is destroyed.
196      */
197     void (*handle_destroy)(USBDevice *dev);
198 
199     /*
200      * Attach the device
201      */
202     void (*handle_attach)(USBDevice *dev);
203 
204     /*
205      * Reset the device
206      */
207     void (*handle_reset)(USBDevice *dev);
208 
209     /*
210      * Process control request.
211      * Called from handle_packet().
212      *
213      * Returns length or one of the USB_RET_ codes.
214      */
215     int (*handle_control)(USBDevice *dev, int request, int value,
216                           int index, int length, uint8_t *data);
217 
218     /*
219      * Process data transfers (both BULK and ISOC).
220      * Called from handle_packet().
221      *
222      * Returns length or one of the USB_RET_ codes.
223      */
224     int (*handle_data)(USBDevice *dev, USBPacket *p);
225 
226     const char *product_desc;
227     const USBDesc *usb_desc;
228 
229     /* handle legacy -usbdevice command line options */
230     const char *usbdevice_name;
231     USBDevice *(*usbdevice_init)(const char *params);
232 };
233 
234 typedef struct USBPortOps {
235     void (*attach)(USBPort *port);
236     void (*detach)(USBPort *port);
237     void (*wakeup)(USBDevice *dev);
238 } USBPortOps;
239 
240 /* USB port on which a device can be connected */
241 struct USBPort {
242     USBDevice *dev;
243     int speedmask;
244     char path[16];
245     USBPortOps *ops;
246     void *opaque;
247     int index; /* internal port index, may be used with the opaque */
248     QTAILQ_ENTRY(USBPort) next;
249 };
250 
251 typedef void USBCallback(USBPacket * packet, void *opaque);
252 
253 /* Structure used to hold information about an active USB packet.  */
254 struct USBPacket {
255     /* Data fields for use by the driver.  */
256     int pid;
257     uint8_t devaddr;
258     uint8_t devep;
259     uint8_t *data;
260     int len;
261     /* Internal use by the USB layer.  */
262     USBCallback *complete_cb;
263     void *complete_opaque;
264     USBCallback *cancel_cb;
265     void *cancel_opaque;
266 };
267 
268 /* Defer completion of a USB packet.  The hadle_packet routine should then
269    return USB_RET_ASYNC.  Packets that complete immediately (before
270    handle_packet returns) should not call this method.  */
usb_defer_packet(USBPacket * p,USBCallback * cancel,void * opaque)271 static inline void usb_defer_packet(USBPacket *p, USBCallback *cancel,
272                                     void * opaque)
273 {
274     p->cancel_cb = cancel;
275     p->cancel_opaque = opaque;
276 }
277 
278 /* Notify the controller that an async packet is complete.  This should only
279    be called for packets previously deferred with usb_defer_packet, and
280    should never be called from within handle_packet.  */
usb_packet_complete(USBPacket * p)281 static inline void usb_packet_complete(USBPacket *p)
282 {
283     p->complete_cb(p, p->complete_opaque);
284 }
285 
286 /* Cancel an active packet.  The packed must have been deferred with
287    usb_defer_packet,  and not yet completed.  */
usb_cancel_packet(USBPacket * p)288 static inline void usb_cancel_packet(USBPacket * p)
289 {
290     p->cancel_cb(p, p->cancel_opaque);
291 }
292 
293 void usb_attach(USBPort *port, USBDevice *dev);
294 void usb_wakeup(USBDevice *dev);
295 int usb_generic_handle_packet(USBDevice *s, USBPacket *p);
296 int set_usb_string(uint8_t *buf, const char *str);
297 void usb_send_msg(USBDevice *dev, int msg);
298 
299 /* usb-linux.c */
300 USBDevice *usb_host_device_open(const char *devname);
301 int usb_host_device_close(const char *devname);
302 void usb_host_info(Monitor *mon);
303 
304 /* usb-hid.c */
305 void usb_hid_datain_cb(USBDevice *dev, void *opaque, void (*datain)(void *));
306 
307 /* usb-bt.c */
308 USBDevice *usb_bt_init(HCIInfo *hci);
309 
310 /* usb ports of the VM */
311 
312 #define VM_USB_HUB_SIZE 8
313 
314 /* usb-musb.c */
315 enum musb_irq_source_e {
316     musb_irq_suspend = 0,
317     musb_irq_resume,
318     musb_irq_rst_babble,
319     musb_irq_sof,
320     musb_irq_connect,
321     musb_irq_disconnect,
322     musb_irq_vbus_request,
323     musb_irq_vbus_error,
324     musb_irq_rx,
325     musb_irq_tx,
326     musb_set_vbus,
327     musb_set_session,
328     __musb_irq_max,
329 };
330 
331 typedef struct MUSBState MUSBState;
332 MUSBState *musb_init(qemu_irq *irqs);
333 uint32_t musb_core_intr_get(MUSBState *s);
334 void musb_core_intr_clear(MUSBState *s, uint32_t mask);
335 void musb_set_size(MUSBState *s, int epnum, int size, int is_tx);
336 
337 /* usb-bus.c */
338 
339 struct USBBus {
340     BusState qbus;
341     int busnr;
342     int nfree;
343     int nused;
344     QTAILQ_HEAD(, USBPort) free;
345     QTAILQ_HEAD(, USBPort) used;
346     QTAILQ_ENTRY(USBBus) next;
347 };
348 
349 void usb_bus_new(USBBus *bus, DeviceState *host);
350 USBBus *usb_bus_find(int busnr);
351 void usb_qdev_register(USBDeviceInfo *info);
352 void usb_qdev_register_many(USBDeviceInfo *info);
353 USBDevice *usb_create(USBBus *bus, const char *name);
354 USBDevice *usb_create_simple(USBBus *bus, const char *name);
355 USBDevice *usbdevice_create(const char *cmdline);
356 void usb_register_port(USBBus *bus, USBPort *port, void *opaque, int index,
357                        USBPortOps *ops, int speedmask);
358 void usb_port_location(USBPort *downstream, USBPort *upstream, int portnr);
359 void usb_unregister_port(USBBus *bus, USBPort *port);
360 int usb_device_attach(USBDevice *dev);
361 int usb_device_detach(USBDevice *dev);
362 int usb_device_delete_addr(int busnr, int addr);
363 
usb_bus_from_device(USBDevice * d)364 static inline USBBus *usb_bus_from_device(USBDevice *d)
365 {
366     return DO_UPCAST(USBBus, qbus, d->qdev.parent_bus);
367 }
368