vusb.h@ 52749

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

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

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

Download in other formats: