VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use