vusb.h@ 32189

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

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

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

Download in other formats: