vusb.h@ 30683

Last change on this file since 30683 was 30653, checked in by vboxsync, 14 years ago
vusb: header updates
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 33.3 KB

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

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

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

Download in other formats: