vusb.h@ 49092

Last change on this file since 49092 was 49092, checked in by vboxsync, 11 years ago
VUSB,EHCI,OHCI: Add a method to query whether a device is emulated or not. Required for working saved states when using the MSD device
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 35.8 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: