vusb.h@ 7944

Last change on this file since 7944 was 7567, checked in by vboxsync, 17 years ago
uint32_t -> RTGCPHYS32
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 31.6 KB

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

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

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

Download in other formats: