1 | /** @file
|
---|
2 | * VUSB - VirtualBox USB. (DEV,VMM)
|
---|
3 | */
|
---|
4 |
|
---|
5 | /*
|
---|
6 | * Copyright (C) 2006-2015 Oracle Corporation
|
---|
7 | *
|
---|
8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
9 | * available from http://www.virtualbox.org. This file is free software;
|
---|
10 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
11 | * General Public License (GPL) as published by the Free Software
|
---|
12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
15 | *
|
---|
16 | * The contents of this file may alternatively be used under the terms
|
---|
17 | * of the Common Development and Distribution License Version 1.0
|
---|
18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
19 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
20 | * CDDL are applicable instead of those of the GPL.
|
---|
21 | *
|
---|
22 | * You may elect to license modified versions of this file under the
|
---|
23 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
24 | */
|
---|
25 |
|
---|
26 | #ifndef ___VBox_vusb_h
|
---|
27 | #define ___VBox_vusb_h
|
---|
28 |
|
---|
29 | #include <VBox/cdefs.h>
|
---|
30 | #include <VBox/types.h>
|
---|
31 |
|
---|
32 | struct PDMLED;
|
---|
33 |
|
---|
34 | RT_C_DECLS_BEGIN
|
---|
35 |
|
---|
36 | /** @defgroup grp_vusb VBox USB API
|
---|
37 | * @{
|
---|
38 | */
|
---|
39 |
|
---|
40 | /** @defgroup grp_vusb_std Standard Stuff
|
---|
41 | * @{ */
|
---|
42 |
|
---|
43 | /** Frequency of USB bus (from spec). */
|
---|
44 | #define VUSB_BUS_HZ 12000000
|
---|
45 |
|
---|
46 |
|
---|
47 | /** @name USB Descriptor types (from spec)
|
---|
48 | * @{ */
|
---|
49 | #define VUSB_DT_DEVICE 0x01
|
---|
50 | #define VUSB_DT_CONFIG 0x02
|
---|
51 | #define VUSB_DT_STRING 0x03
|
---|
52 | #define VUSB_DT_INTERFACE 0x04
|
---|
53 | #define VUSB_DT_ENDPOINT 0x05
|
---|
54 | #define VUSB_DT_DEVICE_QUALIFIER 0x06
|
---|
55 | #define VUSB_DT_OTHER_SPEED_CFG 0x07
|
---|
56 | #define VUSB_DT_INTERFACE_POWER 0x08
|
---|
57 | #define VUSB_DT_INTERFACE_ASSOCIATION 0x0B
|
---|
58 | #define VUSB_DT_BOS 0x0F
|
---|
59 | #define VUSB_DT_DEVICE_CAPABILITY 0x10
|
---|
60 | #define VUSB_DT_SS_ENDPOINT_COMPANION 0x30
|
---|
61 | /** @} */
|
---|
62 |
|
---|
63 | /** @name USB Descriptor minimum sizes (from spec)
|
---|
64 | * @{ */
|
---|
65 | #define VUSB_DT_DEVICE_MIN_LEN 18
|
---|
66 | #define VUSB_DT_CONFIG_MIN_LEN 9
|
---|
67 | #define VUSB_DT_CONFIG_STRING_MIN_LEN 2
|
---|
68 | #define VUSB_DT_INTERFACE_MIN_LEN 9
|
---|
69 | #define VUSB_DT_ENDPOINT_MIN_LEN 7
|
---|
70 | #define VUSB_DT_SSEP_COMPANION_MIN_LEN 6
|
---|
71 | /** @} */
|
---|
72 |
|
---|
73 | /** @name USB Device Capability Type Codes (from spec)
|
---|
74 | * @{ */
|
---|
75 | #define VUSB_DCT_WIRELESS_USB 0x01
|
---|
76 | #define VUSB_DCT_USB_20_EXTENSION 0x02
|
---|
77 | #define VUSB_DCT_SUPERSPEED_USB 0x03
|
---|
78 | #define VUSB_DCT_CONTAINER_ID 0x04
|
---|
79 | /** @} */
|
---|
80 |
|
---|
81 |
|
---|
82 | #pragma pack(1) /* ensure byte packing of the descriptors. */
|
---|
83 |
|
---|
84 | /**
|
---|
85 | * USB language id descriptor (from specs).
|
---|
86 | */
|
---|
87 | typedef struct VUSBDESCLANGID
|
---|
88 | {
|
---|
89 | uint8_t bLength;
|
---|
90 | uint8_t bDescriptorType;
|
---|
91 | } VUSBDESCLANGID;
|
---|
92 | /** Pointer to a USB language id descriptor. */
|
---|
93 | typedef VUSBDESCLANGID *PVUSBDESCLANGID;
|
---|
94 | /** Pointer to a const USB language id descriptor. */
|
---|
95 | typedef const VUSBDESCLANGID *PCVUSBDESCLANGID;
|
---|
96 |
|
---|
97 |
|
---|
98 | /**
|
---|
99 | * USB string descriptor (from specs).
|
---|
100 | */
|
---|
101 | typedef struct VUSBDESCSTRING
|
---|
102 | {
|
---|
103 | uint8_t bLength;
|
---|
104 | uint8_t bDescriptorType;
|
---|
105 | } VUSBDESCSTRING;
|
---|
106 | /** Pointer to a USB string descriptor. */
|
---|
107 | typedef VUSBDESCSTRING *PVUSBDESCSTRING;
|
---|
108 | /** Pointer to a const USB string descriptor. */
|
---|
109 | typedef const VUSBDESCSTRING *PCVUSBDESCSTRING;
|
---|
110 |
|
---|
111 |
|
---|
112 | /**
|
---|
113 | * USB device descriptor (from spec)
|
---|
114 | */
|
---|
115 | typedef struct VUSBDESCDEVICE
|
---|
116 | {
|
---|
117 | uint8_t bLength;
|
---|
118 | uint8_t bDescriptorType;
|
---|
119 | uint16_t bcdUSB;
|
---|
120 | uint8_t bDeviceClass;
|
---|
121 | uint8_t bDeviceSubClass;
|
---|
122 | uint8_t bDeviceProtocol;
|
---|
123 | uint8_t bMaxPacketSize0;
|
---|
124 | uint16_t idVendor;
|
---|
125 | uint16_t idProduct;
|
---|
126 | uint16_t bcdDevice;
|
---|
127 | uint8_t iManufacturer;
|
---|
128 | uint8_t iProduct;
|
---|
129 | uint8_t iSerialNumber;
|
---|
130 | uint8_t bNumConfigurations;
|
---|
131 | } VUSBDESCDEVICE;
|
---|
132 | /** Pointer to a USB device descriptor. */
|
---|
133 | typedef VUSBDESCDEVICE *PVUSBDESCDEVICE;
|
---|
134 | /** Pointer to a const USB device descriptor. */
|
---|
135 | typedef const VUSBDESCDEVICE *PCVUSBDESCDEVICE;
|
---|
136 |
|
---|
137 | /**
|
---|
138 | * USB device qualifier (from spec 9.6.2)
|
---|
139 | */
|
---|
140 | struct VUSBDEVICEQUALIFIER
|
---|
141 | {
|
---|
142 | uint8_t bLength;
|
---|
143 | uint8_t bDescriptorType;
|
---|
144 | uint16_t bcdUsb;
|
---|
145 | uint8_t bDeviceClass;
|
---|
146 | uint8_t bDeviceSubClass;
|
---|
147 | uint8_t bDeviceProtocol;
|
---|
148 | uint8_t bMaxPacketSize0;
|
---|
149 | uint8_t bNumConfigurations;
|
---|
150 | uint8_t bReserved;
|
---|
151 | };
|
---|
152 |
|
---|
153 | typedef struct VUSBDEVICEQUALIFIER VUSBDEVICEQUALIFIER;
|
---|
154 | typedef VUSBDEVICEQUALIFIER *PVUSBDEVICEQUALIFIER;
|
---|
155 |
|
---|
156 |
|
---|
157 | /**
|
---|
158 | * USB configuration descriptor (from spec).
|
---|
159 | */
|
---|
160 | typedef struct VUSBDESCCONFIG
|
---|
161 | {
|
---|
162 | uint8_t bLength;
|
---|
163 | uint8_t bDescriptorType;
|
---|
164 | uint16_t wTotalLength; /**< recalculated by VUSB when involved in URB. */
|
---|
165 | uint8_t bNumInterfaces;
|
---|
166 | uint8_t bConfigurationValue;
|
---|
167 | uint8_t iConfiguration;
|
---|
168 | uint8_t bmAttributes;
|
---|
169 | uint8_t MaxPower;
|
---|
170 | } VUSBDESCCONFIG;
|
---|
171 | /** Pointer to a USB configuration descriptor. */
|
---|
172 | typedef VUSBDESCCONFIG *PVUSBDESCCONFIG;
|
---|
173 | /** Pointer to a readonly USB configuration descriptor. */
|
---|
174 | typedef const VUSBDESCCONFIG *PCVUSBDESCCONFIG;
|
---|
175 |
|
---|
176 |
|
---|
177 | /**
|
---|
178 | * USB interface association descriptor (from USB ECN Interface Association Descriptors)
|
---|
179 | */
|
---|
180 | typedef struct VUSBDESCIAD
|
---|
181 | {
|
---|
182 | uint8_t bLength;
|
---|
183 | uint8_t bDescriptorType;
|
---|
184 | uint8_t bFirstInterface;
|
---|
185 | uint8_t bInterfaceCount;
|
---|
186 | uint8_t bFunctionClass;
|
---|
187 | uint8_t bFunctionSubClass;
|
---|
188 | uint8_t bFunctionProtocol;
|
---|
189 | uint8_t iFunction;
|
---|
190 | } VUSBDESCIAD;
|
---|
191 | /** Pointer to a USB interface association descriptor. */
|
---|
192 | typedef VUSBDESCIAD *PVUSBDESCIAD;
|
---|
193 | /** Pointer to a readonly USB interface association descriptor. */
|
---|
194 | typedef const VUSBDESCIAD *PCVUSBDESCIAD;
|
---|
195 |
|
---|
196 |
|
---|
197 | /**
|
---|
198 | * USB interface descriptor (from spec)
|
---|
199 | */
|
---|
200 | typedef struct VUSBDESCINTERFACE
|
---|
201 | {
|
---|
202 | uint8_t bLength;
|
---|
203 | uint8_t bDescriptorType;
|
---|
204 | uint8_t bInterfaceNumber;
|
---|
205 | uint8_t bAlternateSetting;
|
---|
206 | uint8_t bNumEndpoints;
|
---|
207 | uint8_t bInterfaceClass;
|
---|
208 | uint8_t bInterfaceSubClass;
|
---|
209 | uint8_t bInterfaceProtocol;
|
---|
210 | uint8_t iInterface;
|
---|
211 | } VUSBDESCINTERFACE;
|
---|
212 | /** Pointer to a USB interface descriptor. */
|
---|
213 | typedef VUSBDESCINTERFACE *PVUSBDESCINTERFACE;
|
---|
214 | /** Pointer to a const USB interface descriptor. */
|
---|
215 | typedef const VUSBDESCINTERFACE *PCVUSBDESCINTERFACE;
|
---|
216 |
|
---|
217 |
|
---|
218 | /**
|
---|
219 | * USB endpoint descriptor (from spec)
|
---|
220 | */
|
---|
221 | typedef struct VUSBDESCENDPOINT
|
---|
222 | {
|
---|
223 | uint8_t bLength;
|
---|
224 | uint8_t bDescriptorType;
|
---|
225 | uint8_t bEndpointAddress;
|
---|
226 | uint8_t bmAttributes;
|
---|
227 | uint16_t wMaxPacketSize;
|
---|
228 | uint8_t bInterval;
|
---|
229 | } VUSBDESCENDPOINT;
|
---|
230 | /** Pointer to a USB endpoint descriptor. */
|
---|
231 | typedef VUSBDESCENDPOINT *PVUSBDESCENDPOINT;
|
---|
232 | /** Pointer to a const USB endpoint descriptor. */
|
---|
233 | typedef const VUSBDESCENDPOINT *PCVUSBDESCENDPOINT;
|
---|
234 |
|
---|
235 |
|
---|
236 | /**
|
---|
237 | * USB SuperSpeed endpoint companion descriptor (from USB3 spec)
|
---|
238 | */
|
---|
239 | typedef struct VUSBDESCSSEPCOMPANION
|
---|
240 | {
|
---|
241 | uint8_t bLength;
|
---|
242 | uint8_t bDescriptorType;
|
---|
243 | uint8_t bMaxBurst;
|
---|
244 | uint8_t bmAttributes;
|
---|
245 | uint16_t wBytesPerInterval;
|
---|
246 | } VUSBDESCSSEPCOMPANION;
|
---|
247 | /** Pointer to a USB endpoint companion descriptor. */
|
---|
248 | typedef VUSBDESCSSEPCOMPANION *PVUSBDESCSSEPCOMPANION;
|
---|
249 | /** Pointer to a const USB endpoint companion descriptor. */
|
---|
250 | typedef const VUSBDESCSSEPCOMPANION *PCVUSBDESCSSEPCOMPANION;
|
---|
251 |
|
---|
252 |
|
---|
253 | /**
|
---|
254 | * USB Binary Device Object Store, aka BOS (from USB3 spec)
|
---|
255 | */
|
---|
256 | typedef struct VUSBDESCBOS
|
---|
257 | {
|
---|
258 | uint8_t bLength;
|
---|
259 | uint8_t bDescriptorType;
|
---|
260 | uint16_t wTotalLength;
|
---|
261 | uint8_t bNumDeviceCaps;
|
---|
262 | } VUSBDESCBOS;
|
---|
263 | /** Pointer to a USB BOS descriptor. */
|
---|
264 | typedef VUSBDESCBOS *PVUSBDESCBOS;
|
---|
265 | /** Pointer to a const USB BOS descriptor. */
|
---|
266 | typedef const VUSBDESCBOS *PCVUSBDESCBOS;
|
---|
267 |
|
---|
268 |
|
---|
269 | /**
|
---|
270 | * Generic USB Device Capability Descriptor within BOS (from USB3 spec)
|
---|
271 | */
|
---|
272 | typedef struct VUSBDESCDEVICECAP
|
---|
273 | {
|
---|
274 | uint8_t bLength;
|
---|
275 | uint8_t bDescriptorType;
|
---|
276 | uint8_t bDevCapabilityType;
|
---|
277 | uint8_t aCapSpecific[1];
|
---|
278 | } VUSBDESCDEVICECAP;
|
---|
279 | /** Pointer to a USB device capability descriptor. */
|
---|
280 | typedef VUSBDESCDEVICECAP *PVUSBDESCDEVICECAP;
|
---|
281 | /** Pointer to a const USB device capability descriptor. */
|
---|
282 | typedef const VUSBDESCDEVICECAP *PCVUSBDESCDEVICECAP;
|
---|
283 |
|
---|
284 |
|
---|
285 | /**
|
---|
286 | * SuperSpeed USB Device Capability Descriptor within BOS
|
---|
287 | */
|
---|
288 | typedef struct VUSBDESCSSDEVCAP
|
---|
289 | {
|
---|
290 | uint8_t bLength;
|
---|
291 | uint8_t bDescriptorType; /* DEVICE CAPABILITY */
|
---|
292 | uint8_t bDevCapabilityType; /* SUPERSPEED_USB */
|
---|
293 | uint8_t bmAttributes;
|
---|
294 | uint16_t wSpeedsSupported;
|
---|
295 | uint8_t bFunctionalitySupport;
|
---|
296 | uint8_t bU1DevExitLat;
|
---|
297 | uint16_t wU2DevExitLat;
|
---|
298 | } VUSBDESCSSDEVCAP;
|
---|
299 | /** Pointer to an SS USB device capability descriptor. */
|
---|
300 | typedef VUSBDESCSSDEVCAP *PVUSBDESCSSDEVCAP;
|
---|
301 | /** Pointer to a const SS USB device capability descriptor. */
|
---|
302 | typedef const VUSBDESCSSDEVCAP *PCVUSBDESCSSDEVCAP;
|
---|
303 |
|
---|
304 |
|
---|
305 | /**
|
---|
306 | * USB 2.0 Extension Descriptor within BOS
|
---|
307 | */
|
---|
308 | typedef struct VUSBDESCUSB2EXT
|
---|
309 | {
|
---|
310 | uint8_t bLength;
|
---|
311 | uint8_t bDescriptorType; /* DEVICE CAPABILITY */
|
---|
312 | uint8_t bDevCapabilityType; /* USB 2.0 EXTENSION */
|
---|
313 | uint8_t bmAttributes;
|
---|
314 | } VUSBDESCUSB2EXT;
|
---|
315 | /** Pointer to a USB 2.0 extension capability descriptor. */
|
---|
316 | typedef VUSBDESCUSB2EXT *PVUSBDESCUSB2EXT;
|
---|
317 | /** Pointer to a const USB 2.0 extension capability descriptor. */
|
---|
318 | typedef const VUSBDESCUSB2EXT *PCVUSBDESCUSB2EXT;
|
---|
319 |
|
---|
320 |
|
---|
321 | #pragma pack() /* end of the byte packing. */
|
---|
322 |
|
---|
323 |
|
---|
324 | /**
|
---|
325 | * USB configuration descriptor, the parsed variant used by VUSB.
|
---|
326 | */
|
---|
327 | typedef struct VUSBDESCCONFIGEX
|
---|
328 | {
|
---|
329 | /** The USB descriptor data.
|
---|
330 | * @remark The wTotalLength member is recalculated before the data is passed to the guest. */
|
---|
331 | VUSBDESCCONFIG Core;
|
---|
332 | /** Pointer to additional descriptor bytes following what's covered by VUSBDESCCONFIG. */
|
---|
333 | void *pvMore;
|
---|
334 | /** Pointer to an array of the interfaces referenced in the configuration.
|
---|
335 | * Core.bNumInterfaces in size. */
|
---|
336 | const struct VUSBINTERFACE *paIfs;
|
---|
337 | /** Pointer to the original descriptor data read from the device. */
|
---|
338 | const void *pvOriginal;
|
---|
339 | } VUSBDESCCONFIGEX;
|
---|
340 | /** Pointer to a parsed USB configuration descriptor. */
|
---|
341 | typedef VUSBDESCCONFIGEX *PVUSBDESCCONFIGEX;
|
---|
342 | /** Pointer to a const parsed USB configuration descriptor. */
|
---|
343 | typedef const VUSBDESCCONFIGEX *PCVUSBDESCCONFIGEX;
|
---|
344 |
|
---|
345 |
|
---|
346 | /**
|
---|
347 | * For tracking the alternate interface settings of a configuration.
|
---|
348 | */
|
---|
349 | typedef struct VUSBINTERFACE
|
---|
350 | {
|
---|
351 | /** Pointer to an array of interfaces. */
|
---|
352 | const struct VUSBDESCINTERFACEEX *paSettings;
|
---|
353 | /** The number of entries in the array. */
|
---|
354 | uint32_t cSettings;
|
---|
355 | } VUSBINTERFACE;
|
---|
356 | /** Pointer to a VUSBINTERFACE. */
|
---|
357 | typedef VUSBINTERFACE *PVUSBINTERFACE;
|
---|
358 | /** Pointer to a const VUSBINTERFACE. */
|
---|
359 | typedef const VUSBINTERFACE *PCVUSBINTERFACE;
|
---|
360 |
|
---|
361 |
|
---|
362 | /**
|
---|
363 | * USB interface descriptor, the parsed variant used by VUSB.
|
---|
364 | */
|
---|
365 | typedef struct VUSBDESCINTERFACEEX
|
---|
366 | {
|
---|
367 | /** The USB descriptor data. */
|
---|
368 | VUSBDESCINTERFACE Core;
|
---|
369 | /** Pointer to additional descriptor bytes following what's covered by VUSBDESCINTERFACE. */
|
---|
370 | const void *pvMore;
|
---|
371 | /** Pointer to additional class- or vendor-specific interface descriptors. */
|
---|
372 | const void *pvClass;
|
---|
373 | /** Size of class- or vendor-specific descriptors. */
|
---|
374 | uint16_t cbClass;
|
---|
375 | /** Pointer to an array of the endpoints referenced by the interface.
|
---|
376 | * Core.bNumEndpoints in size. */
|
---|
377 | const struct VUSBDESCENDPOINTEX *paEndpoints;
|
---|
378 | /** Interface association descriptor, which prepends a group of interfaces,
|
---|
379 | * starting with this interface. */
|
---|
380 | PCVUSBDESCIAD pIAD;
|
---|
381 | /** Size of interface association descriptor. */
|
---|
382 | uint16_t cbIAD;
|
---|
383 | } VUSBDESCINTERFACEEX;
|
---|
384 | /** Pointer to an prased USB interface descriptor. */
|
---|
385 | typedef VUSBDESCINTERFACEEX *PVUSBDESCINTERFACEEX;
|
---|
386 | /** Pointer to a const parsed USB interface descriptor. */
|
---|
387 | typedef const VUSBDESCINTERFACEEX *PCVUSBDESCINTERFACEEX;
|
---|
388 |
|
---|
389 |
|
---|
390 | /**
|
---|
391 | * USB endpoint descriptor, the parsed variant used by VUSB.
|
---|
392 | */
|
---|
393 | typedef struct VUSBDESCENDPOINTEX
|
---|
394 | {
|
---|
395 | /** The USB descriptor data.
|
---|
396 | * @remark The wMaxPacketSize member is converted to native endian. */
|
---|
397 | VUSBDESCENDPOINT Core;
|
---|
398 | /** Pointer to additional descriptor bytes following what's covered by VUSBDESCENDPOINT. */
|
---|
399 | const void *pvMore;
|
---|
400 | /** Pointer to additional class- or vendor-specific endpoint descriptors. */
|
---|
401 | const void *pvClass;
|
---|
402 | /** Size of class- or vendor-specific descriptors. */
|
---|
403 | uint16_t cbClass;
|
---|
404 | /** Pointer to SuperSpeed endpoint companion descriptor (SS endpoints only). */
|
---|
405 | const void *pvSsepc;
|
---|
406 | /** Size of SuperSpeed endpoint companion descriptor.
|
---|
407 | * @remark Must be non-zero for SuperSpeed endpoints. */
|
---|
408 | uint16_t cbSsepc;
|
---|
409 | } VUSBDESCENDPOINTEX;
|
---|
410 | /** Pointer to a parsed USB endpoint descriptor. */
|
---|
411 | typedef VUSBDESCENDPOINTEX *PVUSBDESCENDPOINTEX;
|
---|
412 | /** Pointer to a const parsed USB endpoint descriptor. */
|
---|
413 | typedef const VUSBDESCENDPOINTEX *PCVUSBDESCENDPOINTEX;
|
---|
414 |
|
---|
415 |
|
---|
416 | /** @name USB Control message recipient codes (from spec)
|
---|
417 | * @{ */
|
---|
418 | #define VUSB_TO_DEVICE 0x0
|
---|
419 | #define VUSB_TO_INTERFACE 0x1
|
---|
420 | #define VUSB_TO_ENDPOINT 0x2
|
---|
421 | #define VUSB_TO_OTHER 0x3
|
---|
422 | #define VUSB_RECIP_MASK 0x1f
|
---|
423 | /** @} */
|
---|
424 |
|
---|
425 | /** @name USB control pipe setup packet structure (from spec)
|
---|
426 | * @{ */
|
---|
427 | #define VUSB_REQ_SHIFT (5)
|
---|
428 | #define VUSB_REQ_STANDARD (0x0 << VUSB_REQ_SHIFT)
|
---|
429 | #define VUSB_REQ_CLASS (0x1 << VUSB_REQ_SHIFT)
|
---|
430 | #define VUSB_REQ_VENDOR (0x2 << VUSB_REQ_SHIFT)
|
---|
431 | #define VUSB_REQ_RESERVED (0x3 << VUSB_REQ_SHIFT)
|
---|
432 | #define VUSB_REQ_MASK (0x3 << VUSB_REQ_SHIFT)
|
---|
433 | /** @} */
|
---|
434 |
|
---|
435 | #define VUSB_DIR_TO_DEVICE 0x00
|
---|
436 | #define VUSB_DIR_TO_HOST 0x80
|
---|
437 | #define VUSB_DIR_MASK 0x80
|
---|
438 |
|
---|
439 | /**
|
---|
440 | * USB Setup request (from spec)
|
---|
441 | */
|
---|
442 | typedef struct vusb_setup
|
---|
443 | {
|
---|
444 | uint8_t bmRequestType;
|
---|
445 | uint8_t bRequest;
|
---|
446 | uint16_t wValue;
|
---|
447 | uint16_t wIndex;
|
---|
448 | uint16_t wLength;
|
---|
449 | } VUSBSETUP;
|
---|
450 | /** Pointer to a setup request. */
|
---|
451 | typedef VUSBSETUP *PVUSBSETUP;
|
---|
452 | /** Pointer to a const setup request. */
|
---|
453 | typedef const VUSBSETUP *PCVUSBSETUP;
|
---|
454 |
|
---|
455 | /** @name USB Standard device requests (from spec)
|
---|
456 | * @{ */
|
---|
457 | #define VUSB_REQ_GET_STATUS 0x00
|
---|
458 | #define VUSB_REQ_CLEAR_FEATURE 0x01
|
---|
459 | #define VUSB_REQ_SET_FEATURE 0x03
|
---|
460 | #define VUSB_REQ_SET_ADDRESS 0x05
|
---|
461 | #define VUSB_REQ_GET_DESCRIPTOR 0x06
|
---|
462 | #define VUSB_REQ_SET_DESCRIPTOR 0x07
|
---|
463 | #define VUSB_REQ_GET_CONFIGURATION 0x08
|
---|
464 | #define VUSB_REQ_SET_CONFIGURATION 0x09
|
---|
465 | #define VUSB_REQ_GET_INTERFACE 0x0a
|
---|
466 | #define VUSB_REQ_SET_INTERFACE 0x0b
|
---|
467 | #define VUSB_REQ_SYNCH_FRAME 0x0c
|
---|
468 | #define VUSB_REQ_MAX 0x0d
|
---|
469 | /** @} */
|
---|
470 |
|
---|
471 | /** @} */ /* end of grp_vusb_std */
|
---|
472 |
|
---|
473 |
|
---|
474 |
|
---|
475 | /** @name USB Standard version flags.
|
---|
476 | * @{ */
|
---|
477 | /** Indicates USB 1.1 support. */
|
---|
478 | #define VUSB_STDVER_11 RT_BIT(1)
|
---|
479 | /** Indicates USB 2.0 support. */
|
---|
480 | #define VUSB_STDVER_20 RT_BIT(2)
|
---|
481 | /** Indicates USB 3.0 support. */
|
---|
482 | #define VUSB_STDVER_30 RT_BIT(3)
|
---|
483 | /** @} */
|
---|
484 |
|
---|
485 | /**
|
---|
486 | * USB port/device speeds.
|
---|
487 | */
|
---|
488 | typedef enum VUSBSPEED
|
---|
489 | {
|
---|
490 | /** Undetermined/unknown speed. */
|
---|
491 | VUSB_SPEED_UNKNOWN = 0,
|
---|
492 | /** Low-speed (LS), 1.5 Mbit/s, USB 1.0. */
|
---|
493 | VUSB_SPEED_LOW,
|
---|
494 | /** Full-speed (FS), 12 Mbit/s, USB 1.1. */
|
---|
495 | VUSB_SPEED_FULL,
|
---|
496 | /** High-speed (HS), 480 Mbit/s, USB 2.0. */
|
---|
497 | VUSB_SPEED_HIGH,
|
---|
498 | /** Variable speed, wireless USB 2.5. */
|
---|
499 | VUSB_SPEED_VARIABLE,
|
---|
500 | /** SuperSpeed (SS), 5.0 Gbit/s, USB 3.0. */
|
---|
501 | VUSB_SPEED_SUPER,
|
---|
502 | /** SuperSpeed+ (SS+), 10.0 Gbit/s, USB 3.1. */
|
---|
503 | VUSB_SPEED_SUPERPLUS,
|
---|
504 | /** The usual 32-bit hack. */
|
---|
505 | VUSB_SPEED_32BIT_HACK = 0x7fffffff
|
---|
506 | } VUSBSPEED;
|
---|
507 |
|
---|
508 | /**
|
---|
509 | * VUSB transfer direction.
|
---|
510 | */
|
---|
511 | typedef enum VUSBDIRECTION
|
---|
512 | {
|
---|
513 | /** Setup */
|
---|
514 | VUSBDIRECTION_SETUP = 0,
|
---|
515 | #define VUSB_DIRECTION_SETUP VUSBDIRECTION_SETUP
|
---|
516 | /** In - Device to host. */
|
---|
517 | VUSBDIRECTION_IN = 1,
|
---|
518 | #define VUSB_DIRECTION_IN VUSBDIRECTION_IN
|
---|
519 | /** Out - Host to device. */
|
---|
520 | VUSBDIRECTION_OUT = 2,
|
---|
521 | #define VUSB_DIRECTION_OUT VUSBDIRECTION_OUT
|
---|
522 | /** Invalid direction */
|
---|
523 | VUSBDIRECTION_INVALID = 0x7f
|
---|
524 | } VUSBDIRECTION;
|
---|
525 |
|
---|
526 |
|
---|
527 | /** Pointer to a VBox USB device interface. */
|
---|
528 | typedef struct VUSBIDEVICE *PVUSBIDEVICE;
|
---|
529 |
|
---|
530 | /** Pointer to a VUSB RootHub port interface. */
|
---|
531 | typedef struct VUSBIROOTHUBPORT *PVUSBIROOTHUBPORT;
|
---|
532 |
|
---|
533 | /** Pointer to an USB request descriptor. */
|
---|
534 | typedef struct VUSBURB *PVUSBURB;
|
---|
535 |
|
---|
536 |
|
---|
537 |
|
---|
538 | /**
|
---|
539 | * VBox USB port bitmap.
|
---|
540 | *
|
---|
541 | * Bit 0 == Port 0, ... , Bit 127 == Port 127.
|
---|
542 | */
|
---|
543 | typedef struct VUSBPORTBITMAP
|
---|
544 | {
|
---|
545 | /** 128 bits */
|
---|
546 | char ach[16];
|
---|
547 | } VUSBPORTBITMAP;
|
---|
548 | /** Pointer to a VBox USB port bitmap. */
|
---|
549 | typedef VUSBPORTBITMAP *PVUSBPORTBITMAP;
|
---|
550 |
|
---|
551 | #ifndef RDESKTOP
|
---|
552 |
|
---|
553 | /**
|
---|
554 | * The VUSB RootHub port interface provided by the HCI (down).
|
---|
555 | * Pair with VUSBIROOTCONNECTOR
|
---|
556 | */
|
---|
557 | typedef struct VUSBIROOTHUBPORT
|
---|
558 | {
|
---|
559 | /**
|
---|
560 | * Get the number of available ports in the hub.
|
---|
561 | *
|
---|
562 | * @returns The number of ports available.
|
---|
563 | * @param pInterface Pointer to this structure.
|
---|
564 | * @param pAvailable Bitmap indicating the available ports. Set bit == available port.
|
---|
565 | */
|
---|
566 | DECLR3CALLBACKMEMBER(unsigned, pfnGetAvailablePorts,(PVUSBIROOTHUBPORT pInterface, PVUSBPORTBITMAP pAvailable));
|
---|
567 |
|
---|
568 | /**
|
---|
569 | * Gets the supported USB versions.
|
---|
570 | *
|
---|
571 | * @returns The mask of supported USB versions.
|
---|
572 | * @param pInterface Pointer to this structure.
|
---|
573 | */
|
---|
574 | DECLR3CALLBACKMEMBER(uint32_t, pfnGetUSBVersions,(PVUSBIROOTHUBPORT pInterface));
|
---|
575 |
|
---|
576 | /**
|
---|
577 | * A device is being attached to a port in the roothub.
|
---|
578 | *
|
---|
579 | * @param pInterface Pointer to this structure.
|
---|
580 | * @param pDev Pointer to the device being attached.
|
---|
581 | * @param uPort The port number assigned to the device.
|
---|
582 | */
|
---|
583 | DECLR3CALLBACKMEMBER(int, pfnAttach,(PVUSBIROOTHUBPORT pInterface, PVUSBIDEVICE pDev, unsigned uPort));
|
---|
584 |
|
---|
585 | /**
|
---|
586 | * A device is being detached from a port in the roothub.
|
---|
587 | *
|
---|
588 | * @param pInterface Pointer to this structure.
|
---|
589 | * @param pDev Pointer to the device being detached.
|
---|
590 | * @param uPort The port number assigned to the device.
|
---|
591 | */
|
---|
592 | DECLR3CALLBACKMEMBER(void, pfnDetach,(PVUSBIROOTHUBPORT pInterface, PVUSBIDEVICE pDev, unsigned uPort));
|
---|
593 |
|
---|
594 | /**
|
---|
595 | * Reset the root hub.
|
---|
596 | *
|
---|
597 | * @returns VBox status code.
|
---|
598 | * @param pInterface Pointer to this structure.
|
---|
599 | * @param pResetOnLinux Whether or not to do real reset on linux.
|
---|
600 | */
|
---|
601 | DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIROOTHUBPORT pInterface, bool fResetOnLinux));
|
---|
602 |
|
---|
603 | /**
|
---|
604 | * Transfer completion callback routine.
|
---|
605 | *
|
---|
606 | * VUSB will call this when a transfer have been completed
|
---|
607 | * in a one or another way.
|
---|
608 | *
|
---|
609 | * @param pInterface Pointer to this structure.
|
---|
610 | * @param pUrb Pointer to the URB in question.
|
---|
611 | */
|
---|
612 | DECLR3CALLBACKMEMBER(void, pfnXferCompletion,(PVUSBIROOTHUBPORT pInterface, PVUSBURB urb));
|
---|
613 |
|
---|
614 | /**
|
---|
615 | * Handle transfer errors.
|
---|
616 | *
|
---|
617 | * VUSB calls this when a transfer attempt failed. This function will respond
|
---|
618 | * indicating whether to retry or complete the URB with failure.
|
---|
619 | *
|
---|
620 | * @returns Retry indicator.
|
---|
621 | * @param pInterface Pointer to this structure.
|
---|
622 | * @param pUrb Pointer to the URB in question.
|
---|
623 | */
|
---|
624 | DECLR3CALLBACKMEMBER(bool, pfnXferError,(PVUSBIROOTHUBPORT pInterface, PVUSBURB pUrb));
|
---|
625 |
|
---|
626 | /** Alignment dummy. */
|
---|
627 | RTR3PTR Alignment;
|
---|
628 |
|
---|
629 | } VUSBIROOTHUBPORT;
|
---|
630 | /** VUSBIROOTHUBPORT interface ID. */
|
---|
631 | #define VUSBIROOTHUBPORT_IID "e38e2978-7aa2-4860-94b6-9ef4a066d8a0"
|
---|
632 |
|
---|
633 | /** Pointer to a VUSB RootHub connector interface. */
|
---|
634 | typedef struct VUSBIROOTHUBCONNECTOR *PVUSBIROOTHUBCONNECTOR;
|
---|
635 | /**
|
---|
636 | * The VUSB RootHub connector interface provided by the VBox USB RootHub driver
|
---|
637 | * (up).
|
---|
638 | * Pair with VUSBIROOTHUBPORT.
|
---|
639 | */
|
---|
640 | typedef struct VUSBIROOTHUBCONNECTOR
|
---|
641 | {
|
---|
642 | /**
|
---|
643 | * Allocates a new URB for a transfer.
|
---|
644 | *
|
---|
645 | * Either submit using pfnSubmitUrb or free using VUSBUrbFree().
|
---|
646 | *
|
---|
647 | * @returns Pointer to a new URB.
|
---|
648 | * @returns NULL on failure - try again later.
|
---|
649 | * This will not fail if the device wasn't found. We'll fail it
|
---|
650 | * at submit time, since that makes the usage of this api simpler.
|
---|
651 | * @param pInterface Pointer to this struct.
|
---|
652 | * @param DstAddress The destination address of the URB.
|
---|
653 | * @param cbData The amount of data space required.
|
---|
654 | * @param cTds The amount of TD space.
|
---|
655 | */
|
---|
656 | DECLR3CALLBACKMEMBER(PVUSBURB, pfnNewUrb,(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t cbData, uint32_t cTds));
|
---|
657 |
|
---|
658 | /**
|
---|
659 | * Submits a URB for transfer.
|
---|
660 | * The transfer will do asynchronously if possible.
|
---|
661 | *
|
---|
662 | * @returns VBox status code.
|
---|
663 | * @param pInterface Pointer to this struct.
|
---|
664 | * @param pUrb Pointer to the URB returned by pfnNewUrb.
|
---|
665 | * The URB will be freed in case of failure.
|
---|
666 | * @param pLed Pointer to USB Status LED
|
---|
667 | */
|
---|
668 | DECLR3CALLBACKMEMBER(int, pfnSubmitUrb,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed));
|
---|
669 |
|
---|
670 | /**
|
---|
671 | * Call to service asynchronous URB completions in a polling fashion.
|
---|
672 | *
|
---|
673 | * Reaped URBs will be finished by calling the completion callback,
|
---|
674 | * thus there is no return code or input or anything from this function
|
---|
675 | * except for potential state changes elsewhere.
|
---|
676 | *
|
---|
677 | * @returns VINF_SUCCESS if no URBs are pending upon return.
|
---|
678 | * @returns VERR_TIMEOUT if one or more URBs are still in flight upon returning.
|
---|
679 | * @returns Other VBox status code.
|
---|
680 | *
|
---|
681 | * @param pInterface Pointer to this struct.
|
---|
682 | * @param pDevice Pointer to a USB device.
|
---|
683 | * @param cMillies Number of milliseconds to poll for completion.
|
---|
684 | */
|
---|
685 | DECLR3CALLBACKMEMBER(void, pfnReapAsyncUrbs,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice, RTMSINTERVAL cMillies));
|
---|
686 |
|
---|
687 | /**
|
---|
688 | * Cancels and completes - with CRC failure - all URBs queued on an endpoint.
|
---|
689 | * This is done in response to guest URB cancellation.
|
---|
690 | *
|
---|
691 | * @returns VBox status code.
|
---|
692 | * @param pInterface Pointer to this struct.
|
---|
693 | * @param pUrb Pointer to a previously submitted URB.
|
---|
694 | */
|
---|
695 | DECLR3CALLBACKMEMBER(int, pfnCancelUrbsEp,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb));
|
---|
696 |
|
---|
697 | /**
|
---|
698 | * Cancels and completes - with CRC failure - all in-flight async URBs.
|
---|
699 | * This is typically done before saving a state.
|
---|
700 | *
|
---|
701 | * @param pInterface Pointer to this struct.
|
---|
702 | */
|
---|
703 | DECLR3CALLBACKMEMBER(void, pfnCancelAllUrbs,(PVUSBIROOTHUBCONNECTOR pInterface));
|
---|
704 |
|
---|
705 | /**
|
---|
706 | * Cancels and completes - with CRC failure - all URBs queued on an endpoint.
|
---|
707 | * This is done in response to a guest endpoint/pipe abort.
|
---|
708 | *
|
---|
709 | * @returns VBox status code.
|
---|
710 | * @param pInterface Pointer to this struct.
|
---|
711 | * @param pDevice Pointer to a USB device.
|
---|
712 | * @param EndPt Endpoint number.
|
---|
713 | * @param enmDir Endpoint direction.
|
---|
714 | */
|
---|
715 | DECLR3CALLBACKMEMBER(int, pfnAbortEp,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice, int EndPt, VUSBDIRECTION enmDir));
|
---|
716 |
|
---|
717 | /**
|
---|
718 | * Attach the device to the root hub.
|
---|
719 | * The device must not be attached to any hub for this call to succeed.
|
---|
720 | *
|
---|
721 | * @returns VBox status code.
|
---|
722 | * @param pInterface Pointer to this struct.
|
---|
723 | * @param pDevice Pointer to the device (interface) to attach.
|
---|
724 | */
|
---|
725 | DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice));
|
---|
726 |
|
---|
727 | /**
|
---|
728 | * Detach the device from the root hub.
|
---|
729 | * The device must already be attached for this call to succeed.
|
---|
730 | *
|
---|
731 | * @returns VBox status code.
|
---|
732 | * @param pInterface Pointer to this struct.
|
---|
733 | * @param pDevice Pointer to the device (interface) to detach.
|
---|
734 | */
|
---|
735 | DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice));
|
---|
736 |
|
---|
737 | /** Alignment dummy. */
|
---|
738 | RTR3PTR Alignment;
|
---|
739 |
|
---|
740 | } VUSBIROOTHUBCONNECTOR;
|
---|
741 | /** VUSBIROOTHUBCONNECTOR interface ID. */
|
---|
742 | #define VUSBIROOTHUBCONNECTOR_IID "d9a90c59-e3ff-4dff-9754-844557c3f7a1"
|
---|
743 |
|
---|
744 |
|
---|
745 | #ifdef IN_RING3
|
---|
746 | /** @copydoc VUSBIROOTHUBCONNECTOR::pfnNewUrb */
|
---|
747 | DECLINLINE(PVUSBURB) VUSBIRhNewUrb(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t DstAddress, uint32_t cbData, uint32_t cTds)
|
---|
748 | {
|
---|
749 | return pInterface->pfnNewUrb(pInterface, DstAddress, cbData, cTds);
|
---|
750 | }
|
---|
751 |
|
---|
752 | /** @copydoc VUSBIROOTHUBCONNECTOR::pfnSubmitUrb */
|
---|
753 | DECLINLINE(int) VUSBIRhSubmitUrb(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed)
|
---|
754 | {
|
---|
755 | return pInterface->pfnSubmitUrb(pInterface, pUrb, pLed);
|
---|
756 | }
|
---|
757 |
|
---|
758 | /** @copydoc VUSBIROOTHUBCONNECTOR::pfnReapAsyncUrbs */
|
---|
759 | DECLINLINE(void) VUSBIRhReapAsyncUrbs(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice, RTMSINTERVAL cMillies)
|
---|
760 | {
|
---|
761 | pInterface->pfnReapAsyncUrbs(pInterface, pDevice, cMillies);
|
---|
762 | }
|
---|
763 |
|
---|
764 | /** @copydoc VUSBIROOTHUBCONNECTOR::pfnCancelAllUrbs */
|
---|
765 | DECLINLINE(void) VUSBIRhCancelAllUrbs(PVUSBIROOTHUBCONNECTOR pInterface)
|
---|
766 | {
|
---|
767 | pInterface->pfnCancelAllUrbs(pInterface);
|
---|
768 | }
|
---|
769 |
|
---|
770 | /** @copydoc VUSBIROOTHUBCONNECTOR::pfnAttachDevice */
|
---|
771 | DECLINLINE(int) VUSBIRhAttachDevice(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice)
|
---|
772 | {
|
---|
773 | return pInterface->pfnAttachDevice(pInterface, pDevice);
|
---|
774 | }
|
---|
775 |
|
---|
776 | /** @copydoc VUSBIROOTHUBCONNECTOR::pfnDetachDevice */
|
---|
777 | DECLINLINE(int) VUSBIRhDetachDevice(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice)
|
---|
778 | {
|
---|
779 | return pInterface->pfnDetachDevice(pInterface, pDevice);
|
---|
780 | }
|
---|
781 | #endif /* IN_RING3 */
|
---|
782 |
|
---|
783 | #endif /* ! RDESKTOP */
|
---|
784 |
|
---|
785 |
|
---|
786 | /**
|
---|
787 | * VUSB device reset completion callback function.
|
---|
788 | * This is called by the reset thread when the reset has been completed.
|
---|
789 | *
|
---|
790 | * @param pDev Pointer to the virtual USB device core.
|
---|
791 | * @param rc The VBox status code of the reset operation.
|
---|
792 | * @param pvUser User specific argument.
|
---|
793 | *
|
---|
794 | * @thread The reset thread or EMT.
|
---|
795 | */
|
---|
796 | typedef DECLCALLBACK(void) FNVUSBRESETDONE(PVUSBIDEVICE pDevice, int rc, void *pvUser);
|
---|
797 | /** Pointer to a device reset completion callback function (FNUSBRESETDONE). */
|
---|
798 | typedef FNVUSBRESETDONE *PFNVUSBRESETDONE;
|
---|
799 |
|
---|
800 | /**
|
---|
801 | * The state of a VUSB Device.
|
---|
802 | *
|
---|
803 | * @remark The order of these states is vital.
|
---|
804 | */
|
---|
805 | typedef enum VUSBDEVICESTATE
|
---|
806 | {
|
---|
807 | VUSB_DEVICE_STATE_INVALID = 0,
|
---|
808 | VUSB_DEVICE_STATE_DETACHED,
|
---|
809 | VUSB_DEVICE_STATE_ATTACHED,
|
---|
810 | VUSB_DEVICE_STATE_POWERED,
|
---|
811 | VUSB_DEVICE_STATE_DEFAULT,
|
---|
812 | VUSB_DEVICE_STATE_ADDRESS,
|
---|
813 | VUSB_DEVICE_STATE_CONFIGURED,
|
---|
814 | VUSB_DEVICE_STATE_SUSPENDED,
|
---|
815 | /** The device is being reset. Don't mess with it.
|
---|
816 | * Next states: VUSB_DEVICE_STATE_DEFAULT, VUSB_DEVICE_STATE_DESTROYED
|
---|
817 | */
|
---|
818 | VUSB_DEVICE_STATE_RESET,
|
---|
819 | /** The device has been destroyed. */
|
---|
820 | VUSB_DEVICE_STATE_DESTROYED,
|
---|
821 | /** The usual 32-bit hack. */
|
---|
822 | VUSB_DEVICE_STATE_32BIT_HACK = 0x7fffffff
|
---|
823 | } VUSBDEVICESTATE;
|
---|
824 |
|
---|
825 | #ifndef RDESKTOP
|
---|
826 |
|
---|
827 | /**
|
---|
828 | * USB Device Interface (up).
|
---|
829 | * No interface pair.
|
---|
830 | */
|
---|
831 | typedef struct VUSBIDEVICE
|
---|
832 | {
|
---|
833 | /**
|
---|
834 | * Resets the device.
|
---|
835 | *
|
---|
836 | * Since a device reset shall take at least 10ms from the guest point of view,
|
---|
837 | * it must be performed asynchronously. We create a thread which performs this
|
---|
838 | * operation and ensures it will take at least 10ms.
|
---|
839 | *
|
---|
840 | * At times - like init - a synchronous reset is required, this can be done
|
---|
841 | * by passing NULL for pfnDone.
|
---|
842 | *
|
---|
843 | * -- internal stuff, move it --
|
---|
844 | * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
|
---|
845 | * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
|
---|
846 | * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
|
---|
847 | * -- internal stuff, move it --
|
---|
848 | *
|
---|
849 | * @returns VBox status code.
|
---|
850 | * @param pInterface Pointer to this structure.
|
---|
851 | * @param fResetOnLinux Set if we can permit a real reset and a potential logical
|
---|
852 | * device reconnect on linux hosts.
|
---|
853 | * @param pfnDone Pointer to the completion routine. If NULL a synchronous
|
---|
854 | * reset is preformed not respecting the 10ms.
|
---|
855 | * @param pvUser User argument to the completion routine.
|
---|
856 | * @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
|
---|
857 | */
|
---|
858 | DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIDEVICE pInterface, bool fResetOnLinux,
|
---|
859 | PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM));
|
---|
860 |
|
---|
861 | /**
|
---|
862 | * Powers on the device.
|
---|
863 | *
|
---|
864 | * @returns VBox status code.
|
---|
865 | * @param pInterface Pointer to the device interface structure.
|
---|
866 | */
|
---|
867 | DECLR3CALLBACKMEMBER(int, pfnPowerOn,(PVUSBIDEVICE pInterface));
|
---|
868 |
|
---|
869 | /**
|
---|
870 | * Powers off the device.
|
---|
871 | *
|
---|
872 | * @returns VBox status code.
|
---|
873 | * @param pInterface Pointer to the device interface structure.
|
---|
874 | */
|
---|
875 | DECLR3CALLBACKMEMBER(int, pfnPowerOff,(PVUSBIDEVICE pInterface));
|
---|
876 |
|
---|
877 | /**
|
---|
878 | * Get the state of the device.
|
---|
879 | *
|
---|
880 | * @returns Device state.
|
---|
881 | * @param pInterface Pointer to the device interface structure.
|
---|
882 | */
|
---|
883 | DECLR3CALLBACKMEMBER(VUSBDEVICESTATE, pfnGetState,(PVUSBIDEVICE pInterface));
|
---|
884 |
|
---|
885 | /**
|
---|
886 | * Returns whether the device implements the saved state handlers
|
---|
887 | * and doesn't need to get detached.
|
---|
888 | *
|
---|
889 | * @returns true if the device supports saving the state, false otherwise.
|
---|
890 | * @param pInterface Pointer to the device interface structure.
|
---|
891 | */
|
---|
892 | DECLR3CALLBACKMEMBER(bool, pfnIsSavedStateSupported,(PVUSBIDEVICE pInterface));
|
---|
893 |
|
---|
894 | /**
|
---|
895 | * Get the speed the device is operating at.
|
---|
896 | *
|
---|
897 | * @returns Device state.
|
---|
898 | * @param pInterface Pointer to the device interface structure.
|
---|
899 | */
|
---|
900 | DECLR3CALLBACKMEMBER(VUSBSPEED, pfnGetSpeed,(PVUSBIDEVICE pInterface));
|
---|
901 |
|
---|
902 | } VUSBIDEVICE;
|
---|
903 | /** VUSBIDEVICE interface ID. */
|
---|
904 | #define VUSBIDEVICE_IID "f3facb2b-edd3-4b5b-b07e-2cc4d52a471e"
|
---|
905 |
|
---|
906 |
|
---|
907 | #ifdef IN_RING3
|
---|
908 | /**
|
---|
909 | * Resets the device.
|
---|
910 | *
|
---|
911 | * Since a device reset shall take at least 10ms from the guest point of view,
|
---|
912 | * it must be performed asynchronously. We create a thread which performs this
|
---|
913 | * operation and ensures it will take at least 10ms.
|
---|
914 | *
|
---|
915 | * At times - like init - a synchronous reset is required, this can be done
|
---|
916 | * by passing NULL for pfnDone.
|
---|
917 | *
|
---|
918 | * -- internal stuff, move it --
|
---|
919 | * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
|
---|
920 | * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
|
---|
921 | * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
|
---|
922 | * -- internal stuff, move it --
|
---|
923 | *
|
---|
924 | * @returns VBox status code.
|
---|
925 | * @param pInterface Pointer to the device interface structure.
|
---|
926 | * @param fResetOnLinux Set if we can permit a real reset and a potential logical
|
---|
927 | * device reconnect on linux hosts.
|
---|
928 | * @param pfnDone Pointer to the completion routine. If NULL a synchronous
|
---|
929 | * reset is preformed not respecting the 10ms.
|
---|
930 | * @param pvUser User argument to the completion routine.
|
---|
931 | * @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
|
---|
932 | */
|
---|
933 | DECLINLINE(int) VUSBIDevReset(PVUSBIDEVICE pInterface, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
|
---|
934 | {
|
---|
935 | return pInterface->pfnReset(pInterface, fResetOnLinux, pfnDone, pvUser, pVM);
|
---|
936 | }
|
---|
937 |
|
---|
938 | /**
|
---|
939 | * Powers on the device.
|
---|
940 | *
|
---|
941 | * @returns VBox status code.
|
---|
942 | * @param pInterface Pointer to the device interface structure.
|
---|
943 | */
|
---|
944 | DECLINLINE(int) VUSBIDevPowerOn(PVUSBIDEVICE pInterface)
|
---|
945 | {
|
---|
946 | return pInterface->pfnPowerOn(pInterface);
|
---|
947 | }
|
---|
948 |
|
---|
949 | /**
|
---|
950 | * Powers off the device.
|
---|
951 | *
|
---|
952 | * @returns VBox status code.
|
---|
953 | * @param pInterface Pointer to the device interface structure.
|
---|
954 | */
|
---|
955 | DECLINLINE(int) VUSBIDevPowerOff(PVUSBIDEVICE pInterface)
|
---|
956 | {
|
---|
957 | return pInterface->pfnPowerOff(pInterface);
|
---|
958 | }
|
---|
959 |
|
---|
960 | /**
|
---|
961 | * Get the state of the device.
|
---|
962 | *
|
---|
963 | * @returns Device state.
|
---|
964 | * @param pInterface Pointer to the device interface structure.
|
---|
965 | */
|
---|
966 | DECLINLINE(VUSBDEVICESTATE) VUSBIDevGetState(PVUSBIDEVICE pInterface)
|
---|
967 | {
|
---|
968 | return pInterface->pfnGetState(pInterface);
|
---|
969 | }
|
---|
970 |
|
---|
971 | /**
|
---|
972 | * @copydoc VUSBIDEVICE::pfnIsSavedStateSupported
|
---|
973 | */
|
---|
974 | DECLINLINE(bool) VUSBIDevIsSavedStateSupported(PVUSBIDEVICE pInterface)
|
---|
975 | {
|
---|
976 | return pInterface->pfnIsSavedStateSupported(pInterface);
|
---|
977 | }
|
---|
978 | #endif /* IN_RING3 */
|
---|
979 |
|
---|
980 | #endif /* ! RDESKTOP */
|
---|
981 |
|
---|
982 | /** @name URB
|
---|
983 | * @{ */
|
---|
984 |
|
---|
985 | /**
|
---|
986 | * VUSB Transfer status codes.
|
---|
987 | */
|
---|
988 | typedef enum VUSBSTATUS
|
---|
989 | {
|
---|
990 | /** Transer was ok. */
|
---|
991 | VUSBSTATUS_OK = 0,
|
---|
992 | /** Transfer stalled, endpoint halted. */
|
---|
993 | VUSBSTATUS_STALL,
|
---|
994 | /** Device not responding. */
|
---|
995 | VUSBSTATUS_DNR,
|
---|
996 | /** CRC error. */
|
---|
997 | VUSBSTATUS_CRC,
|
---|
998 | /** Data overrun error. */
|
---|
999 | VUSBSTATUS_DATA_UNDERRUN,
|
---|
1000 | /** Data overrun error. */
|
---|
1001 | VUSBSTATUS_DATA_OVERRUN,
|
---|
1002 | /** The isochronous buffer hasn't been touched. */
|
---|
1003 | VUSBSTATUS_NOT_ACCESSED,
|
---|
1004 | /** Canceled/undone URB (VUSB internal). */
|
---|
1005 | VUSBSTATUS_UNDO,
|
---|
1006 | /** Invalid status. */
|
---|
1007 | VUSBSTATUS_INVALID = 0x7f
|
---|
1008 | } VUSBSTATUS;
|
---|
1009 |
|
---|
1010 |
|
---|
1011 | /**
|
---|
1012 | * VUSB Transfer types.
|
---|
1013 | */
|
---|
1014 | typedef enum VUSBXFERTYPE
|
---|
1015 | {
|
---|
1016 | /** Control message. Used to represent a single control transfer. */
|
---|
1017 | VUSBXFERTYPE_CTRL = 0,
|
---|
1018 | /* Isochronous transfer. */
|
---|
1019 | VUSBXFERTYPE_ISOC,
|
---|
1020 | /** Bulk transfer. */
|
---|
1021 | VUSBXFERTYPE_BULK,
|
---|
1022 | /** Interrupt transfer. */
|
---|
1023 | VUSBXFERTYPE_INTR,
|
---|
1024 | /** Complete control message. Used to represent an entire control message. */
|
---|
1025 | VUSBXFERTYPE_MSG,
|
---|
1026 | /** Invalid transfer type. */
|
---|
1027 | VUSBXFERTYPE_INVALID = 0x7f
|
---|
1028 | } VUSBXFERTYPE;
|
---|
1029 |
|
---|
1030 |
|
---|
1031 | /**
|
---|
1032 | * The URB states
|
---|
1033 | */
|
---|
1034 | typedef enum VUSBURBSTATE
|
---|
1035 | {
|
---|
1036 | /** The usual invalid state. */
|
---|
1037 | VUSBURBSTATE_INVALID = 0,
|
---|
1038 | /** The URB is free, i.e. not in use.
|
---|
1039 | * Next state: ALLOCATED */
|
---|
1040 | VUSBURBSTATE_FREE,
|
---|
1041 | /** The URB is allocated, i.e. being prepared for submission.
|
---|
1042 | * Next state: FREE, IN_FLIGHT */
|
---|
1043 | VUSBURBSTATE_ALLOCATED,
|
---|
1044 | /** The URB is in flight.
|
---|
1045 | * Next state: REAPED, CANCELLED */
|
---|
1046 | VUSBURBSTATE_IN_FLIGHT,
|
---|
1047 | /** The URB has been reaped and is being completed.
|
---|
1048 | * Next state: FREE */
|
---|
1049 | VUSBURBSTATE_REAPED,
|
---|
1050 | /** The URB has been cancelled and is awaiting reaping and immediate freeing.
|
---|
1051 | * Next state: FREE */
|
---|
1052 | VUSBURBSTATE_CANCELLED,
|
---|
1053 | /** The end of the valid states (exclusive). */
|
---|
1054 | VUSBURBSTATE_END,
|
---|
1055 | /** The usual 32-bit blow up. */
|
---|
1056 | VUSBURBSTATE_32BIT_HACK = 0x7fffffff
|
---|
1057 | } VUSBURBSTATE;
|
---|
1058 |
|
---|
1059 |
|
---|
1060 | /**
|
---|
1061 | * Information about a isochronous packet.
|
---|
1062 | */
|
---|
1063 | typedef struct VUSBURBISOCPKT
|
---|
1064 | {
|
---|
1065 | /** The size of the packet.
|
---|
1066 | * IN: The packet size. I.e. the number of bytes to the next packet or end of buffer.
|
---|
1067 | * OUT: The actual size transferred. */
|
---|
1068 | uint16_t cb;
|
---|
1069 | /** The offset of the packet. (Relative to VUSBURB::abData[0].)
|
---|
1070 | * OUT: This can be changed by the USB device if it does some kind of buffer squeezing. */
|
---|
1071 | uint16_t off;
|
---|
1072 | /** The status of the transfer.
|
---|
1073 | * IN: VUSBSTATUS_INVALID
|
---|
1074 | * OUT: VUSBSTATUS_INVALID if nothing was done, otherwise the correct status. */
|
---|
1075 | VUSBSTATUS enmStatus;
|
---|
1076 | } VUSBURBISOCPKT;
|
---|
1077 | /** Pointer to a isochronous packet. */
|
---|
1078 | typedef VUSBURBISOCPKT *PVUSBURBISOCPTK;
|
---|
1079 | /** Pointer to a const isochronous packet. */
|
---|
1080 | typedef const VUSBURBISOCPKT *PCVUSBURBISOCPKT;
|
---|
1081 |
|
---|
1082 | /**
|
---|
1083 | * Asynchronous USB request descriptor
|
---|
1084 | */
|
---|
1085 | typedef struct VUSBURB
|
---|
1086 | {
|
---|
1087 | /** URB magic value. */
|
---|
1088 | uint32_t u32Magic;
|
---|
1089 | /** The USR state. */
|
---|
1090 | VUSBURBSTATE enmState;
|
---|
1091 | /** Flag whether the URB is about to be completed,
|
---|
1092 | * either by the I/O thread or the cancellation worker.
|
---|
1093 | */
|
---|
1094 | volatile bool fCompleting;
|
---|
1095 | /** URB description, can be null. intended for logging. */
|
---|
1096 | char *pszDesc;
|
---|
1097 |
|
---|
1098 | #ifdef RDESKTOP
|
---|
1099 | /** The next URB in rdesktop-vrdp's linked list */
|
---|
1100 | PVUSBURB pNext;
|
---|
1101 | /** The previous URB in rdesktop-vrdp's linked list */
|
---|
1102 | PVUSBURB pPrev;
|
---|
1103 | /** The vrdp handle for the URB */
|
---|
1104 | uint32_t handle;
|
---|
1105 | /** Pointer used to find the usb proxy device */
|
---|
1106 | struct VUSBDEV *pDev;
|
---|
1107 | #endif
|
---|
1108 |
|
---|
1109 | /** The VUSB data. */
|
---|
1110 | struct VUSBURBVUSB
|
---|
1111 | {
|
---|
1112 | /** URB chain pointer. */
|
---|
1113 | PVUSBURB pNext;
|
---|
1114 | /** URB chain pointer. */
|
---|
1115 | PVUSBURB *ppPrev;
|
---|
1116 | /** Pointer to the original for control messages. */
|
---|
1117 | PVUSBURB pCtrlUrb;
|
---|
1118 | /** Pointer to the VUSB device.
|
---|
1119 | * This may be NULL if the destination address is invalid. */
|
---|
1120 | struct VUSBDEV *pDev;
|
---|
1121 | /** Sepcific to the pfnFree function. */
|
---|
1122 | void *pvFreeCtx;
|
---|
1123 | /**
|
---|
1124 | * Callback which will free the URB once it's reaped and completed.
|
---|
1125 | * @param pUrb The URB.
|
---|
1126 | */
|
---|
1127 | DECLCALLBACKMEMBER(void, pfnFree)(PVUSBURB pUrb);
|
---|
1128 | /** Submit timestamp. (logging only) */
|
---|
1129 | uint64_t u64SubmitTS;
|
---|
1130 | /** The allocated data length. */
|
---|
1131 | uint32_t cbDataAllocated;
|
---|
1132 | /** The allocated TD length. */
|
---|
1133 | uint32_t cTdsAllocated;
|
---|
1134 | } VUsb;
|
---|
1135 |
|
---|
1136 | /** The host controller data. */
|
---|
1137 | struct VUSBURBHCI
|
---|
1138 | {
|
---|
1139 | /** The endpoint descriptor address. */
|
---|
1140 | RTGCPHYS32 EdAddr;
|
---|
1141 | /** Number of Tds in the array. */
|
---|
1142 | uint32_t cTds;
|
---|
1143 | /** Pointer to an array of TD info items.*/
|
---|
1144 | struct VUSBURBHCITD
|
---|
1145 | {
|
---|
1146 | /** Type of TD (private) */
|
---|
1147 | uint32_t TdType;
|
---|
1148 | /** The address of the */
|
---|
1149 | RTGCPHYS32 TdAddr;
|
---|
1150 | /** A copy of the TD. */
|
---|
1151 | uint32_t TdCopy[16];
|
---|
1152 | } *paTds;
|
---|
1153 | /** URB chain pointer. */
|
---|
1154 | PVUSBURB pNext;
|
---|
1155 | /** When this URB was created.
|
---|
1156 | * (Used for isochronous frames and for logging.) */
|
---|
1157 | uint32_t u32FrameNo;
|
---|
1158 | /** Flag indicating that the TDs have been unlinked. */
|
---|
1159 | bool fUnlinked;
|
---|
1160 | } Hci;
|
---|
1161 |
|
---|
1162 | /** The device data. */
|
---|
1163 | struct VUSBURBDEV
|
---|
1164 | {
|
---|
1165 | /** Pointer to private device specific data. */
|
---|
1166 | void *pvPrivate;
|
---|
1167 | /** Used by the device when linking the URB in some list of its own. */
|
---|
1168 | PVUSBURB pNext;
|
---|
1169 | } Dev;
|
---|
1170 |
|
---|
1171 | #ifndef RDESKTOP
|
---|
1172 | /** The USB device instance this belongs to.
|
---|
1173 | * This is NULL if the device address is invalid, in which case this belongs to the hub. */
|
---|
1174 | PPDMUSBINS pUsbIns;
|
---|
1175 | #endif
|
---|
1176 | /** The device address.
|
---|
1177 | * This is set at allocation time. */
|
---|
1178 | uint8_t DstAddress;
|
---|
1179 |
|
---|
1180 | /** The endpoint.
|
---|
1181 | * IN: Must be set before submitting the URB.
|
---|
1182 | * @remark This does not have the high bit (direction) set! */
|
---|
1183 | uint8_t EndPt;
|
---|
1184 | /** The transfer type.
|
---|
1185 | * IN: Must be set before submitting the URB. */
|
---|
1186 | VUSBXFERTYPE enmType;
|
---|
1187 | /** The transfer direction.
|
---|
1188 | * IN: Must be set before submitting the URB. */
|
---|
1189 | VUSBDIRECTION enmDir;
|
---|
1190 | /** Indicates whether it is OK to receive/send less data than requested.
|
---|
1191 | * IN: Must be initialized before submitting the URB. */
|
---|
1192 | bool fShortNotOk;
|
---|
1193 | /** The transfer status.
|
---|
1194 | * OUT: This is set when reaping the URB. */
|
---|
1195 | VUSBSTATUS enmStatus;
|
---|
1196 |
|
---|
1197 | /** The number of isochronous packets describe in aIsocPkts.
|
---|
1198 | * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
|
---|
1199 | uint32_t cIsocPkts;
|
---|
1200 | /** The iso packets within abData.
|
---|
1201 | * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
|
---|
1202 | VUSBURBISOCPKT aIsocPkts[8];
|
---|
1203 |
|
---|
1204 | /** The message length.
|
---|
1205 | * IN: The amount of data to send / receive - set at allocation time.
|
---|
1206 | * OUT: The amount of data sent / received. */
|
---|
1207 | uint32_t cbData;
|
---|
1208 | /** The message data.
|
---|
1209 | * IN: On host to device transfers, the data to send.
|
---|
1210 | * OUT: On device to host transfers, the data to received.
|
---|
1211 | * This array has actually a size of VUsb.cbDataAllocated, not 8KB! */
|
---|
1212 | uint8_t abData[8*_1K];
|
---|
1213 | } VUSBURB;
|
---|
1214 |
|
---|
1215 | /** The magic value of a valid VUSBURB. (Murakami Haruki) */
|
---|
1216 | #define VUSBURB_MAGIC UINT32_C(0x19490112)
|
---|
1217 |
|
---|
1218 | /** @} */
|
---|
1219 |
|
---|
1220 |
|
---|
1221 | /** @} */
|
---|
1222 |
|
---|
1223 | RT_C_DECLS_END
|
---|
1224 |
|
---|
1225 | #endif
|
---|