vusb.h@ 35351

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

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

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

Download in other formats: