VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use