vusb.h@ 5846

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

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

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

Download in other formats: