vusb.h@ 5999

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

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

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

Download in other formats: