[1] | 1 | /** @file
|
---|
[21217] | 2 | * USB - Universal Serial Bus. (DEV,Main?)
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[98103] | 6 | * Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
---|
[1] | 7 | *
|
---|
[96407] | 8 | * This file is part of VirtualBox base platform packages, as
|
---|
| 9 | * available from https://www.virtualbox.org.
|
---|
[5999] | 10 | *
|
---|
[96407] | 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 | *
|
---|
[5999] | 24 | * The contents of this file may alternatively be used under the terms
|
---|
| 25 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 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
|
---|
[5999] | 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.
|
---|
[96407] | 32 | *
|
---|
| 33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[1] | 34 | */
|
---|
| 35 |
|
---|
[76558] | 36 | #ifndef VBOX_INCLUDED_usb_h
|
---|
| 37 | #define VBOX_INCLUDED_usb_h
|
---|
[76507] | 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 39 | # pragma once
|
---|
| 40 | #endif
|
---|
[1] | 41 |
|
---|
| 42 | #include <VBox/types.h>
|
---|
| 43 |
|
---|
[20374] | 44 | RT_C_DECLS_BEGIN
|
---|
[1] | 45 |
|
---|
[58110] | 46 | /** @defgroup grp_usblib_usb USB Device Structures & Types
|
---|
| 47 | * @ingroup grp_usblib
|
---|
| 48 | * @{
|
---|
| 49 | */
|
---|
| 50 |
|
---|
[1] | 51 | /**
|
---|
| 52 | * The USB host device state.
|
---|
| 53 | */
|
---|
| 54 | typedef enum USBDEVICESTATE
|
---|
| 55 | {
|
---|
| 56 | /** The device is unsupported. */
|
---|
| 57 | USBDEVICESTATE_UNSUPPORTED = 1,
|
---|
| 58 | /** The device is in use by the host. */
|
---|
| 59 | USBDEVICESTATE_USED_BY_HOST,
|
---|
| 60 | /** The device is in use by the host but could perhaps be captured even so. */
|
---|
| 61 | USBDEVICESTATE_USED_BY_HOST_CAPTURABLE,
|
---|
| 62 | /** The device is not used by the host or any guest. */
|
---|
| 63 | USBDEVICESTATE_UNUSED,
|
---|
| 64 | /** The device is held by the proxy for later guest usage. */
|
---|
| 65 | USBDEVICESTATE_HELD_BY_PROXY,
|
---|
| 66 | /** The device in use by a guest. */
|
---|
| 67 | USBDEVICESTATE_USED_BY_GUEST,
|
---|
| 68 | /** The usual 32-bit hack. */
|
---|
| 69 | USBDEVICESTATE_32BIT_HACK = 0x7fffffff
|
---|
| 70 | } USBDEVICESTATE;
|
---|
| 71 |
|
---|
| 72 |
|
---|
| 73 | /**
|
---|
[7745] | 74 | * The USB device speed.
|
---|
| 75 | */
|
---|
| 76 | typedef enum USBDEVICESPEED
|
---|
| 77 | {
|
---|
| 78 | /** Unknown. */
|
---|
| 79 | USBDEVICESPEED_UNKNOWN = 0,
|
---|
| 80 | /** Low speed (1.5 Mbit/s). */
|
---|
| 81 | USBDEVICESPEED_LOW,
|
---|
| 82 | /** Full speed (12 Mbit/s). */
|
---|
| 83 | USBDEVICESPEED_FULL,
|
---|
| 84 | /** High speed (480 Mbit/s). */
|
---|
| 85 | USBDEVICESPEED_HIGH,
|
---|
| 86 | /** Variable speed - USB 2.5 / wireless. */
|
---|
| 87 | USBDEVICESPEED_VARIABLE,
|
---|
[52743] | 88 | /** Super speed - USB 3.0 (5Gbit/s). */
|
---|
| 89 | USBDEVICESPEED_SUPER,
|
---|
[7745] | 90 | /** The usual 32-bit hack. */
|
---|
| 91 | USBDEVICESPEED_32BIT_HACK = 0x7fffffff
|
---|
| 92 | } USBDEVICESPEED;
|
---|
| 93 |
|
---|
| 94 |
|
---|
| 95 | /**
|
---|
[1] | 96 | * USB host device description.
|
---|
| 97 | * Used for enumeration of USB devices.
|
---|
| 98 | */
|
---|
| 99 | typedef struct USBDEVICE
|
---|
| 100 | {
|
---|
[8539] | 101 | /** If linked, this is the pointer to the next device in the list. */
|
---|
| 102 | struct USBDEVICE *pNext;
|
---|
| 103 | /** If linked doubly, this is the pointer to the prev device in the list. */
|
---|
| 104 | struct USBDEVICE *pPrev;
|
---|
| 105 | /** Manufacturer string. */
|
---|
| 106 | const char *pszManufacturer;
|
---|
| 107 | /** Product string. */
|
---|
| 108 | const char *pszProduct;
|
---|
| 109 | /** Serial number string. */
|
---|
| 110 | const char *pszSerialNumber;
|
---|
| 111 | /** The address of the device. */
|
---|
| 112 | const char *pszAddress;
|
---|
[59117] | 113 | /** The backend to use for this device. */
|
---|
| 114 | const char *pszBackend;
|
---|
[8539] | 115 |
|
---|
| 116 | /** Vendor ID. */
|
---|
| 117 | uint16_t idVendor;
|
---|
| 118 | /** Product ID. */
|
---|
| 119 | uint16_t idProduct;
|
---|
| 120 | /** Revision, integer part. */
|
---|
| 121 | uint16_t bcdDevice;
|
---|
[1] | 122 | /** USB version number. */
|
---|
| 123 | uint16_t bcdUSB;
|
---|
| 124 | /** Device class. */
|
---|
| 125 | uint8_t bDeviceClass;
|
---|
| 126 | /** Device subclass. */
|
---|
| 127 | uint8_t bDeviceSubClass;
|
---|
| 128 | /** Device protocol */
|
---|
| 129 | uint8_t bDeviceProtocol;
|
---|
| 130 | /** Number of configurations. */
|
---|
| 131 | uint8_t bNumConfigurations;
|
---|
| 132 | /** The device state. */
|
---|
| 133 | USBDEVICESTATE enmState;
|
---|
[7745] | 134 | /** The device speed. */
|
---|
| 135 | USBDEVICESPEED enmSpeed;
|
---|
[8539] | 136 | /** Serial hash. */
|
---|
| 137 | uint64_t u64SerialHash;
|
---|
[1] | 138 | /** The USB Bus number. */
|
---|
| 139 | uint8_t bBus;
|
---|
[8539] | 140 | /** The port number. */
|
---|
| 141 | uint8_t bPort;
|
---|
[81667] | 142 | /** The hub+port path. */
|
---|
| 143 | char *pszPortPath;
|
---|
[29766] | 144 | #if defined(RT_OS_LINUX) || defined(RT_OS_FREEBSD)
|
---|
[1] | 145 | /** Device number. */
|
---|
| 146 | uint8_t bDevNum;
|
---|
[8539] | 147 | #endif
|
---|
[8545] | 148 | #ifdef RT_OS_WINDOWS
|
---|
| 149 | /** Alternate address. Can be NULL. */
|
---|
| 150 | char *pszAltAddress;
|
---|
| 151 | /** The hub name. */
|
---|
| 152 | char *pszHubName;
|
---|
| 153 | #endif
|
---|
[9158] | 154 | #ifdef RT_OS_SOLARIS
|
---|
| 155 | /** The /devices path of the device. */
|
---|
| 156 | char *pszDevicePath;
|
---|
[13452] | 157 | /** Do we have a partial or full device descriptor here. */
|
---|
| 158 | bool fPartialDescriptor;
|
---|
[9158] | 159 | #endif
|
---|
[1] | 160 | } USBDEVICE;
|
---|
| 161 | /** Pointer to a USB device. */
|
---|
| 162 | typedef USBDEVICE *PUSBDEVICE;
|
---|
| 163 | /** Pointer to a const USB device. */
|
---|
| 164 | typedef USBDEVICE *PCUSBDEVICE;
|
---|
| 165 |
|
---|
[5650] | 166 |
|
---|
| 167 | #ifdef VBOX_USB_H_INCL_DESCRIPTORS /* for the time being, since this may easily conflict with system headers */
|
---|
| 168 |
|
---|
| 169 | /**
|
---|
| 170 | * USB device descriptor.
|
---|
| 171 | */
|
---|
| 172 | #pragma pack(1)
|
---|
| 173 | typedef struct USBDESCHDR
|
---|
| 174 | {
|
---|
| 175 | /** The descriptor length. */
|
---|
| 176 | uint8_t bLength;
|
---|
| 177 | /** The descriptor type. */
|
---|
| 178 | uint8_t bDescriptorType;
|
---|
| 179 | } USBDESCHDR;
|
---|
| 180 | #pragma pack()
|
---|
| 181 | /** Pointer to an USB descriptor header. */
|
---|
| 182 | typedef USBDESCHDR *PUSBDESCHDR;
|
---|
| 183 |
|
---|
| 184 | /** @name Descriptor Type values (bDescriptorType)
|
---|
| 185 | * {@ */
|
---|
| 186 | #if !defined(USB_DT_DEVICE) && !defined(USB_DT_ENDPOINT)
|
---|
| 187 | # define USB_DT_DEVICE 0x01
|
---|
| 188 | # define USB_DT_CONFIG 0x02
|
---|
| 189 | # define USB_DT_STRING 0x03
|
---|
| 190 | # define USB_DT_INTERFACE 0x04
|
---|
| 191 | # define USB_DT_ENDPOINT 0x05
|
---|
| 192 |
|
---|
| 193 | # define USB_DT_HID 0x21
|
---|
| 194 | # define USB_DT_REPORT 0x22
|
---|
| 195 | # define USB_DT_PHYSICAL 0x23
|
---|
| 196 | # define USB_DT_HUB 0x29
|
---|
[7745] | 197 | #endif
|
---|
[5650] | 198 | /** @} */
|
---|
| 199 |
|
---|
| 200 |
|
---|
| 201 | /**
|
---|
| 202 | * USB device descriptor.
|
---|
| 203 | */
|
---|
| 204 | #pragma pack(1)
|
---|
| 205 | typedef struct USBDEVICEDESC
|
---|
| 206 | {
|
---|
| 207 | /** The descriptor length. (Usually sizeof(USBDEVICEDESC).) */
|
---|
| 208 | uint8_t bLength;
|
---|
| 209 | /** The descriptor type. (USB_DT_DEVICE) */
|
---|
| 210 | uint8_t bDescriptorType;
|
---|
| 211 | /** USB version number. */
|
---|
| 212 | uint16_t bcdUSB;
|
---|
| 213 | /** Device class. */
|
---|
| 214 | uint8_t bDeviceClass;
|
---|
| 215 | /** Device subclass. */
|
---|
| 216 | uint8_t bDeviceSubClass;
|
---|
| 217 | /** Device protocol */
|
---|
| 218 | uint8_t bDeviceProtocol;
|
---|
| 219 | /** The max packet size of the default control pipe. */
|
---|
| 220 | uint8_t bMaxPacketSize0;
|
---|
| 221 | /** Vendor ID. */
|
---|
| 222 | uint16_t idVendor;
|
---|
| 223 | /** Product ID. */
|
---|
| 224 | uint16_t idProduct;
|
---|
| 225 | /** Revision, integer part. */
|
---|
| 226 | uint16_t bcdDevice;
|
---|
| 227 | /** Manufacturer string index. */
|
---|
| 228 | uint8_t iManufacturer;
|
---|
| 229 | /** Product string index. */
|
---|
| 230 | uint8_t iProduct;
|
---|
| 231 | /** Serial number string index. */
|
---|
| 232 | uint8_t iSerialNumber;
|
---|
| 233 | /** Number of configurations. */
|
---|
| 234 | uint8_t bNumConfigurations;
|
---|
| 235 | } USBDEVICEDESC;
|
---|
| 236 | #pragma pack()
|
---|
| 237 | /** Pointer to an USB device descriptor. */
|
---|
| 238 | typedef USBDEVICEDESC *PUSBDEVICEDESC;
|
---|
| 239 |
|
---|
| 240 | /** @name Class codes (bDeviceClass)
|
---|
| 241 | * @{ */
|
---|
| 242 | #ifndef USB_HUB_CLASSCODE
|
---|
| 243 | # define USB_HUB_CLASSCODE 0x09
|
---|
| 244 | #endif
|
---|
| 245 | /** @} */
|
---|
| 246 |
|
---|
| 247 | /**
|
---|
| 248 | * USB configuration descriptor.
|
---|
| 249 | */
|
---|
| 250 | #pragma pack(1)
|
---|
| 251 | typedef struct USBCONFIGDESC
|
---|
| 252 | {
|
---|
| 253 | /** The descriptor length. (Usually sizeof(USBCONFIGDESC).) */
|
---|
| 254 | uint8_t bLength;
|
---|
| 255 | /** The descriptor type. (USB_DT_CONFIG) */
|
---|
| 256 | uint8_t bDescriptorType;
|
---|
| 257 | /** The length of the configuration descriptor plus all associated descriptors. */
|
---|
| 258 | uint16_t wTotalLength;
|
---|
| 259 | /** Number of interfaces. */
|
---|
| 260 | uint8_t bNumInterfaces;
|
---|
| 261 | /** Configuration number. (For SetConfiguration().) */
|
---|
| 262 | uint8_t bConfigurationValue;
|
---|
| 263 | /** Configuration description string. */
|
---|
| 264 | uint8_t iConfiguration;
|
---|
| 265 | /** Configuration characteristics. */
|
---|
| 266 | uint8_t bmAttributes;
|
---|
| 267 | /** Maximum power consumption of the USB device in this config. */
|
---|
| 268 | uint8_t MaxPower;
|
---|
| 269 | } USBCONFIGDESC;
|
---|
| 270 | #pragma pack()
|
---|
| 271 | /** Pointer to an USB configuration descriptor. */
|
---|
| 272 | typedef USBCONFIGDESC *PUSBCONFIGDESC;
|
---|
| 273 |
|
---|
| 274 | #endif /* VBOX_USB_H_INCL_DESCRIPTORS */
|
---|
| 275 |
|
---|
[58110] | 276 | /** @} */
|
---|
[20374] | 277 | RT_C_DECLS_END
|
---|
[1] | 278 |
|
---|
[76585] | 279 | #endif /* !VBOX_INCLUDED_usb_h */
|
---|
[5650] | 280 |
|
---|