VirtualBox

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

Last change on this file since 15075 was 15075, checked in by vboxsync, 15 years ago

Added interfaces for shared USB timer, currently mostly disabled.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 33.9 KB
Line 
1/** @file
2 * VUSB - VirtualBox USB.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___VBox_vusb_h
31#define ___VBox_vusb_h
32
33#include <VBox/cdefs.h>
34#include <VBox/types.h>
35
36__BEGIN_DECLS
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/** @} */
60
61/** @name USB Descriptor minimum sizes (from spec)
62 * @{ */
63#define VUSB_DT_DEVICE_MIN_LEN 18
64#define VUSB_DT_CONFIG_MIN_LEN 9
65#define VUSB_DT_CONFIG_STRING_MIN_LEN 2
66#define VUSB_DT_INTERFACE_MIN_LEN 9
67#define VUSB_DT_ENDPOINT_MIN_LEN 7
68/** @} */
69
70
71#pragma pack(1) /* ensure byte packing of the descriptors. */
72
73/**
74 * USB language id descriptor (from specs).
75 */
76typedef struct VUSBDESCLANGID
77{
78 uint8_t bLength;
79 uint8_t bDescriptorType;
80} VUSBDESCLANGID;
81/** Pointer to a USB language id descriptor. */
82typedef VUSBDESCLANGID *PVUSBDESCLANGID;
83/** Pointer to a const USB language id descriptor. */
84typedef const VUSBDESCLANGID *PCVUSBDESCLANGID;
85
86
87/**
88 * USB string descriptor (from specs).
89 */
90typedef struct VUSBDESCSTRING
91{
92 uint8_t bLength;
93 uint8_t bDescriptorType;
94} VUSBDESCSTRING;
95/** Pointer to a USB string descriptor. */
96typedef VUSBDESCSTRING *PVUSBDESCSTRING;
97/** Pointer to a const USB string descriptor. */
98typedef const VUSBDESCSTRING *PCVUSBDESCSTRING;
99
100
101/**
102 * USB device descriptor (from spec)
103 */
104typedef struct VUSBDESCDEVICE
105{
106 uint8_t bLength;
107 uint8_t bDescriptorType;
108 uint16_t bcdUSB;
109 uint8_t bDeviceClass;
110 uint8_t bDeviceSubClass;
111 uint8_t bDeviceProtocol;
112 uint8_t bMaxPacketSize0;
113 uint16_t idVendor;
114 uint16_t idProduct;
115 uint16_t bcdDevice;
116 uint8_t iManufacturer;
117 uint8_t iProduct;
118 uint8_t iSerialNumber;
119 uint8_t bNumConfigurations;
120} VUSBDESCDEVICE;
121/** Pointer to a USB device descriptor. */
122typedef VUSBDESCDEVICE *PVUSBDESCDEVICE;
123/** Pointer to a const USB device descriptor. */
124typedef const VUSBDESCDEVICE *PCVUSBDESCDEVICE;
125
126
127/**
128 * USB configuration descriptor (from spec).
129 */
130typedef struct VUSBDESCCONFIG
131{
132 uint8_t bLength;
133 uint8_t bDescriptorType;
134 uint16_t wTotalLength; /**< recalculated by VUSB when involved in URB. */
135 uint8_t bNumInterfaces;
136 uint8_t bConfigurationValue;
137 uint8_t iConfiguration;
138 uint8_t bmAttributes;
139 uint8_t MaxPower;
140} VUSBDESCCONFIG;
141/** Pointer to a USB configuration descriptor. */
142typedef VUSBDESCCONFIG *PVUSBDESCCONFIG;
143/** Pointer to a readonly USB configuration descriptor. */
144typedef const VUSBDESCCONFIG *PCVUSBDESCCONFIG;
145
146
147/**
148 * USB interface descriptor (from spec)
149 */
150typedef struct VUSBDESCINTERFACE
151{
152 uint8_t bLength;
153 uint8_t bDescriptorType;
154 uint8_t bInterfaceNumber;
155 uint8_t bAlternateSetting;
156 uint8_t bNumEndpoints;
157 uint8_t bInterfaceClass;
158 uint8_t bInterfaceSubClass;
159 uint8_t bInterfaceProtocol;
160 uint8_t iInterface;
161} VUSBDESCINTERFACE;
162/** Pointer to an USB interface descriptor. */
163typedef VUSBDESCINTERFACE *PVUSBDESCINTERFACE;
164/** Pointer to a const USB interface descriptor. */
165typedef const VUSBDESCINTERFACE *PCVUSBDESCINTERFACE;
166
167
168/**
169 * USB endpoint descriptor (from spec)
170 */
171typedef struct VUSBDESCENDPOINT
172{
173 uint8_t bLength;
174 uint8_t bDescriptorType;
175 uint8_t bEndpointAddress;
176 uint8_t bmAttributes;
177 uint16_t wMaxPacketSize;
178 uint8_t bInterval;
179} VUSBDESCENDPOINT;
180/** Pointer to an USB endpoint descriptor. */
181typedef VUSBDESCENDPOINT *PVUSBDESCENDPOINT;
182/** Pointer to a const USB endpoint descriptor. */
183typedef const VUSBDESCENDPOINT *PCVUSBDESCENDPOINT;
184
185#pragma pack() /* end of the byte packing. */
186
187
188/**
189 * USB configuration descriptor, the parsed variant used by VUSB.
190 */
191typedef struct VUSBDESCCONFIGEX
192{
193 /** The USB descriptor data.
194 * @remark The wTotalLength member is recalculated before the data is passed to the guest. */
195 VUSBDESCCONFIG Core;
196 /** Pointer to additional descriptor bytes following what's covered by VUSBDESCCONFIG. */
197 void *pvMore;
198 /** Pointer to an array of the interfaces referenced in the configuration.
199 * Core.bNumInterfaces in size. */
200 const struct VUSBINTERFACE *iface;
201} VUSBDESCCONFIGEX;
202/** Pointer to a parsed USB configuration descriptor. */
203typedef VUSBDESCCONFIGEX *PVUSBDESCCONFIGEX;
204/** Pointer to a const parsed USB configuration descriptor. */
205typedef const VUSBDESCCONFIGEX *PCVUSBDESCCONFIGEX;
206
207
208/**
209 * For tracking the alternate interface settings of a configuration.
210 */
211typedef struct VUSBINTERFACE
212{
213 /** Pointer to an array of interfaces. */
214 const struct VUSBDESCINTERFACEEX *setting;
215 /** The number of entries in the array. */
216 unsigned int num_settings;
217} VUSBINTERFACE;
218/** Pointer to a VUSBINTERFACE. */
219typedef VUSBINTERFACE *PVUSBINTERFACE;
220/** Pointer to a const VUSBINTERFACE. */
221typedef const VUSBINTERFACE *PCVUSBINTERFACE;
222
223
224/**
225 * USB interface descriptor, the parsed variant used by VUSB.
226 */
227typedef struct VUSBDESCINTERFACEEX
228{
229 /** The USB descriptor data. */
230 VUSBDESCINTERFACE Core;
231 /** Pointer to additional descriptor bytes following what's covered by VUSBDESCINTERFACE. */
232 void *pvMore;
233 /** Pointer to an array of the endpoints referenced by the interface.
234 * Core.bNumEndpoints in size. */
235 const struct VUSBDESCENDPOINTEX *endpoint;
236} VUSBDESCINTERFACEEX;
237/** Pointer to an prased USB interface descriptor. */
238typedef VUSBDESCINTERFACEEX *PVUSBDESCINTERFACEEX;
239/** Pointer to a const parsed USB interface descriptor. */
240typedef const VUSBDESCINTERFACEEX *PCVUSBDESCINTERFACEEX;
241
242
243/**
244 * USB endpoint descriptor, the parsed variant used by VUSB.
245 */
246typedef struct VUSBDESCENDPOINTEX
247{
248 /** The USB descriptor data.
249 * @remark The wMaxPacketSize member is converted to native endian. */
250 VUSBDESCENDPOINT Core;
251 /** Pointer to additional descriptor bytes following what's covered by VUSBDESCENDPOINT. */
252 void *pvMore;
253} VUSBDESCENDPOINTEX;
254/** Pointer to a parsed USB endpoint descriptor. */
255typedef VUSBDESCENDPOINTEX *PVUSBDESCENDPOINTEX;
256/** Pointer to a const parsed USB endpoint descriptor. */
257typedef const VUSBDESCENDPOINTEX *PCVUSBDESCENDPOINTEX;
258
259
260/** @name USB Control message recipient codes (from spec)
261 * @{ */
262#define VUSB_TO_DEVICE 0x0
263#define VUSB_TO_INTERFACE 0x1
264#define VUSB_TO_ENDPOINT 0x2
265#define VUSB_TO_OTHER 0x3
266#define VUSB_RECIP_MASK 0x1f
267/** @} */
268
269/** @name USB control pipe setup packet structure (from spec)
270 * @{ */
271#define VUSB_REQ_SHIFT (5)
272#define VUSB_REQ_STANDARD (0x0 << VUSB_REQ_SHIFT)
273#define VUSB_REQ_CLASS (0x1 << VUSB_REQ_SHIFT)
274#define VUSB_REQ_VENDOR (0x2 << VUSB_REQ_SHIFT)
275#define VUSB_REQ_RESERVED (0x3 << VUSB_REQ_SHIFT)
276#define VUSB_REQ_MASK (0x3 << VUSB_REQ_SHIFT)
277/** @} */
278
279#define VUSB_DIR_TO_HOST 0x80
280
281/**
282 * USB Setup request (from spec)
283 */
284typedef struct vusb_setup
285{
286 uint8_t bmRequestType;
287 uint8_t bRequest;
288 uint16_t wValue;
289 uint16_t wIndex;
290 uint16_t wLength;
291} VUSBSETUP;
292/** Pointer to a setup request. */
293typedef VUSBSETUP *PVUSBSETUP;
294/** Pointer to a const setup request. */
295typedef const VUSBSETUP *PCVUSBSETUP;
296
297/** @name USB Standard device requests (from spec)
298 * @{ */
299#define VUSB_REQ_GET_STATUS 0x00
300#define VUSB_REQ_CLEAR_FEATURE 0x01
301#define VUSB_REQ_SET_FEATURE 0x03
302#define VUSB_REQ_SET_ADDRESS 0x05
303#define VUSB_REQ_GET_DESCRIPTOR 0x06
304#define VUSB_REQ_SET_DESCRIPTOR 0x07
305#define VUSB_REQ_GET_CONFIGURATION 0x08
306#define VUSB_REQ_SET_CONFIGURATION 0x09
307#define VUSB_REQ_GET_INTERFACE 0x0a
308#define VUSB_REQ_SET_INTERFACE 0x0b
309#define VUSB_REQ_SYNCH_FRAME 0x0c
310#define VUSB_REQ_MAX 0x0d
311/** @} */
312
313/** @} */ /* end of grp_vusb_std */
314
315
316
317/** @name USB Standard version flags.
318 * @{ */
319/** Indicates USB 1.1 support. */
320#define VUSB_STDVER_11 RT_BIT(1)
321/** Indicates USB 2.0 support. */
322#define VUSB_STDVER_20 RT_BIT(2)
323/** @} */
324
325
326/** Pointer to a VBox USB device interface. */
327typedef struct VUSBIDEVICE *PVUSBIDEVICE;
328
329/** Pointer to a VUSB RootHub port interface. */
330typedef struct VUSBIROOTHUBPORT *PVUSBIROOTHUBPORT;
331
332/** Pointer to a VBox USB timer interface. */
333typedef struct VUSBITIMER *PVUSBITIMER;
334
335/** Pointer to an USB request descriptor. */
336typedef struct VUSBURB *PVUSBURB;
337
338
339
340/**
341 * VBox USB port bitmap.
342 *
343 * Bit 0 == Port 0, ... , Bit 127 == Port 127.
344 */
345typedef struct VUSBPORTBITMAP
346{
347 /** 128 bits */
348 char ach[16];
349} VUSBPORTBITMAP;
350/** Pointer to a VBox USB port bitmap. */
351typedef VUSBPORTBITMAP *PVUSBPORTBITMAP;
352
353
354/**
355 * The VUSB RootHub port interface provided by the HCI.
356 */
357typedef struct VUSBIROOTHUBPORT
358{
359 /**
360 * Get the number of avilable ports in the hub.
361 *
362 * @returns The number of ports available.
363 * @param pInterface Pointer to this structure.
364 * @param pAvailable Bitmap indicating the available ports. Set bit == available port.
365 */
366 DECLR3CALLBACKMEMBER(unsigned, pfnGetAvailablePorts,(PVUSBIROOTHUBPORT pInterface, PVUSBPORTBITMAP pAvailable));
367
368 /**
369 * Gets the supported USB versions.
370 *
371 * @returns The mask of supported USB versions.
372 * @param pInterface Pointer to this structure.
373 */
374 DECLR3CALLBACKMEMBER(uint32_t, pfnGetUSBVersions,(PVUSBIROOTHUBPORT pInterface));
375
376 /**
377 * A device is being attached to a port in the roothub.
378 *
379 * @param pInterface Pointer to this structure.
380 * @param pDev Pointer to the device being attached.
381 * @param uPort The port number assigned to the device.
382 */
383 DECLR3CALLBACKMEMBER(int, pfnAttach,(PVUSBIROOTHUBPORT pInterface, PVUSBIDEVICE pDev, unsigned uPort));
384
385 /**
386 * A device is being detached from a port in the roothub.
387 *
388 * @param pInterface Pointer to this structure.
389 * @param pDev Pointer to the device being detached.
390 * @param uPort The port number assigned to the device.
391 */
392 DECLR3CALLBACKMEMBER(void, pfnDetach,(PVUSBIROOTHUBPORT pInterface, PVUSBIDEVICE pDev, unsigned uPort));
393
394 /**
395 * Reset the root hub.
396 *
397 * @returns VBox status code.
398 * @param pInterface Pointer to this structure.
399 * @param pResetOnLinux Whether or not to do real reset on linux.
400 */
401 DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIROOTHUBPORT pInterface, bool fResetOnLinux));
402
403 /**
404 * Transfer completion callback routine.
405 *
406 * VUSB will call this when a transfer have been completed
407 * in a one or another way.
408 *
409 * @param pInterface Pointer to this structure.
410 * @param pUrb Pointer to the URB in question.
411 */
412 DECLR3CALLBACKMEMBER(void, pfnXferCompletion,(PVUSBIROOTHUBPORT pInterface, PVUSBURB urb));
413
414 /**
415 * Handle transfer errors.
416 *
417 * VUSB calls this when a transfer attempt failed. This function will respond
418 * indicating wheter to retry or complete the URB with failure.
419 *
420 * @returns Retry indicator.
421 * @param pInterface Pointer to this structure.
422 * @param pUrb Pointer to the URB in question.
423 */
424 DECLR3CALLBACKMEMBER(bool, pfnXferError,(PVUSBIROOTHUBPORT pInterface, PVUSBURB pUrb));
425
426 /** Alignment dummy. */
427 RTR3PTR Alignment;
428
429} VUSBIROOTHUBPORT;
430
431
432/** Pointer to a VUSB RootHub connector interface. */
433typedef struct VUSBIROOTHUBCONNECTOR *PVUSBIROOTHUBCONNECTOR;
434
435/**
436 * The VUSB RootHub connector interface provided by the VBox USB RootHub driver.
437 */
438typedef struct VUSBIROOTHUBCONNECTOR
439{
440 /**
441 * Allocates a new URB for a transfer.
442 *
443 * Either submit using pfnSubmitUrb or free using VUSBUrbFree().
444 *
445 * @returns Pointer to a new URB.
446 * @returns NULL on failure - try again later.
447 * This will not fail if the device wasn't found. We'll fail it
448 * at submit time, since that makes the usage of this api simpler.
449 * @param pInterface Pointer to this struct.
450 * @param DstAddress The destination address of the URB.
451 * @param cbData The amount of data space required.
452 * @param cTds The amount of TD space.
453 */
454 DECLR3CALLBACKMEMBER(PVUSBURB, pfnNewUrb,(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t cbData, uint32_t cTds));
455
456 /**
457 * Submits a URB for transfer.
458 * The transfer will do asynchronously if possible.
459 *
460 * @returns VBox status code.
461 * @param pInterface Pointer to this struct.
462 * @param pUrb Pointer to the URB returned by pfnNewUrb.
463 * The URB will be freed in case of failure.
464 * @param pLed Pointer to USB Status LED
465 */
466 DECLR3CALLBACKMEMBER(int, pfnSubmitUrb,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed));
467
468 /**
469 * Call to service asynchronous URB completions in a polling fashion.
470 *
471 * Reaped URBs will be finished by calling the completion callback,
472 * thus there is no return code or input or anything from this function
473 * except for potential state changes elsewhere.
474 *
475 * @returns VINF_SUCCESS if no URBs are pending upon return.
476 * @returns VERR_TIMEOUT if one or more URBs are still in flight upon returning.
477 * @returns Other VBox status code.
478 *
479 * @param pInterface Pointer to this struct.
480 * @param cMillies Number of milliseconds to poll for completion.
481 */
482 DECLR3CALLBACKMEMBER(void, pfnReapAsyncUrbs,(PVUSBIROOTHUBCONNECTOR pInterface, unsigned cMillies));
483
484 /**
485 * Cancels and completes - with CRC failure - all in-flight async URBs.
486 * This is typically done before saving a state.
487 *
488 * @param pInterface Pointer to this struct.
489 */
490 DECLR3CALLBACKMEMBER(void, pfnCancelAllUrbs,(PVUSBIROOTHUBCONNECTOR pInterface));
491
492 /**
493 * Attach the device to the root hub.
494 * The device must not be attached to any hub for this call to succeed.
495 *
496 * @returns VBox status code.
497 * @param pInterface Pointer to this struct.
498 * @param pDevice Pointer to the device (interface) attach.
499 */
500 DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice));
501
502 /**
503 * Detach the device from the root hub.
504 * The device must already be attached for this call to succeed.
505 *
506 * @returns VBox status code.
507 * @param pInterface Pointer to this struct.
508 * @param pDevice Pointer to the device (interface) to detach.
509 */
510 DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice));
511
512} VUSBIROOTHUBCONNECTOR;
513
514
515#ifdef IN_RING3
516/** @copydoc VUSBIROOTHUBCONNECTOR::pfnNewUrb */
517DECLINLINE(PVUSBURB) VUSBIRhNewUrb(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t DstAddress, uint32_t cbData, uint32_t cTds)
518{
519 return pInterface->pfnNewUrb(pInterface, DstAddress, cbData, cTds);
520}
521
522/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSubmitUrb */
523DECLINLINE(int) VUSBIRhSubmitUrb(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed)
524{
525 return pInterface->pfnSubmitUrb(pInterface, pUrb, pLed);
526}
527
528/** @copydoc VUSBIROOTHUBCONNECTOR::pfnReapAsyncUrbs */
529DECLINLINE(void) VUSBIRhReapAsyncUrbs(PVUSBIROOTHUBCONNECTOR pInterface, unsigned cMillies)
530{
531 pInterface->pfnReapAsyncUrbs(pInterface, cMillies);
532}
533
534/** @copydoc VUSBIROOTHUBCONNECTOR::pfnCancelAllUrbs */
535DECLINLINE(void) VUSBIRhCancelAllUrbs(PVUSBIROOTHUBCONNECTOR pInterface)
536{
537 pInterface->pfnCancelAllUrbs(pInterface);
538}
539
540/** @copydoc VUSBIROOTHUBCONNECTOR::pfnAttachDevice */
541DECLINLINE(int) VUSBIRhAttachDevice(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice)
542{
543 return pInterface->pfnAttachDevice(pInterface, pDevice);
544}
545
546/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDetachDevice */
547DECLINLINE(int) VUSBIRhDetachDevice(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice)
548{
549 return pInterface->pfnDetachDevice(pInterface, pDevice);
550}
551#endif /* IN_RING3 */
552
553
554
555/** Pointer to a Root Hub Configuration Interface. */
556typedef struct VUSBIRHCONFIG *PVUSBIRHCONFIG;
557
558/**
559 * Root Hub Configuration Interface (intended for MAIN).
560 */
561typedef struct VUSBIRHCONFIG
562{
563 /**
564 * Creates a USB proxy device and attaches it to the root hub.
565 *
566 * @returns VBox status code.
567 * @param pInterface Pointer to the root hub configuration interface structure.
568 * @param pUuid Pointer to the UUID for the new device.
569 * @param fRemote Whether the device must use the VRDP backend.
570 * @param pszAddress OS specific device address.
571 * @param pvBackend An opaque pointer for the backend. Only used by
572 * the VRDP backend so far.
573 */
574 DECLR3CALLBACKMEMBER(int, pfnCreateProxyDevice,(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid, bool fRemote, const char *pszAddress, void *pvBackend));
575
576 /**
577 * Removes a USB proxy device from the root hub and destroys it.
578 *
579 * @returns VBox status code.
580 * @param pInterface Pointer to the root hub configuration interface structure.
581 * @param pUuid Pointer to the UUID for the device.
582 */
583 DECLR3CALLBACKMEMBER(int, pfnDestroyProxyDevice,(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid));
584
585} VUSBIRHCONFIG;
586
587#ifdef IN_RING3
588/** @copydoc VUSBIRHCONFIG::pfnCreateProxyDevice */
589DECLINLINE(int) VUSBIRhCreateProxyDevice(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid, bool fRemote, const char *pszAddress, void *pvBackend)
590{
591 return pInterface->pfnCreateProxyDevice(pInterface, pUuid, fRemote, pszAddress, pvBackend);
592}
593
594/** @copydoc VUSBIRHCONFIG::pfnDestroyProxyDevice */
595DECLINLINE(int) VUSBIRhDestroyProxyDevice(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid)
596{
597 return pInterface->pfnDestroyProxyDevice(pInterface, pUuid);
598}
599#endif /* IN_RING3 */
600
601
602
603/**
604 * VUSB device reset completion callback function.
605 * This is called by the reset thread when the reset has been completed.
606 *
607 * @param pDev Pointer to the virtual USB device core.
608 * @param rc The VBox status code of the reset operation.
609 * @param pvUser User specific argument.
610 *
611 * @thread The reset thread or EMT.
612 */
613typedef DECLCALLBACK(void) FNVUSBRESETDONE(PVUSBIDEVICE pDevice, int rc, void *pvUser);
614/** Pointer to a device reset completion callback function (FNUSBRESETDONE). */
615typedef FNVUSBRESETDONE *PFNVUSBRESETDONE;
616
617/**
618 * The state of a VUSB Device.
619 *
620 * @remark The order of these states is vital.
621 */
622typedef enum VUSBDEVICESTATE
623{
624 VUSB_DEVICE_STATE_INVALID = 0,
625 VUSB_DEVICE_STATE_DETACHED,
626 VUSB_DEVICE_STATE_ATTACHED,
627 VUSB_DEVICE_STATE_POWERED,
628 VUSB_DEVICE_STATE_DEFAULT,
629 VUSB_DEVICE_STATE_ADDRESS,
630 VUSB_DEVICE_STATE_CONFIGURED,
631 VUSB_DEVICE_STATE_SUSPENDED,
632 /** The device is being reset. Don't mess with it.
633 * Next states: VUSB_DEVICE_STATE_DEFAULT, VUSB_DEVICE_STATE_DESTROYED
634 */
635 VUSB_DEVICE_STATE_RESET,
636 /** The device has been destroy. */
637 VUSB_DEVICE_STATE_DESTROYED,
638 /** The usual 32-bit hack. */
639 VUSB_DEVICE_STATE_32BIT_HACK = 0x7fffffff
640} VUSBDEVICESTATE;
641
642
643/**
644 * USB Device Interface.
645 */
646typedef struct VUSBIDEVICE
647{
648 /**
649 * Resets the device.
650 *
651 * Since a device reset shall take at least 10ms from the guest point of view,
652 * it must be performed asynchronously. We create a thread which performs this
653 * operation and ensures it will take at least 10ms.
654 *
655 * At times - like init - a synchronous reset is required, this can be done
656 * by passing NULL for pfnDone.
657 *
658 * -- internal stuff, move it --
659 * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
660 * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
661 * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
662 * -- internal stuff, move it --
663 *
664 * @returns VBox status code.
665 * @param pInterface Pointer to this structure.
666 * @param fResetOnLinux Set if we can permit a real reset and a potential logical
667 * device reconnect on linux hosts.
668 * @param pfnDone Pointer to the completion routine. If NULL a synchronous
669 * reset is preformed not respecting the 10ms.
670 * @param pvUser User argument to the completion routine.
671 * @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
672 */
673 DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIDEVICE pInterface, bool fResetOnLinux,
674 PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM));
675
676 /**
677 * Powers on the device.
678 *
679 * @returns VBox status code.
680 * @param pInterface Pointer to the device interface structure.
681 */
682 DECLR3CALLBACKMEMBER(int, pfnPowerOn,(PVUSBIDEVICE pInterface));
683
684 /**
685 * Powers off the device.
686 *
687 * @returns VBox status code.
688 * @param pInterface Pointer to the device interface structure.
689 */
690 DECLR3CALLBACKMEMBER(int, pfnPowerOff,(PVUSBIDEVICE pInterface));
691
692 /**
693 * Get the state of the device.
694 *
695 * @returns Device state.
696 * @param pInterface Pointer to the device interface structure.
697 */
698 DECLR3CALLBACKMEMBER(VUSBDEVICESTATE, pfnGetState,(PVUSBIDEVICE pInterface));
699
700} VUSBIDEVICE;
701
702
703#ifdef IN_RING3
704/**
705 * Resets the device.
706 *
707 * Since a device reset shall take at least 10ms from the guest point of view,
708 * it must be performed asynchronously. We create a thread which performs this
709 * operation and ensures it will take at least 10ms.
710 *
711 * At times - like init - a synchronous reset is required, this can be done
712 * by passing NULL for pfnDone.
713 *
714 * -- internal stuff, move it --
715 * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
716 * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
717 * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
718 * -- internal stuff, move it --
719 *
720 * @returns VBox status code.
721 * @param pInterface Pointer to the device interface structure.
722 * @param fResetOnLinux Set if we can permit a real reset and a potential logical
723 * device reconnect on linux hosts.
724 * @param pfnDone Pointer to the completion routine. If NULL a synchronous
725 * reset is preformed not respecting the 10ms.
726 * @param pvUser User argument to the completion routine.
727 * @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
728 */
729DECLINLINE(int) VUSBIDevReset(PVUSBIDEVICE pInterface, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
730{
731 return pInterface->pfnReset(pInterface, fResetOnLinux, pfnDone, pvUser, pVM);
732}
733
734/**
735 * Powers on the device.
736 *
737 * @returns VBox status code.
738 * @param pInterface Pointer to the device interface structure.
739 */
740DECLINLINE(int) VUSBIDevPowerOn(PVUSBIDEVICE pInterface)
741{
742 return pInterface->pfnPowerOn(pInterface);
743}
744
745/**
746 * Powers off the device.
747 *
748 * @returns VBox status code.
749 * @param pInterface Pointer to the device interface structure.
750 */
751DECLINLINE(int) VUSBIDevPowerOff(PVUSBIDEVICE pInterface)
752{
753 return pInterface->pfnPowerOff(pInterface);
754}
755
756/**
757 * Get the state of the device.
758 *
759 * @returns Device state.
760 * @param pInterface Pointer to the device interface structure.
761 */
762DECLINLINE(VUSBDEVICESTATE) VUSBIDevGetState(PVUSBIDEVICE pInterface)
763{
764 return pInterface->pfnGetState(pInterface);
765}
766#endif /* IN_RING3 */
767
768
769/**
770 * USB Timer Interface.
771 */
772typedef struct VUSBITIMER
773{
774 /**
775 * Sets up initial frame timer parameters.
776 *
777 * @returns VBox status code.
778 * @param pInterface Pointer to the timer interface structure.
779 * @param pfnCallback Pointer to the timer callback function.
780 * @param rate Requested frame rate (normally 1,000).
781 */
782 DECLR3CALLBACKMEMBER(int, pfnTimerSetup,(PVUSBITIMER pInterface, PFNTMTIMERDEV pfnCallback, uint32_t rate));
783
784 /**
785 * Requests another tick of the frame timer.
786 *
787 * @returns VBox status code.
788 * @param pInterface Pointer to the timer interface structure.
789 */
790 DECLR3CALLBACKMEMBER(int, pfnTimerSetNext,(PVUSBITIMER pInterface));
791
792 /**
793 * Stops the frame timer for the caller.
794 *
795 * @returns VBox status code.
796 * @param pInterface Pointer to the timer interface structure.
797 */
798 DECLR3CALLBACKMEMBER(int, pfnTimerStop,(PVUSBITIMER pInterface));
799
800} VUSBITIMER;
801
802
803#ifdef IN_RING3
804/**
805 * Sets up initial frame timer parameters.
806 *
807 * @returns VBox status code.
808 * @param pInterface Pointer to the timer interface structure.
809 * @param pfnCallback Pointer to the timer callback function.
810 * @param rate Requested frame rate (normally 1,000).
811 */
812DECLINLINE(int) VUSBITimerSetup(PVUSBITIMER pInterface, PFNTMTIMERDEV pfnCallback, uint32_t rate)
813{
814 return pInterface->pfnTimerSetup(pInterface, pfnCallback, rate);
815}
816
817/**
818 * Requests another tick of the USB frame timer.
819 *
820 * @returns VBox status code.
821 * @param pInterface Pointer to the timer interface structure.
822 */
823DECLINLINE(int) VUSBITimerSetNext(PVUSBITIMER pInterface)
824{
825 return pInterface->pfnTimerSetNext(pInterface);
826}
827
828/**
829 * Stops the USB frame timer for the caller.
830 *
831 * @returns VBox status code.
832 * @param pInterface Pointer to the timer interface structure.
833 */
834DECLINLINE(int) VUSBITimerStop(PVUSBITIMER pInterface)
835{
836 return pInterface->pfnTimerStop(pInterface);
837}
838#endif /* IN_RING3 */
839
840
841/** @name URB
842 * @{ */
843
844/**
845 * VUSB Transfer status codes.
846 */
847typedef enum VUSBSTATUS
848{
849 /** Transer was ok. */
850 VUSBSTATUS_OK = 0,
851 /** Transfer stalled, endpoint halted. */
852 VUSBSTATUS_STALL,
853 /** Device not responding. */
854 VUSBSTATUS_DNR,
855 /** CRC error. */
856 VUSBSTATUS_CRC,
857 /** Data overrun error. */
858 VUSBSTATUS_DATA_UNDERRUN,
859 /** Data overrun error. */
860 VUSBSTATUS_DATA_OVERRUN,
861 /** The isochronous buffer hasn't been touched. */
862 VUSBSTATUS_NOT_ACCESSED,
863 /** Invalid status. */
864 VUSBSTATUS_INVALID = 0x7f
865} VUSBSTATUS;
866
867
868/**
869 * VUSB Transfer types.
870 */
871typedef enum VUSBXFERTYPE
872{
873 /** Control message. Used to represent a single control transfer. */
874 VUSBXFERTYPE_CTRL = 0,
875 /* Isochronous transfer. */
876 VUSBXFERTYPE_ISOC,
877 /** Bulk transfer. */
878 VUSBXFERTYPE_BULK,
879 /** Interrupt transfer. */
880 VUSBXFERTYPE_INTR,
881 /** Complete control message. Used to represent an entire control message. */
882 VUSBXFERTYPE_MSG,
883 /** Invalid transfer type. */
884 VUSBXFERTYPE_INVALID = 0x7f
885} VUSBXFERTYPE;
886
887
888/**
889 * VUSB transfer direction.
890 */
891typedef enum VUSBDIRECTION
892{
893 /** Setup */
894 VUSBDIRECTION_SETUP = 0,
895#define VUSB_DIRECTION_SETUP VUSBDIRECTION_SETUP
896 /** In - Device to host. */
897 VUSBDIRECTION_IN = 1,
898#define VUSB_DIRECTION_IN VUSBDIRECTION_IN
899 /** Out - Host to device. */
900 VUSBDIRECTION_OUT = 2,
901#define VUSB_DIRECTION_OUT VUSBDIRECTION_OUT
902 /** Invalid direction */
903 VUSBDIRECTION_INVALID = 0x7f
904} VUSBDIRECTION;
905
906/**
907 * The URB states
908 */
909typedef enum VUSBURBSTATE
910{
911 /** The usual invalid state. */
912 VUSBURBSTATE_INVALID = 0,
913 /** The URB is free, i.e. not in use.
914 * Next state: ALLOCATED */
915 VUSBURBSTATE_FREE,
916 /** The URB is allocated, i.e. being prepared for submission.
917 * Next state: FREE, IN_FLIGHT */
918 VUSBURBSTATE_ALLOCATED,
919 /** The URB is in flight.
920 * Next state: REAPED, CANCELLED */
921 VUSBURBSTATE_IN_FLIGHT,
922 /** The URB has been reaped and is being completed.
923 * Next state: FREE */
924 VUSBURBSTATE_REAPED,
925 /** The URB has been cancelled and is awaiting reaping and immediate freeing.
926 * Next state: FREE */
927 VUSBURBSTATE_CANCELLED,
928 /** The end of the valid states (exclusive). */
929 VUSBURBSTATE_END,
930 /** The usual 32-bit blow up. */
931 VUSBURBSTATE_32BIT_HACK = 0x7fffffff
932} VUSBURBSTATE;
933
934
935/**
936 * Information about a isochronous packet.
937 */
938typedef struct VUSBURBISOCPKT
939{
940 /** The size of the packet.
941 * IN: The packet size. I.e. the number of bytes to the next packet or end of buffer.
942 * OUT: The actual size transfered. */
943 uint16_t cb;
944 /** The offset of the packet. (Relative to VUSBURB::abData[0].)
945 * OUT: This can be changed by the USB device if it does some kind of buffer squeezing. */
946 uint16_t off;
947 /** The status of the transfer.
948 * IN: VUSBSTATUS_INVALID
949 * OUT: VUSBSTATUS_INVALID if nothing was done, otherwise the correct status. */
950 VUSBSTATUS enmStatus;
951} VUSBURBISOCPKT;
952/** Pointer to a isochronous packet. */
953typedef VUSBURBISOCPKT *PVUSBURBISOCPTK;
954/** Pointer to a const isochronous packet. */
955typedef const VUSBURBISOCPKT *PCVUSBURBISOCPKT;
956
957/**
958 * Asynchronous USB request descriptor
959 */
960typedef struct VUSBURB
961{
962 /** URB magic value. */
963 uint32_t u32Magic;
964 /** The USR state. */
965 VUSBURBSTATE enmState;
966 /** URB description, can be null. intended for logging. */
967 char *pszDesc;
968
969 /** The VUSB data. */
970 struct VUSBURBVUSB
971 {
972 /** URB chain pointer. */
973 PVUSBURB pNext;
974 /** URB chain pointer. */
975 PVUSBURB *ppPrev;
976 /** Pointer to the original for control messages. */
977 PVUSBURB pCtrlUrb;
978 /** Pointer to the VUSB device.
979 * This may be NULL if the destination address is invalid. */
980 struct VUSBDEV *pDev;
981 /** Sepcific to the pfnFree function. */
982 void *pvFreeCtx;
983 /**
984 * Callback which will free the URB once it's reaped and completed.
985 * @param pUrb The URB.
986 */
987 DECLCALLBACKMEMBER(void, pfnFree)(PVUSBURB pUrb);
988 /** Submit timestamp. (logging only) */
989 uint64_t u64SubmitTS;
990 /** The allocated data length. */
991 uint32_t cbDataAllocated;
992 /** The allocated TD length. */
993 uint32_t cTdsAllocated;
994 } VUsb;
995
996 /** The host controller data. */
997 struct VUSBURBHCI
998 {
999 /** The endpoint descriptor address. */
1000 RTGCPHYS32 EdAddr;
1001 /** Number of Tds in the array. */
1002 uint32_t cTds;
1003 /** Pointer to an array of TD info items.*/
1004 struct VUSBURBHCITD
1005 {
1006 /** Type of TD (private) */
1007 uint32_t TdType;
1008 /** The address of the */
1009 RTGCPHYS32 TdAddr;
1010 /** A copy of the TD. */
1011 uint32_t TdCopy[16];
1012 } *paTds;
1013 /** URB chain pointer. */
1014 PVUSBURB pNext;
1015 /** When this URB was created.
1016 * (Used for isochronous frames and for logging.) */
1017 uint32_t u32FrameNo;
1018 /** Flag indicating that the TDs have been unlinked. */
1019 bool fUnlinked;
1020 } Hci;
1021
1022 /** The device data. */
1023 struct VUSBURBDEV
1024 {
1025 /** Pointer to the proxy URB. */
1026 void *pvProxyUrb;
1027 } Dev;
1028
1029 /** The USB device instance this belongs to.
1030 * This is NULL if the device address is invalid, in which case this belongs to the hub. */
1031 PPDMUSBINS pUsbIns;
1032 /** The device address.
1033 * This is set at allocation time. */
1034 uint8_t DstAddress;
1035
1036 /** The endpoint.
1037 * IN: Must be set before submitting the URB.
1038 * @remark This does not have the high bit (direction) set! */
1039 uint8_t EndPt;
1040 /** The transfer type.
1041 * IN: Must be set before submitting the URB. */
1042 VUSBXFERTYPE enmType;
1043 /** The transfer direction.
1044 * IN: Must be set before submitting the URB. */
1045 VUSBDIRECTION enmDir;
1046 /** Indicates whether it is OK to receive/send less data than requested.
1047 * IN: Must be initialized before submitting the URB. */
1048 bool fShortNotOk;
1049 /** The transfer status.
1050 * OUT: This is set when reaping the URB. */
1051 VUSBSTATUS enmStatus;
1052
1053 /** The number of isochronous packets describe in aIsocPkts.
1054 * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
1055 uint32_t cIsocPkts;
1056 /** The iso packets within abData.
1057 * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
1058 VUSBURBISOCPKT aIsocPkts[8];
1059
1060 /** The message length.
1061 * IN: The amount of data to send / receive - set at allocation time.
1062 * OUT: The amount of data sent / received. */
1063 uint32_t cbData;
1064 /** The message data.
1065 * IN: On host to device transfers, the data to send.
1066 * OUT: On device to host transfers, the data to received. */
1067 uint8_t abData[8*_1K];
1068} VUSBURB;
1069
1070/** The magic value of a valid VUSBURB. (Murakami Haruki) */
1071#define VUSBURB_MAGIC 0x19490112
1072
1073/** @} */
1074
1075
1076/** @} */
1077
1078__END_DECLS
1079
1080#endif
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use