vusb.h@ 39667

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

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

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

Download in other formats: