VirtualBox

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

Last change on this file since 17661 was 15076, checked in by vboxsync, 16 years ago

Different headers included on gcc builds?

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 34.3 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/**
327 * USB frame timer callback function.
328 *
329 * @param pDevIns Device instance of the device which registered the timer.
330 * @param pTimer The timer handle.
331 */
332typedef DECLCALLBACK(void) FNUSBTIMERDEV(PPDMDEVINS pDevIns, PTMTIMER pTimer);
333/** Pointer to a device timer callback function. */
334typedef FNUSBTIMERDEV *PFNUSBTIMERDEV;
335
336/** Pointer to a VBox USB device interface. */
337typedef struct VUSBIDEVICE *PVUSBIDEVICE;
338
339/** Pointer to a VUSB RootHub port interface. */
340typedef struct VUSBIROOTHUBPORT *PVUSBIROOTHUBPORT;
341
342/** Pointer to a VBox USB timer interface. */
343typedef struct VUSBITIMER *PVUSBITIMER;
344
345/** Pointer to an USB request descriptor. */
346typedef struct VUSBURB *PVUSBURB;
347
348
349
350/**
351 * VBox USB port bitmap.
352 *
353 * Bit 0 == Port 0, ... , Bit 127 == Port 127.
354 */
355typedef struct VUSBPORTBITMAP
356{
357 /** 128 bits */
358 char ach[16];
359} VUSBPORTBITMAP;
360/** Pointer to a VBox USB port bitmap. */
361typedef VUSBPORTBITMAP *PVUSBPORTBITMAP;
362
363
364/**
365 * The VUSB RootHub port interface provided by the HCI.
366 */
367typedef struct VUSBIROOTHUBPORT
368{
369 /**
370 * Get the number of avilable ports in the hub.
371 *
372 * @returns The number of ports available.
373 * @param pInterface Pointer to this structure.
374 * @param pAvailable Bitmap indicating the available ports. Set bit == available port.
375 */
376 DECLR3CALLBACKMEMBER(unsigned, pfnGetAvailablePorts,(PVUSBIROOTHUBPORT pInterface, PVUSBPORTBITMAP pAvailable));
377
378 /**
379 * Gets the supported USB versions.
380 *
381 * @returns The mask of supported USB versions.
382 * @param pInterface Pointer to this structure.
383 */
384 DECLR3CALLBACKMEMBER(uint32_t, pfnGetUSBVersions,(PVUSBIROOTHUBPORT pInterface));
385
386 /**
387 * A device is being attached to a port in the roothub.
388 *
389 * @param pInterface Pointer to this structure.
390 * @param pDev Pointer to the device being attached.
391 * @param uPort The port number assigned to the device.
392 */
393 DECLR3CALLBACKMEMBER(int, pfnAttach,(PVUSBIROOTHUBPORT pInterface, PVUSBIDEVICE pDev, unsigned uPort));
394
395 /**
396 * A device is being detached from a port in the roothub.
397 *
398 * @param pInterface Pointer to this structure.
399 * @param pDev Pointer to the device being detached.
400 * @param uPort The port number assigned to the device.
401 */
402 DECLR3CALLBACKMEMBER(void, pfnDetach,(PVUSBIROOTHUBPORT pInterface, PVUSBIDEVICE pDev, unsigned uPort));
403
404 /**
405 * Reset the root hub.
406 *
407 * @returns VBox status code.
408 * @param pInterface Pointer to this structure.
409 * @param pResetOnLinux Whether or not to do real reset on linux.
410 */
411 DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIROOTHUBPORT pInterface, bool fResetOnLinux));
412
413 /**
414 * Transfer completion callback routine.
415 *
416 * VUSB will call this when a transfer have been completed
417 * in a one or another way.
418 *
419 * @param pInterface Pointer to this structure.
420 * @param pUrb Pointer to the URB in question.
421 */
422 DECLR3CALLBACKMEMBER(void, pfnXferCompletion,(PVUSBIROOTHUBPORT pInterface, PVUSBURB urb));
423
424 /**
425 * Handle transfer errors.
426 *
427 * VUSB calls this when a transfer attempt failed. This function will respond
428 * indicating wheter to retry or complete the URB with failure.
429 *
430 * @returns Retry indicator.
431 * @param pInterface Pointer to this structure.
432 * @param pUrb Pointer to the URB in question.
433 */
434 DECLR3CALLBACKMEMBER(bool, pfnXferError,(PVUSBIROOTHUBPORT pInterface, PVUSBURB pUrb));
435
436 /** Alignment dummy. */
437 RTR3PTR Alignment;
438
439} VUSBIROOTHUBPORT;
440
441
442/** Pointer to a VUSB RootHub connector interface. */
443typedef struct VUSBIROOTHUBCONNECTOR *PVUSBIROOTHUBCONNECTOR;
444
445/**
446 * The VUSB RootHub connector interface provided by the VBox USB RootHub driver.
447 */
448typedef struct VUSBIROOTHUBCONNECTOR
449{
450 /**
451 * Allocates a new URB for a transfer.
452 *
453 * Either submit using pfnSubmitUrb or free using VUSBUrbFree().
454 *
455 * @returns Pointer to a new URB.
456 * @returns NULL on failure - try again later.
457 * This will not fail if the device wasn't found. We'll fail it
458 * at submit time, since that makes the usage of this api simpler.
459 * @param pInterface Pointer to this struct.
460 * @param DstAddress The destination address of the URB.
461 * @param cbData The amount of data space required.
462 * @param cTds The amount of TD space.
463 */
464 DECLR3CALLBACKMEMBER(PVUSBURB, pfnNewUrb,(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t cbData, uint32_t cTds));
465
466 /**
467 * Submits a URB for transfer.
468 * The transfer will do asynchronously if possible.
469 *
470 * @returns VBox status code.
471 * @param pInterface Pointer to this struct.
472 * @param pUrb Pointer to the URB returned by pfnNewUrb.
473 * The URB will be freed in case of failure.
474 * @param pLed Pointer to USB Status LED
475 */
476 DECLR3CALLBACKMEMBER(int, pfnSubmitUrb,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed));
477
478 /**
479 * Call to service asynchronous URB completions in a polling fashion.
480 *
481 * Reaped URBs will be finished by calling the completion callback,
482 * thus there is no return code or input or anything from this function
483 * except for potential state changes elsewhere.
484 *
485 * @returns VINF_SUCCESS if no URBs are pending upon return.
486 * @returns VERR_TIMEOUT if one or more URBs are still in flight upon returning.
487 * @returns Other VBox status code.
488 *
489 * @param pInterface Pointer to this struct.
490 * @param cMillies Number of milliseconds to poll for completion.
491 */
492 DECLR3CALLBACKMEMBER(void, pfnReapAsyncUrbs,(PVUSBIROOTHUBCONNECTOR pInterface, unsigned cMillies));
493
494 /**
495 * Cancels and completes - with CRC failure - all in-flight async URBs.
496 * This is typically done before saving a state.
497 *
498 * @param pInterface Pointer to this struct.
499 */
500 DECLR3CALLBACKMEMBER(void, pfnCancelAllUrbs,(PVUSBIROOTHUBCONNECTOR pInterface));
501
502 /**
503 * Attach the device to the root hub.
504 * The device must not be attached to any hub 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) attach.
509 */
510 DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice));
511
512 /**
513 * Detach the device from the root hub.
514 * The device must already be attached for this call to succeed.
515 *
516 * @returns VBox status code.
517 * @param pInterface Pointer to this struct.
518 * @param pDevice Pointer to the device (interface) to detach.
519 */
520 DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice));
521
522} VUSBIROOTHUBCONNECTOR;
523
524
525#ifdef IN_RING3
526/** @copydoc VUSBIROOTHUBCONNECTOR::pfnNewUrb */
527DECLINLINE(PVUSBURB) VUSBIRhNewUrb(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t DstAddress, uint32_t cbData, uint32_t cTds)
528{
529 return pInterface->pfnNewUrb(pInterface, DstAddress, cbData, cTds);
530}
531
532/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSubmitUrb */
533DECLINLINE(int) VUSBIRhSubmitUrb(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb, struct PDMLED *pLed)
534{
535 return pInterface->pfnSubmitUrb(pInterface, pUrb, pLed);
536}
537
538/** @copydoc VUSBIROOTHUBCONNECTOR::pfnReapAsyncUrbs */
539DECLINLINE(void) VUSBIRhReapAsyncUrbs(PVUSBIROOTHUBCONNECTOR pInterface, unsigned cMillies)
540{
541 pInterface->pfnReapAsyncUrbs(pInterface, cMillies);
542}
543
544/** @copydoc VUSBIROOTHUBCONNECTOR::pfnCancelAllUrbs */
545DECLINLINE(void) VUSBIRhCancelAllUrbs(PVUSBIROOTHUBCONNECTOR pInterface)
546{
547 pInterface->pfnCancelAllUrbs(pInterface);
548}
549
550/** @copydoc VUSBIROOTHUBCONNECTOR::pfnAttachDevice */
551DECLINLINE(int) VUSBIRhAttachDevice(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice)
552{
553 return pInterface->pfnAttachDevice(pInterface, pDevice);
554}
555
556/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDetachDevice */
557DECLINLINE(int) VUSBIRhDetachDevice(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice)
558{
559 return pInterface->pfnDetachDevice(pInterface, pDevice);
560}
561#endif /* IN_RING3 */
562
563
564
565/** Pointer to a Root Hub Configuration Interface. */
566typedef struct VUSBIRHCONFIG *PVUSBIRHCONFIG;
567
568/**
569 * Root Hub Configuration Interface (intended for MAIN).
570 */
571typedef struct VUSBIRHCONFIG
572{
573 /**
574 * Creates a USB proxy device and attaches it to the root hub.
575 *
576 * @returns VBox status code.
577 * @param pInterface Pointer to the root hub configuration interface structure.
578 * @param pUuid Pointer to the UUID for the new device.
579 * @param fRemote Whether the device must use the VRDP backend.
580 * @param pszAddress OS specific device address.
581 * @param pvBackend An opaque pointer for the backend. Only used by
582 * the VRDP backend so far.
583 */
584 DECLR3CALLBACKMEMBER(int, pfnCreateProxyDevice,(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid, bool fRemote, const char *pszAddress, void *pvBackend));
585
586 /**
587 * Removes a USB proxy device from the root hub and destroys it.
588 *
589 * @returns VBox status code.
590 * @param pInterface Pointer to the root hub configuration interface structure.
591 * @param pUuid Pointer to the UUID for the device.
592 */
593 DECLR3CALLBACKMEMBER(int, pfnDestroyProxyDevice,(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid));
594
595} VUSBIRHCONFIG;
596
597#ifdef IN_RING3
598/** @copydoc VUSBIRHCONFIG::pfnCreateProxyDevice */
599DECLINLINE(int) VUSBIRhCreateProxyDevice(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid, bool fRemote, const char *pszAddress, void *pvBackend)
600{
601 return pInterface->pfnCreateProxyDevice(pInterface, pUuid, fRemote, pszAddress, pvBackend);
602}
603
604/** @copydoc VUSBIRHCONFIG::pfnDestroyProxyDevice */
605DECLINLINE(int) VUSBIRhDestroyProxyDevice(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid)
606{
607 return pInterface->pfnDestroyProxyDevice(pInterface, pUuid);
608}
609#endif /* IN_RING3 */
610
611
612
613/**
614 * VUSB device reset completion callback function.
615 * This is called by the reset thread when the reset has been completed.
616 *
617 * @param pDev Pointer to the virtual USB device core.
618 * @param rc The VBox status code of the reset operation.
619 * @param pvUser User specific argument.
620 *
621 * @thread The reset thread or EMT.
622 */
623typedef DECLCALLBACK(void) FNVUSBRESETDONE(PVUSBIDEVICE pDevice, int rc, void *pvUser);
624/** Pointer to a device reset completion callback function (FNUSBRESETDONE). */
625typedef FNVUSBRESETDONE *PFNVUSBRESETDONE;
626
627/**
628 * The state of a VUSB Device.
629 *
630 * @remark The order of these states is vital.
631 */
632typedef enum VUSBDEVICESTATE
633{
634 VUSB_DEVICE_STATE_INVALID = 0,
635 VUSB_DEVICE_STATE_DETACHED,
636 VUSB_DEVICE_STATE_ATTACHED,
637 VUSB_DEVICE_STATE_POWERED,
638 VUSB_DEVICE_STATE_DEFAULT,
639 VUSB_DEVICE_STATE_ADDRESS,
640 VUSB_DEVICE_STATE_CONFIGURED,
641 VUSB_DEVICE_STATE_SUSPENDED,
642 /** The device is being reset. Don't mess with it.
643 * Next states: VUSB_DEVICE_STATE_DEFAULT, VUSB_DEVICE_STATE_DESTROYED
644 */
645 VUSB_DEVICE_STATE_RESET,
646 /** The device has been destroy. */
647 VUSB_DEVICE_STATE_DESTROYED,
648 /** The usual 32-bit hack. */
649 VUSB_DEVICE_STATE_32BIT_HACK = 0x7fffffff
650} VUSBDEVICESTATE;
651
652
653/**
654 * USB Device Interface.
655 */
656typedef struct VUSBIDEVICE
657{
658 /**
659 * Resets the device.
660 *
661 * Since a device reset shall take at least 10ms from the guest point of view,
662 * it must be performed asynchronously. We create a thread which performs this
663 * operation and ensures it will take at least 10ms.
664 *
665 * At times - like init - a synchronous reset is required, this can be done
666 * by passing NULL for pfnDone.
667 *
668 * -- internal stuff, move it --
669 * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
670 * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
671 * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
672 * -- internal stuff, move it --
673 *
674 * @returns VBox status code.
675 * @param pInterface Pointer to this structure.
676 * @param fResetOnLinux Set if we can permit a real reset and a potential logical
677 * device reconnect on linux hosts.
678 * @param pfnDone Pointer to the completion routine. If NULL a synchronous
679 * reset is preformed not respecting the 10ms.
680 * @param pvUser User argument to the completion routine.
681 * @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
682 */
683 DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIDEVICE pInterface, bool fResetOnLinux,
684 PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM));
685
686 /**
687 * Powers on the device.
688 *
689 * @returns VBox status code.
690 * @param pInterface Pointer to the device interface structure.
691 */
692 DECLR3CALLBACKMEMBER(int, pfnPowerOn,(PVUSBIDEVICE pInterface));
693
694 /**
695 * Powers off the device.
696 *
697 * @returns VBox status code.
698 * @param pInterface Pointer to the device interface structure.
699 */
700 DECLR3CALLBACKMEMBER(int, pfnPowerOff,(PVUSBIDEVICE pInterface));
701
702 /**
703 * Get the state of the device.
704 *
705 * @returns Device state.
706 * @param pInterface Pointer to the device interface structure.
707 */
708 DECLR3CALLBACKMEMBER(VUSBDEVICESTATE, pfnGetState,(PVUSBIDEVICE pInterface));
709
710} VUSBIDEVICE;
711
712
713#ifdef IN_RING3
714/**
715 * Resets the device.
716 *
717 * Since a device reset shall take at least 10ms from the guest point of view,
718 * it must be performed asynchronously. We create a thread which performs this
719 * operation and ensures it will take at least 10ms.
720 *
721 * At times - like init - a synchronous reset is required, this can be done
722 * by passing NULL for pfnDone.
723 *
724 * -- internal stuff, move it --
725 * While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
726 * On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
727 * or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
728 * -- internal stuff, move it --
729 *
730 * @returns VBox status code.
731 * @param pInterface Pointer to the device interface structure.
732 * @param fResetOnLinux Set if we can permit a real reset and a potential logical
733 * device reconnect on linux hosts.
734 * @param pfnDone Pointer to the completion routine. If NULL a synchronous
735 * reset is preformed not respecting the 10ms.
736 * @param pvUser User argument to the completion routine.
737 * @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
738 */
739DECLINLINE(int) VUSBIDevReset(PVUSBIDEVICE pInterface, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
740{
741 return pInterface->pfnReset(pInterface, fResetOnLinux, pfnDone, pvUser, pVM);
742}
743
744/**
745 * Powers on the device.
746 *
747 * @returns VBox status code.
748 * @param pInterface Pointer to the device interface structure.
749 */
750DECLINLINE(int) VUSBIDevPowerOn(PVUSBIDEVICE pInterface)
751{
752 return pInterface->pfnPowerOn(pInterface);
753}
754
755/**
756 * Powers off the device.
757 *
758 * @returns VBox status code.
759 * @param pInterface Pointer to the device interface structure.
760 */
761DECLINLINE(int) VUSBIDevPowerOff(PVUSBIDEVICE pInterface)
762{
763 return pInterface->pfnPowerOff(pInterface);
764}
765
766/**
767 * Get the state of the device.
768 *
769 * @returns Device state.
770 * @param pInterface Pointer to the device interface structure.
771 */
772DECLINLINE(VUSBDEVICESTATE) VUSBIDevGetState(PVUSBIDEVICE pInterface)
773{
774 return pInterface->pfnGetState(pInterface);
775}
776#endif /* IN_RING3 */
777
778
779/**
780 * USB Timer Interface.
781 */
782typedef struct VUSBITIMER
783{
784 /**
785 * Sets up initial frame timer parameters.
786 *
787 * @returns VBox status code.
788 * @param pInterface Pointer to the timer interface structure.
789 * @param pfnCallback Pointer to the timer callback function.
790 * @param rate Requested frame rate (normally 1,000).
791 */
792 DECLR3CALLBACKMEMBER(int, pfnTimerSetup,(PVUSBITIMER pInterface, PFNUSBTIMERDEV pfnCallback, uint32_t rate));
793
794 /**
795 * Requests another tick of the frame timer.
796 *
797 * @returns VBox status code.
798 * @param pInterface Pointer to the timer interface structure.
799 */
800 DECLR3CALLBACKMEMBER(int, pfnTimerSetNext,(PVUSBITIMER pInterface));
801
802 /**
803 * Stops the frame timer for the caller.
804 *
805 * @returns VBox status code.
806 * @param pInterface Pointer to the timer interface structure.
807 */
808 DECLR3CALLBACKMEMBER(int, pfnTimerStop,(PVUSBITIMER pInterface));
809
810} VUSBITIMER;
811
812
813#ifdef IN_RING3
814/**
815 * Sets up initial frame timer parameters.
816 *
817 * @returns VBox status code.
818 * @param pInterface Pointer to the timer interface structure.
819 * @param pfnCallback Pointer to the timer callback function.
820 * @param rate Requested frame rate (normally 1,000).
821 */
822DECLINLINE(int) VUSBITimerSetup(PVUSBITIMER pInterface, PFNUSBTIMERDEV pfnCallback, uint32_t rate)
823{
824 return pInterface->pfnTimerSetup(pInterface, pfnCallback, rate);
825}
826
827/**
828 * Requests another tick of the USB frame timer.
829 *
830 * @returns VBox status code.
831 * @param pInterface Pointer to the timer interface structure.
832 */
833DECLINLINE(int) VUSBITimerSetNext(PVUSBITIMER pInterface)
834{
835 return pInterface->pfnTimerSetNext(pInterface);
836}
837
838/**
839 * Stops the USB frame timer for the caller.
840 *
841 * @returns VBox status code.
842 * @param pInterface Pointer to the timer interface structure.
843 */
844DECLINLINE(int) VUSBITimerStop(PVUSBITIMER pInterface)
845{
846 return pInterface->pfnTimerStop(pInterface);
847}
848#endif /* IN_RING3 */
849
850
851/** @name URB
852 * @{ */
853
854/**
855 * VUSB Transfer status codes.
856 */
857typedef enum VUSBSTATUS
858{
859 /** Transer was ok. */
860 VUSBSTATUS_OK = 0,
861 /** Transfer stalled, endpoint halted. */
862 VUSBSTATUS_STALL,
863 /** Device not responding. */
864 VUSBSTATUS_DNR,
865 /** CRC error. */
866 VUSBSTATUS_CRC,
867 /** Data overrun error. */
868 VUSBSTATUS_DATA_UNDERRUN,
869 /** Data overrun error. */
870 VUSBSTATUS_DATA_OVERRUN,
871 /** The isochronous buffer hasn't been touched. */
872 VUSBSTATUS_NOT_ACCESSED,
873 /** Invalid status. */
874 VUSBSTATUS_INVALID = 0x7f
875} VUSBSTATUS;
876
877
878/**
879 * VUSB Transfer types.
880 */
881typedef enum VUSBXFERTYPE
882{
883 /** Control message. Used to represent a single control transfer. */
884 VUSBXFERTYPE_CTRL = 0,
885 /* Isochronous transfer. */
886 VUSBXFERTYPE_ISOC,
887 /** Bulk transfer. */
888 VUSBXFERTYPE_BULK,
889 /** Interrupt transfer. */
890 VUSBXFERTYPE_INTR,
891 /** Complete control message. Used to represent an entire control message. */
892 VUSBXFERTYPE_MSG,
893 /** Invalid transfer type. */
894 VUSBXFERTYPE_INVALID = 0x7f
895} VUSBXFERTYPE;
896
897
898/**
899 * VUSB transfer direction.
900 */
901typedef enum VUSBDIRECTION
902{
903 /** Setup */
904 VUSBDIRECTION_SETUP = 0,
905#define VUSB_DIRECTION_SETUP VUSBDIRECTION_SETUP
906 /** In - Device to host. */
907 VUSBDIRECTION_IN = 1,
908#define VUSB_DIRECTION_IN VUSBDIRECTION_IN
909 /** Out - Host to device. */
910 VUSBDIRECTION_OUT = 2,
911#define VUSB_DIRECTION_OUT VUSBDIRECTION_OUT
912 /** Invalid direction */
913 VUSBDIRECTION_INVALID = 0x7f
914} VUSBDIRECTION;
915
916/**
917 * The URB states
918 */
919typedef enum VUSBURBSTATE
920{
921 /** The usual invalid state. */
922 VUSBURBSTATE_INVALID = 0,
923 /** The URB is free, i.e. not in use.
924 * Next state: ALLOCATED */
925 VUSBURBSTATE_FREE,
926 /** The URB is allocated, i.e. being prepared for submission.
927 * Next state: FREE, IN_FLIGHT */
928 VUSBURBSTATE_ALLOCATED,
929 /** The URB is in flight.
930 * Next state: REAPED, CANCELLED */
931 VUSBURBSTATE_IN_FLIGHT,
932 /** The URB has been reaped and is being completed.
933 * Next state: FREE */
934 VUSBURBSTATE_REAPED,
935 /** The URB has been cancelled and is awaiting reaping and immediate freeing.
936 * Next state: FREE */
937 VUSBURBSTATE_CANCELLED,
938 /** The end of the valid states (exclusive). */
939 VUSBURBSTATE_END,
940 /** The usual 32-bit blow up. */
941 VUSBURBSTATE_32BIT_HACK = 0x7fffffff
942} VUSBURBSTATE;
943
944
945/**
946 * Information about a isochronous packet.
947 */
948typedef struct VUSBURBISOCPKT
949{
950 /** The size of the packet.
951 * IN: The packet size. I.e. the number of bytes to the next packet or end of buffer.
952 * OUT: The actual size transfered. */
953 uint16_t cb;
954 /** The offset of the packet. (Relative to VUSBURB::abData[0].)
955 * OUT: This can be changed by the USB device if it does some kind of buffer squeezing. */
956 uint16_t off;
957 /** The status of the transfer.
958 * IN: VUSBSTATUS_INVALID
959 * OUT: VUSBSTATUS_INVALID if nothing was done, otherwise the correct status. */
960 VUSBSTATUS enmStatus;
961} VUSBURBISOCPKT;
962/** Pointer to a isochronous packet. */
963typedef VUSBURBISOCPKT *PVUSBURBISOCPTK;
964/** Pointer to a const isochronous packet. */
965typedef const VUSBURBISOCPKT *PCVUSBURBISOCPKT;
966
967/**
968 * Asynchronous USB request descriptor
969 */
970typedef struct VUSBURB
971{
972 /** URB magic value. */
973 uint32_t u32Magic;
974 /** The USR state. */
975 VUSBURBSTATE enmState;
976 /** URB description, can be null. intended for logging. */
977 char *pszDesc;
978
979 /** The VUSB data. */
980 struct VUSBURBVUSB
981 {
982 /** URB chain pointer. */
983 PVUSBURB pNext;
984 /** URB chain pointer. */
985 PVUSBURB *ppPrev;
986 /** Pointer to the original for control messages. */
987 PVUSBURB pCtrlUrb;
988 /** Pointer to the VUSB device.
989 * This may be NULL if the destination address is invalid. */
990 struct VUSBDEV *pDev;
991 /** Sepcific to the pfnFree function. */
992 void *pvFreeCtx;
993 /**
994 * Callback which will free the URB once it's reaped and completed.
995 * @param pUrb The URB.
996 */
997 DECLCALLBACKMEMBER(void, pfnFree)(PVUSBURB pUrb);
998 /** Submit timestamp. (logging only) */
999 uint64_t u64SubmitTS;
1000 /** The allocated data length. */
1001 uint32_t cbDataAllocated;
1002 /** The allocated TD length. */
1003 uint32_t cTdsAllocated;
1004 } VUsb;
1005
1006 /** The host controller data. */
1007 struct VUSBURBHCI
1008 {
1009 /** The endpoint descriptor address. */
1010 RTGCPHYS32 EdAddr;
1011 /** Number of Tds in the array. */
1012 uint32_t cTds;
1013 /** Pointer to an array of TD info items.*/
1014 struct VUSBURBHCITD
1015 {
1016 /** Type of TD (private) */
1017 uint32_t TdType;
1018 /** The address of the */
1019 RTGCPHYS32 TdAddr;
1020 /** A copy of the TD. */
1021 uint32_t TdCopy[16];
1022 } *paTds;
1023 /** URB chain pointer. */
1024 PVUSBURB pNext;
1025 /** When this URB was created.
1026 * (Used for isochronous frames and for logging.) */
1027 uint32_t u32FrameNo;
1028 /** Flag indicating that the TDs have been unlinked. */
1029 bool fUnlinked;
1030 } Hci;
1031
1032 /** The device data. */
1033 struct VUSBURBDEV
1034 {
1035 /** Pointer to the proxy URB. */
1036 void *pvProxyUrb;
1037 } Dev;
1038
1039 /** The USB device instance this belongs to.
1040 * This is NULL if the device address is invalid, in which case this belongs to the hub. */
1041 PPDMUSBINS pUsbIns;
1042 /** The device address.
1043 * This is set at allocation time. */
1044 uint8_t DstAddress;
1045
1046 /** The endpoint.
1047 * IN: Must be set before submitting the URB.
1048 * @remark This does not have the high bit (direction) set! */
1049 uint8_t EndPt;
1050 /** The transfer type.
1051 * IN: Must be set before submitting the URB. */
1052 VUSBXFERTYPE enmType;
1053 /** The transfer direction.
1054 * IN: Must be set before submitting the URB. */
1055 VUSBDIRECTION enmDir;
1056 /** Indicates whether it is OK to receive/send less data than requested.
1057 * IN: Must be initialized before submitting the URB. */
1058 bool fShortNotOk;
1059 /** The transfer status.
1060 * OUT: This is set when reaping the URB. */
1061 VUSBSTATUS enmStatus;
1062
1063 /** The number of isochronous packets describe in aIsocPkts.
1064 * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
1065 uint32_t cIsocPkts;
1066 /** The iso packets within abData.
1067 * This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
1068 VUSBURBISOCPKT aIsocPkts[8];
1069
1070 /** The message length.
1071 * IN: The amount of data to send / receive - set at allocation time.
1072 * OUT: The amount of data sent / received. */
1073 uint32_t cbData;
1074 /** The message data.
1075 * IN: On host to device transfers, the data to send.
1076 * OUT: On device to host transfers, the data to received. */
1077 uint8_t abData[8*_1K];
1078} VUSBURB;
1079
1080/** The magic value of a valid VUSBURB. (Murakami Haruki) */
1081#define VUSBURB_MAGIC 0x19490112
1082
1083/** @} */
1084
1085
1086/** @} */
1087
1088__END_DECLS
1089
1090#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