VirtualBox

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

Last change on this file since 106381 was 106061, checked in by vboxsync, 3 months ago

Copyright year updates by scm.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 49.8 KB
Line 
1/** @file
2 * VUSB - VirtualBox USB. (DEV,VMM)
3 */
4
5/*
6 * Copyright (C) 2006-2024 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 * @param pInterface Pointer to this structure.
725 * @param u32FrameRate The new frame rate.
726 */
727 DECLR3CALLBACKMEMBER(void, pfnFrameRateChanged, (PVUSBIROOTHUBPORT pInterface, uint32_t u32FrameRate));
728
729 /** Alignment dummy. */
730 RTR3PTR Alignment;
731
732} VUSBIROOTHUBPORT;
733/** VUSBIROOTHUBPORT interface ID. */
734# define VUSBIROOTHUBPORT_IID "2ece01c2-4dbf-4bd5-96ca-09fc14164cd4"
735
736/** Pointer to a VUSB RootHub connector interface. */
737typedef struct VUSBIROOTHUBCONNECTOR *PVUSBIROOTHUBCONNECTOR;
738/**
739 * The VUSB RootHub connector interface provided by the VBox USB RootHub driver
740 * (up).
741 * Pair with VUSBIROOTHUBPORT.
742 */
743typedef struct VUSBIROOTHUBCONNECTOR
744{
745 /**
746 * Sets the URB parameters for the caller.
747 *
748 * @returns VBox status code.
749 * @param pInterface Pointer to this struct.
750 * @param cbHci Size of the data private to the HCI for each URB when allocated.
751 * @param cbHciTd Size of one transfer descriptor. The number of transfer descriptors
752 * is given VUSBIROOTHUBCONNECTOR::pfnNewUrb for each URB to calculate the
753 * final amount of memory required for the TDs.
754 *
755 * @note This must be called before starting to allocate any URB or otherwise there will be no
756 * data available for the HCI.
757 */
758 DECLR3CALLBACKMEMBER(int, pfnSetUrbParams, (PVUSBIROOTHUBCONNECTOR pInterface, size_t cbHci, size_t cbHciTd));
759
760 /**
761 * Resets the roothub.
762 *
763 * @returns VBox status code.
764 * @param pInterface Pointer to this struct.
765 * @param fResetOnLinux Whether or not to do real reset on linux.
766 */
767 DECLR3CALLBACKMEMBER(int, pfnReset, (PVUSBIROOTHUBCONNECTOR pInterface, bool fResetOnLinux));
768
769 /**
770 * Powers on the roothub.
771 *
772 * @returns VBox status code.
773 * @param pInterface Pointer to this struct.
774 */
775 DECLR3CALLBACKMEMBER(int, pfnPowerOn, (PVUSBIROOTHUBCONNECTOR pInterface));
776
777 /**
778 * Power off the roothub.
779 *
780 * @returns VBox status code.
781 * @param pInterface Pointer to this struct.
782 */
783 DECLR3CALLBACKMEMBER(int, pfnPowerOff, (PVUSBIROOTHUBCONNECTOR pInterface));
784
785 /**
786 * Allocates a new URB for a transfer.
787 *
788 * Either submit using pfnSubmitUrb or free using VUSBUrbFree().
789 *
790 * @returns Pointer to a new URB.
791 * @returns NULL on failure - try again later.
792 * This will not fail if the device wasn't found. We'll fail it
793 * at submit time, since that makes the usage of this api simpler.
794 * @param pInterface Pointer to this struct.
795 * @param DstAddress The destination address of the URB.
796 * @param uPort Optional port of the device the URB is for, use VUSB_DEVICE_PORT_INVALID to indicate to use the destination address.
797 * @param enmType Type of the URB.
798 * @param enmDir Data transfer direction.
799 * @param cbData The amount of data space required.
800 * @param cTds The amount of TD space.
801 * @param pszTag Custom URB tag assigned by the caller, only for
802 * logged builds and optional.
803 *
804 * @note pDev should be NULL in most cases. The only useful case is for USB3 where
805 * it is required for the SET_ADDRESS request because USB3 uses unicast traffic.
806 */
807 DECLR3CALLBACKMEMBER(PVUSBURB, pfnNewUrb,(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t uPort,
808 VUSBXFERTYPE enmType, VUSBDIRECTION enmDir, uint32_t cbData, uint32_t cTds, const char *pszTag));
809
810 /**
811 * Free an URB not submitted yet.
812 *
813 * @returns VBox status code.
814 * @param pInterface Pointer to this struct.
815 * @param pUrb Pointer to the URB to free returned by VUSBIROOTHUBCONNECTOR::pfnNewUrb.
816 */
817 DECLR3CALLBACKMEMBER(int, pfnFreeUrb, (PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb));
818
819 /**
820 * Submits a URB for transfer.
821 * The transfer will do asynchronously if possible.
822 *
823 * @returns VBox status code.
824 * @param pInterface Pointer to this struct.
825 * @param pUrb Pointer to the URB returned by pfnNewUrb.
826 * The URB will be freed in case of failure.
827 * @param pLed Pointer to USB Status LED
828 */
829 DECLR3CALLBACKMEMBER(int, pfnSubmitUrb,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed));
830
831 /**
832 * Call to service asynchronous URB completions in a polling fashion.
833 *
834 * Reaped URBs will be finished by calling the completion callback,
835 * thus there is no return code or input or anything from this function
836 * except for potential state changes elsewhere.
837 *
838 * @param pInterface Pointer to this struct.
839 * @param uPort Port of the device to reap URBs on.
840 * @param cMillies Number of milliseconds to poll for completion.
841 */
842 DECLR3CALLBACKMEMBER(void, pfnReapAsyncUrbs,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, RTMSINTERVAL cMillies));
843
844 /**
845 * Cancels and completes - with CRC failure - all URBs queued on an endpoint.
846 * This is done in response to guest URB cancellation.
847 *
848 * @returns VBox status code.
849 * @param pInterface Pointer to this struct.
850 * @param pUrb Pointer to a previously submitted URB.
851 */
852 DECLR3CALLBACKMEMBER(int, pfnCancelUrbsEp,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb));
853
854 /**
855 * Cancels and completes - with CRC failure - all in-flight async URBs.
856 * This is typically done before saving a state.
857 *
858 * @param pInterface Pointer to this struct.
859 */
860 DECLR3CALLBACKMEMBER(void, pfnCancelAllUrbs,(PVUSBIROOTHUBCONNECTOR pInterface));
861
862 /**
863 * Cancels and completes - with CRC failure - all URBs queued on an endpoint.
864 * This is done in response to a guest endpoint/pipe abort.
865 *
866 * @returns VBox status code.
867 * @param pInterface Pointer to this struct.
868 * @param uPort Port of the device.
869 * @param EndPt Endpoint number.
870 * @param enmDir Endpoint direction.
871 */
872 DECLR3CALLBACKMEMBER(int, pfnAbortEpByPort,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, int EndPt, VUSBDIRECTION enmDir));
873
874 /**
875 * Cancels and completes - with CRC failure - all URBs queued on an endpoint.
876 * This is done in response to a guest endpoint/pipe abort.
877 *
878 * @returns VBox status code.
879 * @param pInterface Pointer to this struct.
880 * @param DstAddress Port of the device.
881 * @param EndPt Endpoint number.
882 * @param enmDir Endpoint direction.
883 */
884 DECLR3CALLBACKMEMBER(int, pfnAbortEpByAddr,(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, int EndPt, VUSBDIRECTION enmDir));
885
886 /**
887 * Attach the device to the root hub.
888 * The device must not be attached to any hub for this call to succeed.
889 *
890 * @returns VBox status code.
891 * @param pInterface Pointer to this struct.
892 * @param uPort Port of the device to attach.
893 */
894 DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
895
896 /**
897 * Detach the device from the root hub.
898 * The device must already be attached for this call to succeed.
899 *
900 * @returns VBox status code.
901 * @param pInterface Pointer to this struct.
902 * @param uPort Port of the device to detach.
903 */
904 DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
905
906 /**
907 * Sets periodic frame processing.
908 *
909 * @returns VBox status code.
910 * @param pInterface Pointer to this struct.
911 * @param uFrameRate The target frame rate in Hertz, 0 disables periodic frame processing.
912 * The real frame rate might be lower if there is no activity for a certain period or
913 * higher if there is a need for catching up with where the guest expects the device to be.
914 */
915 DECLR3CALLBACKMEMBER(int, pfnSetPeriodicFrameProcessing, (PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uFrameRate));
916
917 /**
918 * Returns the current frame rate for the periodic frame processing.
919 *
920 * @returns Frame rate for periodic frame processing.
921 * @retval 0 if disabled.
922 * @param pInterface Pointer to this struct.
923 */
924 DECLR3CALLBACKMEMBER(uint32_t, pfnGetPeriodicFrameRate, (PVUSBIROOTHUBCONNECTOR pInterface));
925
926 /**
927 * Updates the internally stored isochronous scheduling frame for a given
928 * endpoint and returns the delta between the current and previous frame.
929 *
930 * @returns Delta between currently and previously scheduled frame.
931 * @retval 0 if no previous frame was set.
932 * @param pInterface Pointer to this struct.
933 * @param uPort Port of the device.
934 * @param EndPt Endpoint number.
935 * @param enmDir Endpoint direction.
936 * @param uNewFrameID The frame ID of a new transfer.
937 * @param uBits The number of significant bits in frame ID.
938 */
939 DECLR3CALLBACKMEMBER(uint32_t, pfnUpdateIsocFrameDelta, (PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort,
940 int EndPt, VUSBDIRECTION enmDir, uint16_t uNewFrameID, uint8_t uBits));
941
942 /**
943 * Resets the device.
944 *
945 * Since a device reset shall take at least 10ms from the guest point of view,
946 * it must be performed asynchronously. We create a thread which performs this
947 * operation and ensures it will take at least 10ms.
948 *
949 * At times - like init - a synchronous reset is required, this can be done
950 * by passing NULL for pfnDone.
951 *
952 * -- internal stuff, move it --
953 * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
954 * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
955 * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
956 * -- internal stuff, move it --
957 *
958 * @returns VBox status code.
959 * @param pInterface Pointer to this struct.
960 * @param uPort Port of the device to reset.
961 * @param fResetOnLinux Set if we can permit a real reset and a potential logical
962 * device reconnect on linux hosts.
963 * @param pfnDone Pointer to the completion routine. If NULL a synchronous
964 * reset is performed not respecting the 10ms.
965 * @param pvUser User argument to the completion routine.
966 * @param pVM The cross context VM structure. Required if pfnDone
967 * is not NULL.
968 */
969 DECLR3CALLBACKMEMBER(int, pfnDevReset,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, bool fResetOnLinux,
970 PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM));
971
972 /**
973 * Powers on the device.
974 *
975 * @returns VBox status code.
976 * @param pInterface Pointer to this struct.
977 * @param uPort Port of the device to power on.
978 */
979 DECLR3CALLBACKMEMBER(int, pfnDevPowerOn,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
980
981 /**
982 * Powers off the device.
983 *
984 * @returns VBox status code.
985 * @param pInterface Pointer to this struct.
986 * @param uPort Port of the device to power off.
987 */
988 DECLR3CALLBACKMEMBER(int, pfnDevPowerOff,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
989
990 /**
991 * Get the state of the device.
992 *
993 * @returns Device state.
994 * @param pInterface Pointer to this struct.
995 * @param uPort Port of the device to get the state for.
996 */
997 DECLR3CALLBACKMEMBER(VUSBDEVICESTATE, pfnDevGetState,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
998
999 /**
1000 * Returns whether the device implements the saved state handlers
1001 * and doesn't need to get detached.
1002 *
1003 * @returns true if the device supports saving the state, false otherwise.
1004 * @param pInterface Pointer to this struct.
1005 * @param uPort Port of the device to query saved state support for.
1006 */
1007 DECLR3CALLBACKMEMBER(bool, pfnDevIsSavedStateSupported,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
1008
1009 /**
1010 * Get the speed the device is operating at.
1011 *
1012 * @returns Device state.
1013 * @param pInterface Pointer to this struct.
1014 * @param uPort Port of the device to query the speed for.
1015 */
1016 DECLR3CALLBACKMEMBER(VUSBSPEED, pfnDevGetSpeed,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
1017
1018 /** Alignment dummy. */
1019 RTR3PTR Alignment;
1020
1021} VUSBIROOTHUBCONNECTOR;
1022AssertCompileSizeAlignment(VUSBIROOTHUBCONNECTOR, 8);
1023/** VUSBIROOTHUBCONNECTOR interface ID. */
1024# define VUSBIROOTHUBCONNECTOR_IID "83eb1fb4-d755-4925-a7c5-751d0899c048"
1025
1026
1027# ifdef IN_RING3
1028/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSetUrbParams */
1029DECLINLINE(int) VUSBIRhSetUrbParams(PVUSBIROOTHUBCONNECTOR pInterface, size_t cbHci, size_t cbHciTd)
1030{
1031 return pInterface->pfnSetUrbParams(pInterface, cbHci, cbHciTd);
1032}
1033
1034/** @copydoc VUSBIROOTHUBCONNECTOR::pfnNewUrb */
1035DECLINLINE(PVUSBURB) VUSBIRhNewUrb(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t uPort,
1036 VUSBXFERTYPE enmType, VUSBDIRECTION enmDir, uint32_t cbData, uint32_t cTds, const char *pszTag)
1037{
1038 return pInterface->pfnNewUrb(pInterface, DstAddress, uPort, enmType, enmDir, cbData, cTds, pszTag);
1039}
1040
1041/** @copydoc VUSBIROOTHUBCONNECTOR::pfnFreeUrb */
1042DECLINLINE(int) VUSBIRhFreeUrb(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb)
1043{
1044 return pInterface->pfnFreeUrb(pInterface, pUrb);
1045}
1046
1047/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSubmitUrb */
1048DECLINLINE(int) VUSBIRhSubmitUrb(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed)
1049{
1050 return pInterface->pfnSubmitUrb(pInterface, pUrb, pLed);
1051}
1052
1053/** @copydoc VUSBIROOTHUBCONNECTOR::pfnReapAsyncUrbs */
1054DECLINLINE(void) VUSBIRhReapAsyncUrbs(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, RTMSINTERVAL cMillies)
1055{
1056 pInterface->pfnReapAsyncUrbs(pInterface, uPort, cMillies);
1057}
1058
1059/** @copydoc VUSBIROOTHUBCONNECTOR::pfnCancelAllUrbs */
1060DECLINLINE(void) VUSBIRhCancelAllUrbs(PVUSBIROOTHUBCONNECTOR pInterface)
1061{
1062 pInterface->pfnCancelAllUrbs(pInterface);
1063}
1064
1065/** @copydoc VUSBIROOTHUBCONNECTOR::pfnAttachDevice */
1066DECLINLINE(int) VUSBIRhAttachDevice(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
1067{
1068 return pInterface->pfnAttachDevice(pInterface, uPort);
1069}
1070
1071/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDetachDevice */
1072DECLINLINE(int) VUSBIRhDetachDevice(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
1073{
1074 return pInterface->pfnDetachDevice(pInterface, uPort);
1075}
1076
1077/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSetPeriodicFrameProcessing */
1078DECLINLINE(int) VUSBIRhSetPeriodicFrameProcessing(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uFrameRate)
1079{
1080 return pInterface->pfnSetPeriodicFrameProcessing(pInterface, uFrameRate);
1081}
1082
1083/** @copydoc VUSBIROOTHUBCONNECTOR::pfnGetPeriodicFrameRate */
1084DECLINLINE(uint32_t) VUSBIRhGetPeriodicFrameRate(PVUSBIROOTHUBCONNECTOR pInterface)
1085{
1086 return pInterface->pfnGetPeriodicFrameRate(pInterface);
1087}
1088
1089/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevReset */
1090DECLINLINE(int) VUSBIRhDevReset(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, bool fResetOnLinux,
1091 PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
1092{
1093 return pInterface->pfnDevReset(pInterface, uPort, fResetOnLinux, pfnDone, pvUser, pVM);
1094}
1095
1096/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevPowerOn */
1097DECLINLINE(int) VUSBIRhDevPowerOn(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
1098{
1099 return pInterface->pfnDevPowerOn(pInterface, uPort);
1100}
1101
1102/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevPowerOff */
1103DECLINLINE(int) VUSBIRhDevPowerOff(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
1104{
1105 return pInterface->pfnDevPowerOff(pInterface, uPort);
1106}
1107
1108/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevGetState */
1109DECLINLINE(VUSBDEVICESTATE) VUSBIRhDevGetState(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
1110{
1111 return pInterface->pfnDevGetState(pInterface, uPort);
1112}
1113
1114/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevGetState */
1115DECLINLINE(bool) VUSBIRhDevIsSavedStateSupported(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
1116{
1117 return pInterface->pfnDevIsSavedStateSupported(pInterface, uPort);
1118}
1119
1120/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevGetSpeed */
1121DECLINLINE(VUSBSPEED) VUSBIRhDevGetSpeed(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
1122{
1123 return pInterface->pfnDevGetSpeed(pInterface, uPort);
1124}
1125# endif /* IN_RING3 */
1126
1127#endif /* ! RDESKTOP */
1128
1129
1130#ifndef RDESKTOP
1131
1132/**
1133 * USB Device Interface (up).
1134 * No interface pair.
1135 */
1136typedef struct VUSBIDEVICE
1137{
1138 /**
1139 * Resets the device.
1140 *
1141 * Since a device reset shall take at least 10ms from the guest point of view,
1142 * it must be performed asynchronously. We create a thread which performs this
1143 * operation and ensures it will take at least 10ms.
1144 *
1145 * At times - like init - a synchronous reset is required, this can be done
1146 * by passing NULL for pfnDone.
1147 *
1148 * -- internal stuff, move it --
1149 * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
1150 * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
1151 * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
1152 * -- internal stuff, move it --
1153 *
1154 * @returns VBox status code.
1155 * @param pInterface Pointer to this structure.
1156 * @param fResetOnLinux Set if we can permit a real reset and a potential logical
1157 * device reconnect on linux hosts.
1158 * @param pfnDone Pointer to the completion routine. If NULL a synchronous
1159 * reset is performed not respecting the 10ms.
1160 * @param pvUser User argument to the completion routine.
1161 * @param pVM The cross context VM structure. Required if pfnDone
1162 * is not NULL.
1163 */
1164 DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIDEVICE pInterface, bool fResetOnLinux,
1165 PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM));
1166
1167 /**
1168 * Powers on the device.
1169 *
1170 * @returns VBox status code.
1171 * @param pInterface Pointer to the device interface structure.
1172 */
1173 DECLR3CALLBACKMEMBER(int, pfnPowerOn,(PVUSBIDEVICE pInterface));
1174
1175 /**
1176 * Powers off the device.
1177 *
1178 * @returns VBox status code.
1179 * @param pInterface Pointer to the device interface structure.
1180 */
1181 DECLR3CALLBACKMEMBER(int, pfnPowerOff,(PVUSBIDEVICE pInterface));
1182
1183 /**
1184 * Get the state of the device.
1185 *
1186 * @returns Device state.
1187 * @param pInterface Pointer to the device interface structure.
1188 */
1189 DECLR3CALLBACKMEMBER(VUSBDEVICESTATE, pfnGetState,(PVUSBIDEVICE pInterface));
1190
1191 /**
1192 * Returns whether the device implements the saved state handlers
1193 * and doesn't need to get detached.
1194 *
1195 * @returns true if the device supports saving the state, false otherwise.
1196 * @param pInterface Pointer to the device interface structure.
1197 */
1198 DECLR3CALLBACKMEMBER(bool, pfnIsSavedStateSupported,(PVUSBIDEVICE pInterface));
1199
1200 /**
1201 * Get the speed the device is operating at.
1202 *
1203 * @returns Device state.
1204 * @param pInterface Pointer to the device interface structure.
1205 */
1206 DECLR3CALLBACKMEMBER(VUSBSPEED, pfnGetSpeed,(PVUSBIDEVICE pInterface));
1207
1208} VUSBIDEVICE;
1209/** VUSBIDEVICE interface ID. */
1210# define VUSBIDEVICE_IID "af576b38-e8ca-4db7-810a-2596d8d57ca0"
1211
1212
1213# ifdef IN_RING3
1214/**
1215 * Resets the device.
1216 *
1217 * Since a device reset shall take at least 10ms from the guest point of view,
1218 * it must be performed asynchronously. We create a thread which performs this
1219 * operation and ensures it will take at least 10ms.
1220 *
1221 * At times - like init - a synchronous reset is required, this can be done
1222 * by passing NULL for pfnDone.
1223 *
1224 * -- internal stuff, move it --
1225 * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
1226 * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
1227 * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
1228 * -- internal stuff, move it --
1229 *
1230 * @returns VBox status code.
1231 * @param pInterface Pointer to the device interface structure.
1232 * @param fResetOnLinux Set if we can permit a real reset and a potential logical
1233 * device reconnect on linux hosts.
1234 * @param pfnDone Pointer to the completion routine. If NULL a
1235 * synchronous reset is performed not respecting the
1236 * 10ms.
1237 * @param pvUser User argument to the completion routine.
1238 * @param pVM The cross context VM structure. Required if pfnDone
1239 * is not NULL.
1240 *
1241 * NULL is acceptable Required if callback in EMT is desired, NULL is otherwise
1242 * acceptable.
1243 */
1244DECLINLINE(int) VUSBIDevReset(PVUSBIDEVICE pInterface, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
1245{
1246 return pInterface->pfnReset(pInterface, fResetOnLinux, pfnDone, pvUser, pVM);
1247}
1248
1249/**
1250 * Powers on the device.
1251 *
1252 * @returns VBox status code.
1253 * @param pInterface Pointer to the device interface structure.
1254 */
1255DECLINLINE(int) VUSBIDevPowerOn(PVUSBIDEVICE pInterface)
1256{
1257 return pInterface->pfnPowerOn(pInterface);
1258}
1259
1260/**
1261 * Powers off the device.
1262 *
1263 * @returns VBox status code.
1264 * @param pInterface Pointer to the device interface structure.
1265 */
1266DECLINLINE(int) VUSBIDevPowerOff(PVUSBIDEVICE pInterface)
1267{
1268 return pInterface->pfnPowerOff(pInterface);
1269}
1270
1271/**
1272 * Get the state of the device.
1273 *
1274 * @returns Device state.
1275 * @param pInterface Pointer to the device interface structure.
1276 */
1277DECLINLINE(VUSBDEVICESTATE) VUSBIDevGetState(PVUSBIDEVICE pInterface)
1278{
1279 return pInterface->pfnGetState(pInterface);
1280}
1281
1282/**
1283 * @copydoc VUSBIDEVICE::pfnIsSavedStateSupported
1284 */
1285DECLINLINE(bool) VUSBIDevIsSavedStateSupported(PVUSBIDEVICE pInterface)
1286{
1287 return pInterface->pfnIsSavedStateSupported(pInterface);
1288}
1289# endif /* IN_RING3 */
1290
1291#endif /* ! RDESKTOP */
1292
1293/** @name URB
1294 * @{ */
1295
1296/**
1297 * VUSB Transfer status codes.
1298 */
1299typedef enum VUSBSTATUS
1300{
1301 /** Transer was ok. */
1302 VUSBSTATUS_OK = 0,
1303 /** Transfer stalled, endpoint halted. */
1304 VUSBSTATUS_STALL,
1305 /** Device not responding. */
1306 VUSBSTATUS_DNR,
1307 /** CRC error. */
1308 VUSBSTATUS_CRC,
1309 /** Data underrun error. */
1310 VUSBSTATUS_DATA_UNDERRUN,
1311 /** Data overrun error. */
1312 VUSBSTATUS_DATA_OVERRUN,
1313 /** The isochronous buffer hasn't been touched. */
1314 VUSBSTATUS_NOT_ACCESSED,
1315 /** Canceled/undone URB (VUSB internal). */
1316 VUSBSTATUS_UNDO,
1317 /** Canceled URB. */
1318 VUSBSTATUS_CANCELED,
1319 /** Invalid status. */
1320 VUSBSTATUS_INVALID = 0x7f
1321} VUSBSTATUS;
1322
1323
1324/**
1325 * The URB states
1326 */
1327typedef enum VUSBURBSTATE
1328{
1329 /** The usual invalid state. */
1330 VUSBURBSTATE_INVALID = 0,
1331 /** The URB is free, i.e. not in use.
1332 * Next state: ALLOCATED */
1333 VUSBURBSTATE_FREE,
1334 /** The URB is allocated, i.e. being prepared for submission.
1335 * Next state: FREE, IN_FLIGHT */
1336 VUSBURBSTATE_ALLOCATED,
1337 /** The URB is in flight.
1338 * Next state: REAPED, CANCELLED */
1339 VUSBURBSTATE_IN_FLIGHT,
1340 /** The URB has been reaped and is being completed.
1341 * Next state: FREE */
1342 VUSBURBSTATE_REAPED,
1343 /** The URB has been cancelled and is awaiting reaping and immediate freeing.
1344 * Next state: FREE */
1345 VUSBURBSTATE_CANCELLED,
1346 /** The end of the valid states (exclusive). */
1347 VUSBURBSTATE_END,
1348 /** The usual 32-bit blow up. */
1349 VUSBURBSTATE_32BIT_HACK = 0x7fffffff
1350} VUSBURBSTATE;
1351
1352
1353/**
1354 * Information about a isochronous packet.
1355 */
1356typedef struct VUSBURBISOCPKT
1357{
1358 /** The size of the packet.
1359 * IN: The packet size. I.e. the number of bytes to the next packet or end of buffer.
1360 * OUT: The actual size transferred. */
1361 uint32_t cb;
1362 /** The offset of the packet. (Relative to VUSBURB::abData[0].)
1363 * OUT: This can be changed by the USB device if it does some kind of buffer squeezing. */
1364 uint32_t off;
1365 /** The status of the transfer.
1366 * IN: VUSBSTATUS_INVALID
1367 * OUT: VUSBSTATUS_INVALID if nothing was done, otherwise the correct status. */
1368 VUSBSTATUS enmStatus;
1369} VUSBURBISOCPKT;
1370/** Pointer to a isochronous packet. */
1371typedef VUSBURBISOCPKT *PVUSBURBISOCPTK;
1372/** Pointer to a const isochronous packet. */
1373typedef const VUSBURBISOCPKT *PCVUSBURBISOCPKT;
1374
1375/** Private controller emulation specific data for the associated USB request descriptor. */
1376typedef struct VUSBURBHCIINT *PVUSBURBHCI;
1377/** Private controller emulation specific TD data. */
1378typedef struct VUSBURBHCITDINT *PVUSBURBHCITD;
1379/** Private VUSB/roothub related state for the associated URB. */
1380typedef struct VUSBURBVUSBINT *PVUSBURBVUSB;
1381
1382/**
1383 * Asynchronous USB request descriptor
1384 */
1385typedef struct VUSBURB
1386{
1387 /** URB magic value. */
1388 uint32_t u32Magic;
1389 /** The USR state. */
1390 VUSBURBSTATE enmState;
1391 /** Flag whether the URB is about to be completed,
1392 * either by the I/O thread or the cancellation worker.
1393 */
1394 volatile bool fCompleting;
1395 /** URB description, can be null. intended for logging. */
1396 char *pszDesc;
1397
1398#ifdef RDESKTOP
1399 /** The next URB in rdesktop-vrdp's linked list */
1400 PVUSBURB pNext;
1401 /** The previous URB in rdesktop-vrdp's linked list */
1402 PVUSBURB pPrev;
1403 /** The vrdp handle for the URB */
1404 uint32_t handle;
1405 /** Pointer used to find the usb proxy device */
1406 struct VUSBDEV *pDev;
1407#endif
1408
1409 /** The VUSB stack private data. */
1410 PVUSBURBVUSB pVUsb;
1411 /** Private host controller data associated with this URB. */
1412 PVUSBURBHCI pHci;
1413 /** Pointer to the host controller transfer descriptor array. */
1414 PVUSBURBHCITD paTds;
1415
1416 /** The device data. */
1417 struct VUSBURBDEV
1418 {
1419 /** Pointer to private device specific data. */
1420 void *pvPrivate;
1421 /** Used by the device when linking the URB in some list of its own. */
1422 PVUSBURB pNext;
1423 } Dev;
1424
1425 /** The device address.
1426 * This is set at allocation time. */
1427 uint8_t DstAddress;
1428
1429 /** The endpoint.
1430 * IN: Must be set before submitting the URB.
1431 * @remark This does not have the high bit (direction) set! */
1432 uint8_t EndPt;
1433 /** The transfer type.
1434 * IN: Set at allocation time. */
1435 VUSBXFERTYPE enmType;
1436 /** The transfer direction.
1437 * IN: Set at allocation time. */
1438 VUSBDIRECTION enmDir;
1439 /** Indicates whether it is OK to receive/send less data than requested.
1440 * IN: Must be initialized before submitting the URB. */
1441 bool fShortNotOk;
1442 /** The transfer status.
1443 * OUT: This is set when reaping the URB. */
1444 VUSBSTATUS enmStatus;
1445
1446 /** The relative starting frame for isochronous transfers.
1447 * Zero indicates "transfer ASAP".
1448 * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
1449 uint16_t uStartFrameDelta;
1450 /** Flag indicating whether the start frame delta is relative
1451 * to the previous transfer (false) or now (true).
1452 * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
1453 bool fStartRelToNow;
1454 /** The number of isochronous packets describe in aIsocPkts.
1455 * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
1456 uint8_t cIsocPkts;
1457 /** The iso packets within abData.
1458 * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
1459 VUSBURBISOCPKT aIsocPkts[8];
1460
1461 /** The message length.
1462 * IN: The amount of data to send / receive - set at allocation time.
1463 * OUT: The amount of data sent / received. */
1464 uint32_t cbData;
1465 /** The message data.
1466 * IN: On host to device transfers, the data to send.
1467 * OUT: On device to host transfers, the data to received.
1468 * This array has actually a size of VUsb.cbDataAllocated, not 8KB! */
1469 uint8_t abData[8*_1K];
1470} VUSBURB;
1471
1472/** The magic value of a valid VUSBURB. (Murakami Haruki) */
1473#define VUSBURB_MAGIC UINT32_C(0x19490112)
1474
1475/** @} */
1476
1477
1478/** @} */
1479
1480RT_C_DECLS_END
1481
1482#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