VirtualBox

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

Last change on this file since 55966 was 54557, checked in by vboxsync, 10 years ago

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