VirtualBox

source: vbox/trunk/include/VBox/vusb.h@ 97583

Last change on this file since 97583 was 96407, checked in by vboxsync, 2 years ago

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette