VirtualBox

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

Last change on this file since 78307 was 76585, checked in by vboxsync, 6 years ago

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