summaryrefslogtreecommitdiffstats
path: root/include/VBox/vusb.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--include/VBox/vusb.h1472
1 files changed, 1472 insertions, 0 deletions
diff --git a/include/VBox/vusb.h b/include/VBox/vusb.h
new file mode 100644
index 00000000..95ae9b0a
--- /dev/null
+++ b/include/VBox/vusb.h
@@ -0,0 +1,1472 @@
+/** @file
+ * VUSB - VirtualBox USB. (DEV,VMM)
+ */
+
+/*
+ * Copyright (C) 2006-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef VBOX_INCLUDED_vusb_h
+#define VBOX_INCLUDED_vusb_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <VBox/cdefs.h>
+#include <VBox/types.h>
+#include <iprt/assert.h>
+
+struct PDMLED;
+
+RT_C_DECLS_BEGIN
+
+/** @defgroup grp_vusb VBox USB API
+ * @{
+ */
+
+/** @defgroup grp_vusb_std Standard Stuff
+ * @{ */
+
+/** Frequency of USB bus (from spec). */
+#define VUSB_BUS_HZ 12000000
+
+
+/** @name USB Descriptor types (from spec)
+ * @{ */
+#define VUSB_DT_DEVICE 0x01
+#define VUSB_DT_CONFIG 0x02
+#define VUSB_DT_STRING 0x03
+#define VUSB_DT_INTERFACE 0x04
+#define VUSB_DT_ENDPOINT 0x05
+#define VUSB_DT_DEVICE_QUALIFIER 0x06
+#define VUSB_DT_OTHER_SPEED_CFG 0x07
+#define VUSB_DT_INTERFACE_POWER 0x08
+#define VUSB_DT_INTERFACE_ASSOCIATION 0x0B
+#define VUSB_DT_BOS 0x0F
+#define VUSB_DT_DEVICE_CAPABILITY 0x10
+#define VUSB_DT_SS_ENDPOINT_COMPANION 0x30
+/** @} */
+
+/** @name USB Descriptor minimum sizes (from spec)
+ * @{ */
+#define VUSB_DT_DEVICE_MIN_LEN 18
+#define VUSB_DT_CONFIG_MIN_LEN 9
+#define VUSB_DT_CONFIG_STRING_MIN_LEN 2
+#define VUSB_DT_INTERFACE_MIN_LEN 9
+#define VUSB_DT_ENDPOINT_MIN_LEN 7
+#define VUSB_DT_SSEP_COMPANION_MIN_LEN 6
+/** @} */
+
+/** @name USB Device Capability Type Codes (from spec)
+ * @{ */
+#define VUSB_DCT_WIRELESS_USB 0x01
+#define VUSB_DCT_USB_20_EXTENSION 0x02
+#define VUSB_DCT_SUPERSPEED_USB 0x03
+#define VUSB_DCT_CONTAINER_ID 0x04
+/** @} */
+
+
+#pragma pack(1) /* ensure byte packing of the descriptors. */
+
+/**
+ * USB language id descriptor (from specs).
+ */
+typedef struct VUSBDESCLANGID
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+} VUSBDESCLANGID;
+/** Pointer to a USB language id descriptor. */
+typedef VUSBDESCLANGID *PVUSBDESCLANGID;
+/** Pointer to a const USB language id descriptor. */
+typedef const VUSBDESCLANGID *PCVUSBDESCLANGID;
+
+
+/**
+ * USB string descriptor (from specs).
+ */
+typedef struct VUSBDESCSTRING
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+} VUSBDESCSTRING;
+/** Pointer to a USB string descriptor. */
+typedef VUSBDESCSTRING *PVUSBDESCSTRING;
+/** Pointer to a const USB string descriptor. */
+typedef const VUSBDESCSTRING *PCVUSBDESCSTRING;
+
+
+/**
+ * USB device descriptor (from spec)
+ */
+typedef struct VUSBDESCDEVICE
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint16_t bcdUSB;
+ uint8_t bDeviceClass;
+ uint8_t bDeviceSubClass;
+ uint8_t bDeviceProtocol;
+ uint8_t bMaxPacketSize0;
+ uint16_t idVendor;
+ uint16_t idProduct;
+ uint16_t bcdDevice;
+ uint8_t iManufacturer;
+ uint8_t iProduct;
+ uint8_t iSerialNumber;
+ uint8_t bNumConfigurations;
+} VUSBDESCDEVICE;
+/** Pointer to a USB device descriptor. */
+typedef VUSBDESCDEVICE *PVUSBDESCDEVICE;
+/** Pointer to a const USB device descriptor. */
+typedef const VUSBDESCDEVICE *PCVUSBDESCDEVICE;
+
+/**
+ * USB device qualifier (from spec 9.6.2)
+ */
+struct VUSBDEVICEQUALIFIER
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint16_t bcdUsb;
+ uint8_t bDeviceClass;
+ uint8_t bDeviceSubClass;
+ uint8_t bDeviceProtocol;
+ uint8_t bMaxPacketSize0;
+ uint8_t bNumConfigurations;
+ uint8_t bReserved;
+};
+
+typedef struct VUSBDEVICEQUALIFIER VUSBDEVICEQUALIFIER;
+typedef VUSBDEVICEQUALIFIER *PVUSBDEVICEQUALIFIER;
+
+
+/**
+ * USB configuration descriptor (from spec).
+ */
+typedef struct VUSBDESCCONFIG
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint16_t wTotalLength; /**< recalculated by VUSB when involved in URB. */
+ uint8_t bNumInterfaces;
+ uint8_t bConfigurationValue;
+ uint8_t iConfiguration;
+ uint8_t bmAttributes;
+ uint8_t MaxPower;
+} VUSBDESCCONFIG;
+/** Pointer to a USB configuration descriptor. */
+typedef VUSBDESCCONFIG *PVUSBDESCCONFIG;
+/** Pointer to a readonly USB configuration descriptor. */
+typedef const VUSBDESCCONFIG *PCVUSBDESCCONFIG;
+
+
+/**
+ * USB interface association descriptor (from USB ECN Interface Association Descriptors)
+ */
+typedef struct VUSBDESCIAD
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint8_t bFirstInterface;
+ uint8_t bInterfaceCount;
+ uint8_t bFunctionClass;
+ uint8_t bFunctionSubClass;
+ uint8_t bFunctionProtocol;
+ uint8_t iFunction;
+} VUSBDESCIAD;
+/** Pointer to a USB interface association descriptor. */
+typedef VUSBDESCIAD *PVUSBDESCIAD;
+/** Pointer to a readonly USB interface association descriptor. */
+typedef const VUSBDESCIAD *PCVUSBDESCIAD;
+
+
+/**
+ * USB interface descriptor (from spec)
+ */
+typedef struct VUSBDESCINTERFACE
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint8_t bInterfaceNumber;
+ uint8_t bAlternateSetting;
+ uint8_t bNumEndpoints;
+ uint8_t bInterfaceClass;
+ uint8_t bInterfaceSubClass;
+ uint8_t bInterfaceProtocol;
+ uint8_t iInterface;
+} VUSBDESCINTERFACE;
+/** Pointer to a USB interface descriptor. */
+typedef VUSBDESCINTERFACE *PVUSBDESCINTERFACE;
+/** Pointer to a const USB interface descriptor. */
+typedef const VUSBDESCINTERFACE *PCVUSBDESCINTERFACE;
+
+
+/**
+ * USB endpoint descriptor (from spec)
+ */
+typedef struct VUSBDESCENDPOINT
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint8_t bEndpointAddress;
+ uint8_t bmAttributes;
+ uint16_t wMaxPacketSize;
+ uint8_t bInterval;
+} VUSBDESCENDPOINT;
+/** Pointer to a USB endpoint descriptor. */
+typedef VUSBDESCENDPOINT *PVUSBDESCENDPOINT;
+/** Pointer to a const USB endpoint descriptor. */
+typedef const VUSBDESCENDPOINT *PCVUSBDESCENDPOINT;
+
+
+/**
+ * USB SuperSpeed endpoint companion descriptor (from USB3 spec)
+ */
+typedef struct VUSBDESCSSEPCOMPANION
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint8_t bMaxBurst;
+ uint8_t bmAttributes;
+ uint16_t wBytesPerInterval;
+} VUSBDESCSSEPCOMPANION;
+/** Pointer to a USB endpoint companion descriptor. */
+typedef VUSBDESCSSEPCOMPANION *PVUSBDESCSSEPCOMPANION;
+/** Pointer to a const USB endpoint companion descriptor. */
+typedef const VUSBDESCSSEPCOMPANION *PCVUSBDESCSSEPCOMPANION;
+
+
+/**
+ * USB Binary Device Object Store, aka BOS (from USB3 spec)
+ */
+typedef struct VUSBDESCBOS
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint16_t wTotalLength;
+ uint8_t bNumDeviceCaps;
+} VUSBDESCBOS;
+/** Pointer to a USB BOS descriptor. */
+typedef VUSBDESCBOS *PVUSBDESCBOS;
+/** Pointer to a const USB BOS descriptor. */
+typedef const VUSBDESCBOS *PCVUSBDESCBOS;
+
+
+/**
+ * Generic USB Device Capability Descriptor within BOS (from USB3 spec)
+ */
+typedef struct VUSBDESCDEVICECAP
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType;
+ uint8_t bDevCapabilityType;
+ uint8_t aCapSpecific[1];
+} VUSBDESCDEVICECAP;
+/** Pointer to a USB device capability descriptor. */
+typedef VUSBDESCDEVICECAP *PVUSBDESCDEVICECAP;
+/** Pointer to a const USB device capability descriptor. */
+typedef const VUSBDESCDEVICECAP *PCVUSBDESCDEVICECAP;
+
+
+/**
+ * SuperSpeed USB Device Capability Descriptor within BOS
+ */
+typedef struct VUSBDESCSSDEVCAP
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType; /* DEVICE CAPABILITY */
+ uint8_t bDevCapabilityType; /* SUPERSPEED_USB */
+ uint8_t bmAttributes;
+ uint16_t wSpeedsSupported;
+ uint8_t bFunctionalitySupport;
+ uint8_t bU1DevExitLat;
+ uint16_t wU2DevExitLat;
+} VUSBDESCSSDEVCAP;
+/** Pointer to an SS USB device capability descriptor. */
+typedef VUSBDESCSSDEVCAP *PVUSBDESCSSDEVCAP;
+/** Pointer to a const SS USB device capability descriptor. */
+typedef const VUSBDESCSSDEVCAP *PCVUSBDESCSSDEVCAP;
+
+
+/**
+ * USB 2.0 Extension Descriptor within BOS
+ */
+typedef struct VUSBDESCUSB2EXT
+{
+ uint8_t bLength;
+ uint8_t bDescriptorType; /* DEVICE CAPABILITY */
+ uint8_t bDevCapabilityType; /* USB 2.0 EXTENSION */
+ uint8_t bmAttributes;
+} VUSBDESCUSB2EXT;
+/** Pointer to a USB 2.0 extension capability descriptor. */
+typedef VUSBDESCUSB2EXT *PVUSBDESCUSB2EXT;
+/** Pointer to a const USB 2.0 extension capability descriptor. */
+typedef const VUSBDESCUSB2EXT *PCVUSBDESCUSB2EXT;
+
+
+#pragma pack() /* end of the byte packing. */
+
+
+/**
+ * USB configuration descriptor, the parsed variant used by VUSB.
+ */
+typedef struct VUSBDESCCONFIGEX
+{
+ /** The USB descriptor data.
+ * @remark The wTotalLength member is recalculated before the data is passed to the guest. */
+ VUSBDESCCONFIG Core;
+ /** Pointer to additional descriptor bytes following what's covered by VUSBDESCCONFIG. */
+ void *pvMore;
+ /** Pointer to additional class- or vendor-specific interface descriptors. */
+ const void *pvClass;
+ /** Size of class- or vendor-specific descriptors. */
+ uint16_t cbClass;
+ /** Pointer to an array of the interfaces referenced in the configuration.
+ * Core.bNumInterfaces in size. */
+ const struct VUSBINTERFACE *paIfs;
+ /** Pointer to the original descriptor data read from the device. */
+ const void *pvOriginal;
+} VUSBDESCCONFIGEX;
+/** Pointer to a parsed USB configuration descriptor. */
+typedef VUSBDESCCONFIGEX *PVUSBDESCCONFIGEX;
+/** Pointer to a const parsed USB configuration descriptor. */
+typedef const VUSBDESCCONFIGEX *PCVUSBDESCCONFIGEX;
+
+
+/**
+ * For tracking the alternate interface settings of a configuration.
+ */
+typedef struct VUSBINTERFACE
+{
+ /** Pointer to an array of interfaces. */
+ const struct VUSBDESCINTERFACEEX *paSettings;
+ /** The number of entries in the array. */
+ uint32_t cSettings;
+} VUSBINTERFACE;
+/** Pointer to a VUSBINTERFACE. */
+typedef VUSBINTERFACE *PVUSBINTERFACE;
+/** Pointer to a const VUSBINTERFACE. */
+typedef const VUSBINTERFACE *PCVUSBINTERFACE;
+
+
+/**
+ * USB interface descriptor, the parsed variant used by VUSB.
+ */
+typedef struct VUSBDESCINTERFACEEX
+{
+ /** The USB descriptor data. */
+ VUSBDESCINTERFACE Core;
+ /** Pointer to additional descriptor bytes following what's covered by VUSBDESCINTERFACE. */
+ const void *pvMore;
+ /** Pointer to additional class- or vendor-specific interface descriptors. */
+ const void *pvClass;
+ /** Size of class- or vendor-specific descriptors. */
+ uint16_t cbClass;
+ /** Pointer to an array of the endpoints referenced by the interface.
+ * Core.bNumEndpoints in size. */
+ const struct VUSBDESCENDPOINTEX *paEndpoints;
+ /** Interface association descriptor, which prepends a group of interfaces,
+ * starting with this interface. */
+ PCVUSBDESCIAD pIAD;
+ /** Size of interface association descriptor. */
+ uint16_t cbIAD;
+} VUSBDESCINTERFACEEX;
+/** Pointer to an prased USB interface descriptor. */
+typedef VUSBDESCINTERFACEEX *PVUSBDESCINTERFACEEX;
+/** Pointer to a const parsed USB interface descriptor. */
+typedef const VUSBDESCINTERFACEEX *PCVUSBDESCINTERFACEEX;
+
+
+/**
+ * USB endpoint descriptor, the parsed variant used by VUSB.
+ */
+typedef struct VUSBDESCENDPOINTEX
+{
+ /** The USB descriptor data.
+ * @remark The wMaxPacketSize member is converted to native endian. */
+ VUSBDESCENDPOINT Core;
+ /** Pointer to additional descriptor bytes following what's covered by VUSBDESCENDPOINT. */
+ const void *pvMore;
+ /** Pointer to additional class- or vendor-specific endpoint descriptors. */
+ const void *pvClass;
+ /** Size of class- or vendor-specific descriptors. */
+ uint16_t cbClass;
+ /** Pointer to SuperSpeed endpoint companion descriptor (SS endpoints only). */
+ const void *pvSsepc;
+ /** Size of SuperSpeed endpoint companion descriptor.
+ * @remark Must be non-zero for SuperSpeed endpoints. */
+ uint16_t cbSsepc;
+} VUSBDESCENDPOINTEX;
+/** Pointer to a parsed USB endpoint descriptor. */
+typedef VUSBDESCENDPOINTEX *PVUSBDESCENDPOINTEX;
+/** Pointer to a const parsed USB endpoint descriptor. */
+typedef const VUSBDESCENDPOINTEX *PCVUSBDESCENDPOINTEX;
+
+
+/** @name USB Control message recipient codes (from spec)
+ * @{ */
+#define VUSB_TO_DEVICE 0x0
+#define VUSB_TO_INTERFACE 0x1
+#define VUSB_TO_ENDPOINT 0x2
+#define VUSB_TO_OTHER 0x3
+#define VUSB_RECIP_MASK 0x1f
+/** @} */
+
+/** @name USB control pipe setup packet structure (from spec)
+ * @{ */
+#define VUSB_REQ_SHIFT (5)
+#define VUSB_REQ_STANDARD (0x0 << VUSB_REQ_SHIFT)
+#define VUSB_REQ_CLASS (0x1 << VUSB_REQ_SHIFT)
+#define VUSB_REQ_VENDOR (0x2 << VUSB_REQ_SHIFT)
+#define VUSB_REQ_RESERVED (0x3 << VUSB_REQ_SHIFT)
+#define VUSB_REQ_MASK (0x3 << VUSB_REQ_SHIFT)
+/** @} */
+
+#define VUSB_DIR_TO_DEVICE 0x00
+#define VUSB_DIR_TO_HOST 0x80
+#define VUSB_DIR_MASK 0x80
+
+/**
+ * USB Setup request (from spec)
+ */
+typedef struct vusb_setup
+{
+ uint8_t bmRequestType;
+ uint8_t bRequest;
+ uint16_t wValue;
+ uint16_t wIndex;
+ uint16_t wLength;
+} VUSBSETUP;
+/** Pointer to a setup request. */
+typedef VUSBSETUP *PVUSBSETUP;
+/** Pointer to a const setup request. */
+typedef const VUSBSETUP *PCVUSBSETUP;
+
+/** @name USB Standard device requests (from spec)
+ * @{ */
+#define VUSB_REQ_GET_STATUS 0x00
+#define VUSB_REQ_CLEAR_FEATURE 0x01
+#define VUSB_REQ_SET_FEATURE 0x03
+#define VUSB_REQ_SET_ADDRESS 0x05
+#define VUSB_REQ_GET_DESCRIPTOR 0x06
+#define VUSB_REQ_SET_DESCRIPTOR 0x07
+#define VUSB_REQ_GET_CONFIGURATION 0x08
+#define VUSB_REQ_SET_CONFIGURATION 0x09
+#define VUSB_REQ_GET_INTERFACE 0x0a
+#define VUSB_REQ_SET_INTERFACE 0x0b
+#define VUSB_REQ_SYNCH_FRAME 0x0c
+#define VUSB_REQ_MAX 0x0d
+/** @} */
+
+/** @} */ /* end of grp_vusb_std */
+
+
+
+/** @name USB Standard version flags.
+ * @{ */
+/** Indicates USB 1.1 support. */
+#define VUSB_STDVER_11 RT_BIT(1)
+/** Indicates USB 2.0 support. */
+#define VUSB_STDVER_20 RT_BIT(2)
+/** Indicates USB 3.0 support. */
+#define VUSB_STDVER_30 RT_BIT(3)
+/** @} */
+
+/**
+ * USB port/device speeds.
+ */
+typedef enum VUSBSPEED
+{
+ /** Undetermined/unknown speed. */
+ VUSB_SPEED_UNKNOWN = 0,
+ /** Low-speed (LS), 1.5 Mbit/s, USB 1.0. */
+ VUSB_SPEED_LOW,
+ /** Full-speed (FS), 12 Mbit/s, USB 1.1. */
+ VUSB_SPEED_FULL,
+ /** High-speed (HS), 480 Mbit/s, USB 2.0. */
+ VUSB_SPEED_HIGH,
+ /** Variable speed, wireless USB 2.5. */
+ VUSB_SPEED_VARIABLE,
+ /** SuperSpeed (SS), 5.0 Gbit/s, USB 3.0. */
+ VUSB_SPEED_SUPER,
+ /** SuperSpeed+ (SS+), 10.0 Gbit/s, USB 3.1. */
+ VUSB_SPEED_SUPERPLUS,
+ /** The usual 32-bit hack. */
+ VUSB_SPEED_32BIT_HACK = 0x7fffffff
+} VUSBSPEED;
+
+/**
+ * VUSB transfer direction.
+ */
+typedef enum VUSBDIRECTION
+{
+ /** Setup */
+ VUSBDIRECTION_SETUP = 0,
+#define VUSB_DIRECTION_SETUP VUSBDIRECTION_SETUP
+ /** In - Device to host. */
+ VUSBDIRECTION_IN = 1,
+#define VUSB_DIRECTION_IN VUSBDIRECTION_IN
+ /** Out - Host to device. */
+ VUSBDIRECTION_OUT = 2,
+#define VUSB_DIRECTION_OUT VUSBDIRECTION_OUT
+ /** Invalid direction */
+ VUSBDIRECTION_INVALID = 0x7f
+} VUSBDIRECTION;
+
+/**
+ * VUSB Transfer types.
+ */
+typedef enum VUSBXFERTYPE
+{
+ /** Control message. Used to represent a single control transfer. */
+ VUSBXFERTYPE_CTRL = 0,
+ /* Isochronous transfer. */
+ VUSBXFERTYPE_ISOC,
+ /** Bulk transfer. */
+ VUSBXFERTYPE_BULK,
+ /** Interrupt transfer. */
+ VUSBXFERTYPE_INTR,
+ /** Complete control message. Used to represent an entire control message. */
+ VUSBXFERTYPE_MSG,
+ /** Invalid transfer type. */
+ VUSBXFERTYPE_INVALID = 0x7f
+} VUSBXFERTYPE;
+
+/** Number of valid USB transfer types - KEEP in sync with VUSBXFERTYPE!. */
+#define VUSBXFERTYPE_ELEMENTS (5)
+
+/** Pointer to a VBox USB device interface. */
+typedef struct VUSBIDEVICE *PVUSBIDEVICE;
+
+/** Pointer to a VUSB RootHub port interface. */
+typedef struct VUSBIROOTHUBPORT *PVUSBIROOTHUBPORT;
+
+/** Pointer to an USB request descriptor. */
+typedef struct VUSBURB *PVUSBURB;
+
+
+/**
+ * VUSB device reset completion callback function.
+ * This is called by the reset thread when the reset has been completed.
+ *
+ * @param pDevice Pointer to the virtual USB device core.
+ * @param uPort The port of the device which completed the reset.
+ * @param rc The VBox status code of the reset operation.
+ * @param pvUser User specific argument.
+ *
+ * @thread The reset thread or EMT.
+ */
+typedef DECLCALLBACKTYPE(void, FNVUSBRESETDONE,(PVUSBIDEVICE pDevice, uint32_t uPort, int rc, void *pvUser));
+/** Pointer to a device reset completion callback function (FNUSBRESETDONE). */
+typedef FNVUSBRESETDONE *PFNVUSBRESETDONE;
+
+
+/**
+ * The state of a VUSB Device.
+ *
+ * @remark The order of these states is vital.
+ */
+typedef enum VUSBDEVICESTATE
+{
+ VUSB_DEVICE_STATE_INVALID = 0,
+ VUSB_DEVICE_STATE_DETACHED,
+ VUSB_DEVICE_STATE_ATTACHED,
+ VUSB_DEVICE_STATE_POWERED,
+ VUSB_DEVICE_STATE_DEFAULT,
+ VUSB_DEVICE_STATE_ADDRESS,
+ VUSB_DEVICE_STATE_CONFIGURED,
+ VUSB_DEVICE_STATE_SUSPENDED,
+ /** The device is being reset. Don't mess with it.
+ * Next states: VUSB_DEVICE_STATE_DEFAULT, VUSB_DEVICE_STATE_DESTROYED
+ */
+ VUSB_DEVICE_STATE_RESET,
+ /** The device has been destroyed. */
+ VUSB_DEVICE_STATE_DESTROYED,
+ /** The usual 32-bit hack. */
+ VUSB_DEVICE_STATE_32BIT_HACK = 0x7fffffff
+} VUSBDEVICESTATE;
+
+
+/** Maximum number of USB devices supported. */
+#define VUSB_DEVICES_MAX 128
+/** An invalid device port. */
+#define VUSB_DEVICE_PORT_INVALID UINT32_MAX
+
+/**
+ * VBox USB port bitmap.
+ *
+ * Bit 0 == Port 0, ... , Bit 127 == Port 127.
+ */
+typedef struct VUSBPORTBITMAP
+{
+ /** 128 bits */
+ char ach[VUSB_DEVICES_MAX / 8];
+} VUSBPORTBITMAP;
+/** Pointer to a VBox USB port bitmap. */
+typedef VUSBPORTBITMAP *PVUSBPORTBITMAP;
+AssertCompile(sizeof(VUSBPORTBITMAP) * 8 >= VUSB_DEVICES_MAX);
+
+#ifndef RDESKTOP
+
+/**
+ * The VUSB RootHub port interface provided by the HCI (down).
+ * Pair with VUSBIROOTCONNECTOR
+ */
+typedef struct VUSBIROOTHUBPORT
+{
+ /**
+ * Get the number of available ports in the hub.
+ *
+ * @returns The number of ports available.
+ * @param pInterface Pointer to this structure.
+ * @param pAvailable Bitmap indicating the available ports. Set bit == available port.
+ */
+ DECLR3CALLBACKMEMBER(unsigned, pfnGetAvailablePorts,(PVUSBIROOTHUBPORT pInterface, PVUSBPORTBITMAP pAvailable));
+
+ /**
+ * Gets the supported USB versions.
+ *
+ * @returns The mask of supported USB versions.
+ * @param pInterface Pointer to this structure.
+ */
+ DECLR3CALLBACKMEMBER(uint32_t, pfnGetUSBVersions,(PVUSBIROOTHUBPORT pInterface));
+
+ /**
+ * A device is being attached to a port in the roothub.
+ *
+ * @param pInterface Pointer to this structure.
+ * @param uPort The port number assigned to the device.
+ * @param enmSpeed The speed of the device being attached.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnAttach,(PVUSBIROOTHUBPORT pInterface, uint32_t uPort, VUSBSPEED enmSpeed));
+
+ /**
+ * A device is being detached from a port in the roothub.
+ *
+ * @param pInterface Pointer to this structure.
+ * @param uPort The port number assigned to the device.
+ */
+ DECLR3CALLBACKMEMBER(void, pfnDetach,(PVUSBIROOTHUBPORT pInterface, uint32_t uPort));
+
+ /**
+ * Reset the root hub.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this structure.
+ * @param fResetOnLinux Whether or not to do real reset on linux.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIROOTHUBPORT pInterface, bool fResetOnLinux));
+
+ /**
+ * Transfer completion callback routine.
+ *
+ * VUSB will call this when a transfer have been completed
+ * in a one or another way.
+ *
+ * @param pInterface Pointer to this structure.
+ * @param pUrb Pointer to the URB in question.
+ */
+ DECLR3CALLBACKMEMBER(void, pfnXferCompletion,(PVUSBIROOTHUBPORT pInterface, PVUSBURB pUrb));
+
+ /**
+ * Handle transfer errors.
+ *
+ * VUSB calls this when a transfer attempt failed. This function will respond
+ * indicating whether to retry or complete the URB with failure.
+ *
+ * @returns Retry indicator.
+ * @param pInterface Pointer to this structure.
+ * @param pUrb Pointer to the URB in question.
+ */
+ DECLR3CALLBACKMEMBER(bool, pfnXferError,(PVUSBIROOTHUBPORT pInterface, PVUSBURB pUrb));
+
+ /**
+ * Processes a new frame if periodic frame processing is enabled.
+ *
+ * @returns Flag whether there was activity which influences the frame rate.
+ * @param pInterface Pointer to this structure.
+ * @param u32FrameNo The frame number.
+ */
+ DECLR3CALLBACKMEMBER(bool, pfnStartFrame, (PVUSBIROOTHUBPORT pInterface, uint32_t u32FrameNo));
+
+ /**
+ * Informs the callee about a change in the frame rate due to too many idle cycles or
+ * when seeing activity after some idle time.
+ *
+ * @returns nothing.
+ * @param pInterface Pointer to this structure.
+ * @param u32FrameRate The new frame rate.
+ */
+ DECLR3CALLBACKMEMBER(void, pfnFrameRateChanged, (PVUSBIROOTHUBPORT pInterface, uint32_t u32FrameRate));
+
+ /** Alignment dummy. */
+ RTR3PTR Alignment;
+
+} VUSBIROOTHUBPORT;
+/** VUSBIROOTHUBPORT interface ID. */
+# define VUSBIROOTHUBPORT_IID "2ece01c2-4dbf-4bd5-96ca-09fc14164cd4"
+
+/** Pointer to a VUSB RootHub connector interface. */
+typedef struct VUSBIROOTHUBCONNECTOR *PVUSBIROOTHUBCONNECTOR;
+/**
+ * The VUSB RootHub connector interface provided by the VBox USB RootHub driver
+ * (up).
+ * Pair with VUSBIROOTHUBPORT.
+ */
+typedef struct VUSBIROOTHUBCONNECTOR
+{
+ /**
+ * Sets the URB parameters for the caller.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param cbHci Size of the data private to the HCI for each URB when allocated.
+ * @param cbHciTd Size of one transfer descriptor. The number of transfer descriptors
+ * is given VUSBIROOTHUBCONNECTOR::pfnNewUrb for each URB to calculate the
+ * final amount of memory required for the TDs.
+ *
+ * @note This must be called before starting to allocate any URB or otherwise there will be no
+ * data available for the HCI.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnSetUrbParams, (PVUSBIROOTHUBCONNECTOR pInterface, size_t cbHci, size_t cbHciTd));
+
+ /**
+ * Resets the roothub.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param fResetOnLinux Whether or not to do real reset on linux.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnReset, (PVUSBIROOTHUBCONNECTOR pInterface, bool fResetOnLinux));
+
+ /**
+ * Powers on the roothub.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnPowerOn, (PVUSBIROOTHUBCONNECTOR pInterface));
+
+ /**
+ * Power off the roothub.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnPowerOff, (PVUSBIROOTHUBCONNECTOR pInterface));
+
+ /**
+ * Allocates a new URB for a transfer.
+ *
+ * Either submit using pfnSubmitUrb or free using VUSBUrbFree().
+ *
+ * @returns Pointer to a new URB.
+ * @returns NULL on failure - try again later.
+ * This will not fail if the device wasn't found. We'll fail it
+ * at submit time, since that makes the usage of this api simpler.
+ * @param pInterface Pointer to this struct.
+ * @param DstAddress The destination address of the URB.
+ * @param uPort Optional port of the device the URB is for, use VUSB_DEVICE_PORT_INVALID to indicate to use the destination address.
+ * @param enmType Type of the URB.
+ * @param enmDir Data transfer direction.
+ * @param cbData The amount of data space required.
+ * @param cTds The amount of TD space.
+ * @param pszTag Custom URB tag assigned by the caller, only for
+ * logged builds and optional.
+ *
+ * @note pDev should be NULL in most cases. The only useful case is for USB3 where
+ * it is required for the SET_ADDRESS request because USB3 uses unicast traffic.
+ */
+ DECLR3CALLBACKMEMBER(PVUSBURB, pfnNewUrb,(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t uPort,
+ VUSBXFERTYPE enmType, VUSBDIRECTION enmDir, uint32_t cbData, uint32_t cTds, const char *pszTag));
+
+ /**
+ * Free an URB not submitted yet.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param pUrb Pointer to the URB to free returned by VUSBIROOTHUBCONNECTOR::pfnNewUrb.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnFreeUrb, (PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb));
+
+ /**
+ * Submits a URB for transfer.
+ * The transfer will do asynchronously if possible.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param pUrb Pointer to the URB returned by pfnNewUrb.
+ * The URB will be freed in case of failure.
+ * @param pLed Pointer to USB Status LED
+ */
+ DECLR3CALLBACKMEMBER(int, pfnSubmitUrb,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed));
+
+ /**
+ * Call to service asynchronous URB completions in a polling fashion.
+ *
+ * Reaped URBs will be finished by calling the completion callback,
+ * thus there is no return code or input or anything from this function
+ * except for potential state changes elsewhere.
+ *
+ * @returns VINF_SUCCESS if no URBs are pending upon return.
+ * @returns VERR_TIMEOUT if one or more URBs are still in flight upon returning.
+ * @returns Other VBox status code.
+ *
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to reap URBs on.
+ * @param cMillies Number of milliseconds to poll for completion.
+ */
+ DECLR3CALLBACKMEMBER(void, pfnReapAsyncUrbs,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, RTMSINTERVAL cMillies));
+
+ /**
+ * Cancels and completes - with CRC failure - all URBs queued on an endpoint.
+ * This is done in response to guest URB cancellation.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param pUrb Pointer to a previously submitted URB.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnCancelUrbsEp,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb));
+
+ /**
+ * Cancels and completes - with CRC failure - all in-flight async URBs.
+ * This is typically done before saving a state.
+ *
+ * @param pInterface Pointer to this struct.
+ */
+ DECLR3CALLBACKMEMBER(void, pfnCancelAllUrbs,(PVUSBIROOTHUBCONNECTOR pInterface));
+
+ /**
+ * Cancels and completes - with CRC failure - all URBs queued on an endpoint.
+ * This is done in response to a guest endpoint/pipe abort.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device.
+ * @param EndPt Endpoint number.
+ * @param enmDir Endpoint direction.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnAbortEp,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, int EndPt, VUSBDIRECTION enmDir));
+
+ /**
+ * Attach the device to the root hub.
+ * The device must not be attached to any hub for this call to succeed.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to attach.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
+
+ /**
+ * Detach the device from the root hub.
+ * The device must already be attached for this call to succeed.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to detach.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
+
+ /**
+ * Sets periodic frame processing.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param uFrameRate The target frame rate in Hertz, 0 disables periodic frame processing.
+ * The real frame rate might be lower if there is no activity for a certain period or
+ * higher if there is a need for catching up with where the guest expects the device to be.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnSetPeriodicFrameProcessing, (PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uFrameRate));
+
+ /**
+ * Returns the current frame rate for the periodic frame processing.
+ *
+ * @returns Frame rate for periodic frame processing.
+ * @retval 0 if disabled.
+ * @param pInterface Pointer to this struct.
+ */
+ DECLR3CALLBACKMEMBER(uint32_t, pfnGetPeriodicFrameRate, (PVUSBIROOTHUBCONNECTOR pInterface));
+
+ /**
+ * Updates the internally stored isochronous scheduling frame for a given
+ * endpoint and returns the delta between the current and previous frame.
+ *
+ * @returns Delta between currently and previously scheduled frame.
+ * @retval 0 if no previous frame was set.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device.
+ * @param EndPt Endpoint number.
+ * @param enmDir Endpoint direction.
+ * @param uNewFrameID The frame ID of a new transfer.
+ * @param uBits The number of significant bits in frame ID.
+ */
+ DECLR3CALLBACKMEMBER(uint32_t, pfnUpdateIsocFrameDelta, (PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort,
+ int EndPt, VUSBDIRECTION enmDir, uint16_t uNewFrameID, uint8_t uBits));
+
+ /**
+ * Resets the device.
+ *
+ * Since a device reset shall take at least 10ms from the guest point of view,
+ * it must be performed asynchronously. We create a thread which performs this
+ * operation and ensures it will take at least 10ms.
+ *
+ * At times - like init - a synchronous reset is required, this can be done
+ * by passing NULL for pfnDone.
+ *
+ * -- internal stuff, move it --
+ * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
+ * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
+ * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
+ * -- internal stuff, move it --
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to reset.
+ * @param fResetOnLinux Set if we can permit a real reset and a potential logical
+ * device reconnect on linux hosts.
+ * @param pfnDone Pointer to the completion routine. If NULL a synchronous
+ * reset is performed not respecting the 10ms.
+ * @param pvUser User argument to the completion routine.
+ * @param pVM The cross context VM structure. Required if pfnDone
+ * is not NULL.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnDevReset,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, bool fResetOnLinux,
+ PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM));
+
+ /**
+ * Powers on the device.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to power on.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnDevPowerOn,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
+
+ /**
+ * Powers off the device.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to power off.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnDevPowerOff,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
+
+ /**
+ * Get the state of the device.
+ *
+ * @returns Device state.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to get the state for.
+ */
+ DECLR3CALLBACKMEMBER(VUSBDEVICESTATE, pfnDevGetState,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
+
+ /**
+ * Returns whether the device implements the saved state handlers
+ * and doesn't need to get detached.
+ *
+ * @returns true if the device supports saving the state, false otherwise.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to query saved state support for.
+ */
+ DECLR3CALLBACKMEMBER(bool, pfnDevIsSavedStateSupported,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
+
+ /**
+ * Get the speed the device is operating at.
+ *
+ * @returns Device state.
+ * @param pInterface Pointer to this struct.
+ * @param uPort Port of the device to query the speed for.
+ */
+ DECLR3CALLBACKMEMBER(VUSBSPEED, pfnDevGetSpeed,(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort));
+
+} VUSBIROOTHUBCONNECTOR;
+AssertCompileSizeAlignment(VUSBIROOTHUBCONNECTOR, 8);
+/** VUSBIROOTHUBCONNECTOR interface ID. */
+# define VUSBIROOTHUBCONNECTOR_IID "662d7822-b9c6-43b5-88b6-5d59f0106e46"
+
+
+# ifdef IN_RING3
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSetUrbParams */
+DECLINLINE(int) VUSBIRhSetUrbParams(PVUSBIROOTHUBCONNECTOR pInterface, size_t cbHci, size_t cbHciTd)
+{
+ return pInterface->pfnSetUrbParams(pInterface, cbHci, cbHciTd);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnNewUrb */
+DECLINLINE(PVUSBURB) VUSBIRhNewUrb(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t uPort,
+ VUSBXFERTYPE enmType, VUSBDIRECTION enmDir, uint32_t cbData, uint32_t cTds, const char *pszTag)
+{
+ return pInterface->pfnNewUrb(pInterface, DstAddress, uPort, enmType, enmDir, cbData, cTds, pszTag);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnFreeUrb */
+DECLINLINE(int) VUSBIRhFreeUrb(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb)
+{
+ return pInterface->pfnFreeUrb(pInterface, pUrb);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSubmitUrb */
+DECLINLINE(int) VUSBIRhSubmitUrb(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed)
+{
+ return pInterface->pfnSubmitUrb(pInterface, pUrb, pLed);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnReapAsyncUrbs */
+DECLINLINE(void) VUSBIRhReapAsyncUrbs(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, RTMSINTERVAL cMillies)
+{
+ pInterface->pfnReapAsyncUrbs(pInterface, uPort, cMillies);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnCancelAllUrbs */
+DECLINLINE(void) VUSBIRhCancelAllUrbs(PVUSBIROOTHUBCONNECTOR pInterface)
+{
+ pInterface->pfnCancelAllUrbs(pInterface);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnAttachDevice */
+DECLINLINE(int) VUSBIRhAttachDevice(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
+{
+ return pInterface->pfnAttachDevice(pInterface, uPort);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDetachDevice */
+DECLINLINE(int) VUSBIRhDetachDevice(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
+{
+ return pInterface->pfnDetachDevice(pInterface, uPort);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSetPeriodicFrameProcessing */
+DECLINLINE(int) VUSBIRhSetPeriodicFrameProcessing(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uFrameRate)
+{
+ return pInterface->pfnSetPeriodicFrameProcessing(pInterface, uFrameRate);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnGetPeriodicFrameRate */
+DECLINLINE(uint32_t) VUSBIRhGetPeriodicFrameRate(PVUSBIROOTHUBCONNECTOR pInterface)
+{
+ return pInterface->pfnGetPeriodicFrameRate(pInterface);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevReset */
+DECLINLINE(int) VUSBIRhDevReset(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort, bool fResetOnLinux,
+ PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
+{
+ return pInterface->pfnDevReset(pInterface, uPort, fResetOnLinux, pfnDone, pvUser, pVM);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevPowerOn */
+DECLINLINE(int) VUSBIRhDevPowerOn(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
+{
+ return pInterface->pfnDevPowerOn(pInterface, uPort);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevPowerOff */
+DECLINLINE(int) VUSBIRhDevPowerOff(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
+{
+ return pInterface->pfnDevPowerOff(pInterface, uPort);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevGetState */
+DECLINLINE(VUSBDEVICESTATE) VUSBIRhDevGetState(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
+{
+ return pInterface->pfnDevGetState(pInterface, uPort);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevGetState */
+DECLINLINE(bool) VUSBIRhDevIsSavedStateSupported(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
+{
+ return pInterface->pfnDevIsSavedStateSupported(pInterface, uPort);
+}
+
+/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDevGetSpeed */
+DECLINLINE(VUSBSPEED) VUSBIRhDevGetSpeed(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t uPort)
+{
+ return pInterface->pfnDevGetSpeed(pInterface, uPort);
+}
+# endif /* IN_RING3 */
+
+#endif /* ! RDESKTOP */
+
+
+#ifndef RDESKTOP
+
+/**
+ * USB Device Interface (up).
+ * No interface pair.
+ */
+typedef struct VUSBIDEVICE
+{
+ /**
+ * Resets the device.
+ *
+ * Since a device reset shall take at least 10ms from the guest point of view,
+ * it must be performed asynchronously. We create a thread which performs this
+ * operation and ensures it will take at least 10ms.
+ *
+ * At times - like init - a synchronous reset is required, this can be done
+ * by passing NULL for pfnDone.
+ *
+ * -- internal stuff, move it --
+ * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
+ * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
+ * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
+ * -- internal stuff, move it --
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to this structure.
+ * @param fResetOnLinux Set if we can permit a real reset and a potential logical
+ * device reconnect on linux hosts.
+ * @param pfnDone Pointer to the completion routine. If NULL a synchronous
+ * reset is performed not respecting the 10ms.
+ * @param pvUser User argument to the completion routine.
+ * @param pVM The cross context VM structure. Required if pfnDone
+ * is not NULL.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIDEVICE pInterface, bool fResetOnLinux,
+ PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM));
+
+ /**
+ * Powers on the device.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to the device interface structure.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnPowerOn,(PVUSBIDEVICE pInterface));
+
+ /**
+ * Powers off the device.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to the device interface structure.
+ */
+ DECLR3CALLBACKMEMBER(int, pfnPowerOff,(PVUSBIDEVICE pInterface));
+
+ /**
+ * Get the state of the device.
+ *
+ * @returns Device state.
+ * @param pInterface Pointer to the device interface structure.
+ */
+ DECLR3CALLBACKMEMBER(VUSBDEVICESTATE, pfnGetState,(PVUSBIDEVICE pInterface));
+
+ /**
+ * Returns whether the device implements the saved state handlers
+ * and doesn't need to get detached.
+ *
+ * @returns true if the device supports saving the state, false otherwise.
+ * @param pInterface Pointer to the device interface structure.
+ */
+ DECLR3CALLBACKMEMBER(bool, pfnIsSavedStateSupported,(PVUSBIDEVICE pInterface));
+
+ /**
+ * Get the speed the device is operating at.
+ *
+ * @returns Device state.
+ * @param pInterface Pointer to the device interface structure.
+ */
+ DECLR3CALLBACKMEMBER(VUSBSPEED, pfnGetSpeed,(PVUSBIDEVICE pInterface));
+
+} VUSBIDEVICE;
+/** VUSBIDEVICE interface ID. */
+# define VUSBIDEVICE_IID "af576b38-e8ca-4db7-810a-2596d8d57ca0"
+
+
+# ifdef IN_RING3
+/**
+ * Resets the device.
+ *
+ * Since a device reset shall take at least 10ms from the guest point of view,
+ * it must be performed asynchronously. We create a thread which performs this
+ * operation and ensures it will take at least 10ms.
+ *
+ * At times - like init - a synchronous reset is required, this can be done
+ * by passing NULL for pfnDone.
+ *
+ * -- internal stuff, move it --
+ * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
+ * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
+ * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
+ * -- internal stuff, move it --
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to the device interface structure.
+ * @param fResetOnLinux Set if we can permit a real reset and a potential logical
+ * device reconnect on linux hosts.
+ * @param pfnDone Pointer to the completion routine. If NULL a
+ * synchronous reset is performed not respecting the
+ * 10ms.
+ * @param pvUser User argument to the completion routine.
+ * @param pVM The cross context VM structure. Required if pfnDone
+ * is not NULL.
+ *
+ * NULL is acceptable Required if callback in EMT is desired, NULL is otherwise
+ * acceptable.
+ */
+DECLINLINE(int) VUSBIDevReset(PVUSBIDEVICE pInterface, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
+{
+ return pInterface->pfnReset(pInterface, fResetOnLinux, pfnDone, pvUser, pVM);
+}
+
+/**
+ * Powers on the device.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to the device interface structure.
+ */
+DECLINLINE(int) VUSBIDevPowerOn(PVUSBIDEVICE pInterface)
+{
+ return pInterface->pfnPowerOn(pInterface);
+}
+
+/**
+ * Powers off the device.
+ *
+ * @returns VBox status code.
+ * @param pInterface Pointer to the device interface structure.
+ */
+DECLINLINE(int) VUSBIDevPowerOff(PVUSBIDEVICE pInterface)
+{
+ return pInterface->pfnPowerOff(pInterface);
+}
+
+/**
+ * Get the state of the device.
+ *
+ * @returns Device state.
+ * @param pInterface Pointer to the device interface structure.
+ */
+DECLINLINE(VUSBDEVICESTATE) VUSBIDevGetState(PVUSBIDEVICE pInterface)
+{
+ return pInterface->pfnGetState(pInterface);
+}
+
+/**
+ * @copydoc VUSBIDEVICE::pfnIsSavedStateSupported
+ */
+DECLINLINE(bool) VUSBIDevIsSavedStateSupported(PVUSBIDEVICE pInterface)
+{
+ return pInterface->pfnIsSavedStateSupported(pInterface);
+}
+# endif /* IN_RING3 */
+
+#endif /* ! RDESKTOP */
+
+/** @name URB
+ * @{ */
+
+/**
+ * VUSB Transfer status codes.
+ */
+typedef enum VUSBSTATUS
+{
+ /** Transer was ok. */
+ VUSBSTATUS_OK = 0,
+ /** Transfer stalled, endpoint halted. */
+ VUSBSTATUS_STALL,
+ /** Device not responding. */
+ VUSBSTATUS_DNR,
+ /** CRC error. */
+ VUSBSTATUS_CRC,
+ /** Data underrun error. */
+ VUSBSTATUS_DATA_UNDERRUN,
+ /** Data overrun error. */
+ VUSBSTATUS_DATA_OVERRUN,
+ /** The isochronous buffer hasn't been touched. */
+ VUSBSTATUS_NOT_ACCESSED,
+ /** Canceled/undone URB (VUSB internal). */
+ VUSBSTATUS_UNDO,
+ /** Canceled URB. */
+ VUSBSTATUS_CANCELED,
+ /** Invalid status. */
+ VUSBSTATUS_INVALID = 0x7f
+} VUSBSTATUS;
+
+
+/**
+ * The URB states
+ */
+typedef enum VUSBURBSTATE
+{
+ /** The usual invalid state. */
+ VUSBURBSTATE_INVALID = 0,
+ /** The URB is free, i.e. not in use.
+ * Next state: ALLOCATED */
+ VUSBURBSTATE_FREE,
+ /** The URB is allocated, i.e. being prepared for submission.
+ * Next state: FREE, IN_FLIGHT */
+ VUSBURBSTATE_ALLOCATED,
+ /** The URB is in flight.
+ * Next state: REAPED, CANCELLED */
+ VUSBURBSTATE_IN_FLIGHT,
+ /** The URB has been reaped and is being completed.
+ * Next state: FREE */
+ VUSBURBSTATE_REAPED,
+ /** The URB has been cancelled and is awaiting reaping and immediate freeing.
+ * Next state: FREE */
+ VUSBURBSTATE_CANCELLED,
+ /** The end of the valid states (exclusive). */
+ VUSBURBSTATE_END,
+ /** The usual 32-bit blow up. */
+ VUSBURBSTATE_32BIT_HACK = 0x7fffffff
+} VUSBURBSTATE;
+
+
+/**
+ * Information about a isochronous packet.
+ */
+typedef struct VUSBURBISOCPKT
+{
+ /** The size of the packet.
+ * IN: The packet size. I.e. the number of bytes to the next packet or end of buffer.
+ * OUT: The actual size transferred. */
+ uint32_t cb;
+ /** The offset of the packet. (Relative to VUSBURB::abData[0].)
+ * OUT: This can be changed by the USB device if it does some kind of buffer squeezing. */
+ uint32_t off;
+ /** The status of the transfer.
+ * IN: VUSBSTATUS_INVALID
+ * OUT: VUSBSTATUS_INVALID if nothing was done, otherwise the correct status. */
+ VUSBSTATUS enmStatus;
+} VUSBURBISOCPKT;
+/** Pointer to a isochronous packet. */
+typedef VUSBURBISOCPKT *PVUSBURBISOCPTK;
+/** Pointer to a const isochronous packet. */
+typedef const VUSBURBISOCPKT *PCVUSBURBISOCPKT;
+
+/** Private controller emulation specific data for the associated USB request descriptor. */
+typedef struct VUSBURBHCIINT *PVUSBURBHCI;
+/** Private controller emulation specific TD data. */
+typedef struct VUSBURBHCITDINT *PVUSBURBHCITD;
+/** Private VUSB/roothub related state for the associated URB. */
+typedef struct VUSBURBVUSBINT *PVUSBURBVUSB;
+
+/**
+ * Asynchronous USB request descriptor
+ */
+typedef struct VUSBURB
+{
+ /** URB magic value. */
+ uint32_t u32Magic;
+ /** The USR state. */
+ VUSBURBSTATE enmState;
+ /** Flag whether the URB is about to be completed,
+ * either by the I/O thread or the cancellation worker.
+ */
+ volatile bool fCompleting;
+ /** URB description, can be null. intended for logging. */
+ char *pszDesc;
+
+#ifdef RDESKTOP
+ /** The next URB in rdesktop-vrdp's linked list */
+ PVUSBURB pNext;
+ /** The previous URB in rdesktop-vrdp's linked list */
+ PVUSBURB pPrev;
+ /** The vrdp handle for the URB */
+ uint32_t handle;
+ /** Pointer used to find the usb proxy device */
+ struct VUSBDEV *pDev;
+#endif
+
+ /** The VUSB stack private data. */
+ PVUSBURBVUSB pVUsb;
+ /** Private host controller data associated with this URB. */
+ PVUSBURBHCI pHci;
+ /** Pointer to the host controller transfer descriptor array. */
+ PVUSBURBHCITD paTds;
+
+ /** The device data. */
+ struct VUSBURBDEV
+ {
+ /** Pointer to private device specific data. */
+ void *pvPrivate;
+ /** Used by the device when linking the URB in some list of its own. */
+ PVUSBURB pNext;
+ } Dev;
+
+ /** The device address.
+ * This is set at allocation time. */
+ uint8_t DstAddress;
+
+ /** The endpoint.
+ * IN: Must be set before submitting the URB.
+ * @remark This does not have the high bit (direction) set! */
+ uint8_t EndPt;
+ /** The transfer type.
+ * IN: Set at allocation time. */
+ VUSBXFERTYPE enmType;
+ /** The transfer direction.
+ * IN: Set at allocation time. */
+ VUSBDIRECTION enmDir;
+ /** Indicates whether it is OK to receive/send less data than requested.
+ * IN: Must be initialized before submitting the URB. */
+ bool fShortNotOk;
+ /** The transfer status.
+ * OUT: This is set when reaping the URB. */
+ VUSBSTATUS enmStatus;
+
+ /** The relative starting frame for isochronous transfers.
+ * Zero indicates "transfer ASAP".
+ * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
+ uint16_t uStartFrameDelta;
+ /** Flag indicating whether the start frame delta is relative
+ * to the previous transfer (false) or now (true).
+ * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
+ bool fStartRelToNow;
+ /** The number of isochronous packets describe in aIsocPkts.
+ * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
+ uint8_t cIsocPkts;
+ /** The iso packets within abData.
+ * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
+ VUSBURBISOCPKT aIsocPkts[8];
+
+ /** The message length.
+ * IN: The amount of data to send / receive - set at allocation time.
+ * OUT: The amount of data sent / received. */
+ uint32_t cbData;
+ /** The message data.
+ * IN: On host to device transfers, the data to send.
+ * OUT: On device to host transfers, the data to received.
+ * This array has actually a size of VUsb.cbDataAllocated, not 8KB! */
+ uint8_t abData[8*_1K];
+} VUSBURB;
+
+/** The magic value of a valid VUSBURB. (Murakami Haruki) */
+#define VUSBURB_MAGIC UINT32_C(0x19490112)
+
+/** @} */
+
+
+/** @} */
+
+RT_C_DECLS_END
+
+#endif /* !VBOX_INCLUDED_vusb_h */