vusb.h@ 20087

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

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

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

Download in other formats: