vusb.h@ 53098

Last change on this file since 53098 was 53098, checked in by vboxsync, 10 years ago
VUSB: Define a few new descriptor types.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 37.5 KB

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

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

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

Download in other formats: