vusb.h@ 3880

Last change on this file since 3880 was 3852, checked in by vboxsync, 18 years ago
Finally splitting up pdm.h. Working on integrating USB into PDM (USBProxy needs CFGM stuff).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 23.3 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	* If you received this file as part of a commercial VirtualBox
17	* distribution, then only the terms of your commercial VirtualBox
18	* license agreement apply instead of the previous paragraph.
19	*/
20
21	#ifndef ___VBox_vusb_h
22	#define ___VBox_vusb_h
23
24	#include <VBox/cdefs.h>
25	#include <VBox/types.h>
26
27	__BEGIN_DECLS
28
29	/** @defgroup grp_vusb VBox USB API
30	* @{
31	*/
32
33	/** Frequency of USB bus (from spec). */
34	#define VUSB_BUS_HZ 12000000
35
36	/** @name USB Standard version flags.
37	* @{ */
38	/** Indicates USB 1.1 support. */
39	#define VUSB_STDVER_11 BIT(1)
40	/** Indicates USB 2.0 support. */
41	#define VUSB_STDVER_20 BIT(2)
42	/** @} */
43
44
45
46	/** Pointer to a VBox USB device interface. */
47	typedef struct VUSBIDEVICE *PVUSBIDEVICE;
48
49	/** Pointer to a VUSB RootHub port interface. */
50	typedef struct VUSBIROOTHUBPORT *PVUSBIROOTHUBPORT;
51
52	/** Pointer to an USB request descriptor. */
53	typedef struct vusb_urb *PVUSBURB;
54
55
56
57	/**
58	* VBox USB port bitmap.
59	*
60	* Bit 0 == Port 0, ... , Bit 127 == Port 127.
61	*/
62	typedef struct VUSBPORTBITMAP
63	{
64	/** 128 bits */
65	char ach[16];
66	} VUSBPORTBITMAP;
67	/** Pointer to a VBox USB port bitmap. */
68	typedef VUSBPORTBITMAP *PVUSBPORTBITMAP;
69
70
71
72
73
74	/**
75	* The VUSB RootHub port interface provided by the HCI.
76	*/
77	typedef struct VUSBIROOTHUBPORT
78	{
79	/**
80	* Get the number of avilable ports in the hub.
81	*
82	* @returns The number of ports available.
83	* @param pInterface Pointer to this structure.
84	* @param pAvailable Bitmap indicating the available ports. Set bit == available port.
85	*/
86	DECLR3CALLBACKMEMBER(unsigned, pfnGetAvailablePorts,(PVUSBIROOTHUBPORT pInterface, PVUSBPORTBITMAP pAvailable));
87
88	/**
89	* A device is being attached to a port in the roothub.
90	*
91	* @param pInterface Pointer to this structure.
92	* @param pDev Pointer to the device being attached.
93	* @param uPort The port number assigned to the device.
94	*/
95	DECLR3CALLBACKMEMBER(int, pfnAttach,(PVUSBIROOTHUBPORT pInterface, PVUSBIDEVICE pDev, unsigned uPort));
96
97	/**
98	* A device is being detached from a port in the roothub.
99	*
100	* @param pInterface Pointer to this structure.
101	* @param pDev Pointer to the device being detached.
102	* @param uPort The port number assigned to the device.
103	*/
104	DECLR3CALLBACKMEMBER(void, pfnDetach,(PVUSBIROOTHUBPORT pInterface, PVUSBIDEVICE pDev, unsigned uPort));
105
106	/**
107	* Reset the root hub.
108	*
109	* @returns VBox status code.
110	* @param pInterface Pointer to this structure.
111	* @param pResetOnLinux Whether or not to do real reset on linux.
112	*/
113	DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIROOTHUBPORT pInterface, bool fResetOnLinux));
114
115	/**
116	* Transfer completion callback routine.
117	*
118	* VUSB will call this when a transfer have been completed
119	* in a one or another way.
120	*
121	* @param pInterface Pointer to this structure.
122	* @param pUrb Pointer to the URB in question.
123	*/
124	DECLR3CALLBACKMEMBER(void, pfnXferCompletion,(PVUSBIROOTHUBPORT pInterface, PVUSBURB urb));
125
126	/**
127	* Handle transfer errors.
128	*
129	* VUSB calls this when a transfer attempt failed. This function will respond
130	* indicating wheter to retry or complete the URB with failure.
131	*
132	* @returns Retry indicator.
133	* @param pInterface Pointer to this structure.
134	* @param pUrb Pointer to the URB in question.
135	*/
136	DECLR3CALLBACKMEMBER(bool, pfnXferError,(PVUSBIROOTHUBPORT pInterface, PVUSBURB pUrb));
137
138	} VUSBIROOTHUBPORT;
139
140
141	/** Pointer to a VUSB RootHub connector interface. */
142	typedef struct VUSBIROOTHUBCONNECTOR *PVUSBIROOTHUBCONNECTOR;
143
144	/**
145	* The VUSB RootHub connector interface provided by the VBox USB RootHub driver.
146	*/
147	typedef struct VUSBIROOTHUBCONNECTOR
148	{
149	/**
150	* Allocates a new URB for a transfer.
151	*
152	* Either submit using pfnSubmitUrb or free using VUSBUrbFree().
153	*
154	* @returns Pointer to a new URB.
155	* @returns NULL on failure - try again later.
156	* This will not fail if the device wasn't found. We'll fail it
157	* at submit time, since that makes the usage of this api simpler.
158	* @param pInterface Pointer to this struct.
159	* @param DstAddress The destination address of the URB.
160	* @param cbData The amount of data space required.
161	* @param cTds The amount of TD space.
162	*/
163	DECLR3CALLBACKMEMBER(PVUSBURB, pfnNewUrb,(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t cbData, uint32_t cTds));
164
165	/**
166	* Submits a URB for transfer.
167	* The transfer will do asynchronously if possible.
168	*
169	* @returns VBox status code.
170	* @param pInterface Pointer to this struct.
171	* @param pUrb Pointer to the URB returned by pfnNewUrb.
172	* The URB will be freed in case of failure.
173	*/
174	DECLR3CALLBACKMEMBER(int, pfnSubmitUrb,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb));
175
176	/**
177	* Call to service asynchronous URB completions in a polling fashion.
178	*
179	* Reaped URBs will be finished by calling the completion callback,
180	* thus there is no return code or input or anything from this function
181	* except for potential state changes elsewhere.
182	*
183	* @returns VINF_SUCCESS if no URBs are pending upon return.
184	* @returns VERR_TIMEOUT if one or more URBs are still in flight upon returning.
185	* @returns Other VBox status code.
186	*
187	* @param pInterface Pointer to this struct.
188	* @param cMillies Number of milliseconds to poll for completion.
189	*/
190	DECLR3CALLBACKMEMBER(void, pfnReapAsyncUrbs,(PVUSBIROOTHUBCONNECTOR pInterface, unsigned cMillies));
191
192	/**
193	* Cancels and completes - with CRC failure - all in-flight async URBs.
194	* This is typically done before saving a state.
195	*
196	* @param pInterface Pointer to this struct.
197	*/
198	DECLR3CALLBACKMEMBER(void, pfnCancelAllUrbs,(PVUSBIROOTHUBCONNECTOR pInterface));
199
200	/**
201	* Attach the device to the root hub.
202	* The device must not be attached to any hub for this call to succeed.
203	*
204	* @returns VBox status code.
205	* @param pInterface Pointer to this struct.
206	* @param pDevice Pointer to the device (interface) attach.
207	*/
208	DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice));
209
210	/**
211	* Detach the device from the root hub.
212	* The device must already be attached for this call to succeed.
213	*
214	* @returns VBox status code.
215	* @param pInterface Pointer to this struct.
216	* @param pDevice Pointer to the device (interface) to detach.
217	*/
218	DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice));
219
220	} VUSBIROOTHUBCONNECTOR;
221
222
223	#ifdef IN_RING3
224	/** @copydoc VUSBIROOTHUBCONNECTOR::pfnNewUrb */
225	DECLINLINE(PVUSBURB) VUSBIRhNewUrb(PVUSBIROOTHUBCONNECTOR pInterface, uint32_t DstAddress, uint32_t cbData, uint32_t cTds)
226	{
227	return pInterface->pfnNewUrb(pInterface, DstAddress, cbData, cTds);
228	}
229
230	/** @copydoc VUSBIROOTHUBCONNECTOR::pfnSubmitUrb */
231	DECLINLINE(int) VUSBIRhSubmitUrb(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb)
232	{
233	return pInterface->pfnSubmitUrb(pInterface, pUrb);
234	}
235
236	/** @copydoc VUSBIROOTHUBCONNECTOR::pfnReapAsyncUrbs */
237	DECLINLINE(void) VUSBIRhReapAsyncUrbs(PVUSBIROOTHUBCONNECTOR pInterface, unsigned cMillies)
238	{
239	pInterface->pfnReapAsyncUrbs(pInterface, cMillies);
240	}
241
242	/** @copydoc VUSBIROOTHUBCONNECTOR::pfnCancelAllUrbs */
243	DECLINLINE(void) VUSBIRhCancelAllUrbs(PVUSBIROOTHUBCONNECTOR pInterface)
244	{
245	pInterface->pfnCancelAllUrbs(pInterface);
246	}
247
248	/** @copydoc VUSBIROOTHUBCONNECTOR::pfnAttachDevice */
249	DECLINLINE(int) VUSBIRhAttachDevice(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice)
250	{
251	return pInterface->pfnAttachDevice(pInterface, pDevice);
252	}
253
254	/** @copydoc VUSBIROOTHUBCONNECTOR::pfnDetachDevice */
255	DECLINLINE(int) VUSBIRhDetachDevice(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice)
256	{
257	return pInterface->pfnDetachDevice(pInterface, pDevice);
258	}
259	#endif /* IN_RING3 */
260
261
262
263	/** Pointer to a Root Hub Configuration Interface. */
264	typedef struct VUSBIRHCONFIG *PVUSBIRHCONFIG;
265
266	/**
267	* Root Hub Configuration Interface (intended for MAIN).
268	*/
269	typedef struct VUSBIRHCONFIG
270	{
271	/**
272	* Creates a USB proxy device and attaches it to the root hub.
273	*
274	* @returns VBox status code.
275	* @param pInterface Pointer to the root hub configuration interface structure.
276	* @param pUuid Pointer to the UUID for the new device.
277	* @param fRemote Whether the device must use the VRDP backend.
278	* @param pszAddress OS specific device address.
279	* @param pvBackend An opaque pointer for the backend. Only used by
280	* the VRDP backend so far.
281	*/
282	DECLR3CALLBACKMEMBER(int, pfnCreateProxyDevice,(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid, bool fRemote, const char pszAddress, void pvBackend));
283
284	/**
285	* Removes a USB proxy device from the root hub and destroys it.
286	*
287	* @returns VBox status code.
288	* @param pInterface Pointer to the root hub configuration interface structure.
289	* @param pUuid Pointer to the UUID for the device.
290	*/
291	DECLR3CALLBACKMEMBER(int, pfnDestroyProxyDevice,(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid));
292
293	} VUSBIRHCONFIG;
294
295	#ifdef IN_RING3
296	/** @copydoc VUSBIRHCONFIG::pfnCreateProxyDevice */
297	DECLINLINE(int) VUSBIRhCreateProxyDevice(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid, bool fRemote, const char pszAddress, void pvBackend)
298	{
299	return pInterface->pfnCreateProxyDevice(pInterface, pUuid, fRemote, pszAddress, pvBackend);
300	}
301
302	/** @copydoc VUSBIRHCONFIG::pfnDestroyProxyDevice */
303	DECLINLINE(int) VUSBIRhDestroyProxyDevice(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid)
304	{
305	return pInterface->pfnDestroyProxyDevice(pInterface, pUuid);
306	}
307	#endif /* IN_RING3 */
308
309
310
311	/**
312	* VUSB device reset completion callback function.
313	* This is called by the reset thread when the reset has been completed.
314	*
315	* @param pDev Pointer to the virtual USB device core.
316	* @param rc The VBox status code of the reset operation.
317	* @param pvUser User specific argument.
318	*
319	* @thread The reset thread or EMT.
320	*/
321	typedef DECLCALLBACK(void) FNVUSBRESETDONE(PVUSBIDEVICE pDevice, int rc, void *pvUser);
322	/** Pointer to a device reset completion callback function (FNUSBRESETDONE). */
323	typedef FNVUSBRESETDONE *PFNVUSBRESETDONE;
324
325	/**
326	* The state of a VUSB Device.
327	*
328	* @remark The order of these states is vital.
329	*/
330	typedef enum VUSBDEVICESTATE
331	{
332	VUSB_DEVICE_STATE_INVALID = 0,
333	VUSB_DEVICE_STATE_DETACHED,
334	VUSB_DEVICE_STATE_ATTACHED,
335	VUSB_DEVICE_STATE_POWERED,
336	VUSB_DEVICE_STATE_DEFAULT,
337	VUSB_DEVICE_STATE_ADDRESS,
338	VUSB_DEVICE_STATE_CONFIGURED,
339	VUSB_DEVICE_STATE_SUSPENDED,
340	/** The device is being reset. Don't mess with it.
341	* Next states: VUSB_DEVICE_STATE_DEFAULT, VUSB_DEVICE_STATE_RESET_DESTROY
342	*/
343	VUSB_DEVICE_STATE_RESET,
344	/** The device is being reset and should be destroyed. Don't mess with it.
345	* Prev state: VUSB_DEVICE_STATE_RESET
346	* Next state: VUSB_DEVICE_STATE_DESTROY
347	*/
348	VUSB_DEVICE_STATE_RESET_DESTROY,
349	/** The device is being destroyed.
350	* Prev state: Any but VUSB_DEVICE_STATE_RESET
351	* Next state: VUSB_DEVICE_STATE_DESTROYED
352	*/
353	VUSB_DEVICE_STATE_DESTROY,
354	/** The device has been destroy. */
355	VUSB_DEVICE_STATE_DESTROYED,
356	/** The usual 32-bit hack. */
357	VUSB_DEVICE_STATE_32BIT_HACK = 0x7fffffff
358	} VUSBDEVICESTATE;
359
360
361	/**
362	* USB Device Interface.
363	*/
364	typedef struct VUSBIDEVICE
365	{
366	/**
367	* Resets the device.
368	*
369	* Since a device reset shall take at least 10ms from the guest point of view,
370	* it must be performed asynchronously. We create a thread which performs this
371	* operation and ensures it will take at least 10ms.
372	*
373	* At times - like init - a synchronous reset is required, this can be done
374	* by passing NULL for pfnDone.
375	*
376	* -- internal stuff, move it --
377	* While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
378	* On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
379	* or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
380	* -- internal stuff, move it --
381	*
382	* @returns VBox status code.
383	* @param pInterface Pointer to this structure.
384	* @param fResetOnLinux Set if we can permit a real reset and a potential logical
385	* device reconnect on linux hosts.
386	* @param pfnDone Pointer to the completion routine. If NULL a synchronous
387	* reset is preformed not respecting the 10ms.
388	* @param pvUser User argument to the completion routine.
389	* @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
390	*/
391	DECLR3CALLBACKMEMBER(int, pfnReset,(PVUSBIDEVICE pInterface, bool fResetOnLinux,
392	PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM));
393
394	/**
395	* Powers on the device.
396	*
397	* @returns VBox status code.
398	* @param pInterface Pointer to the device interface structure.
399	*/
400	DECLR3CALLBACKMEMBER(int, pfnPowerOn,(PVUSBIDEVICE pInterface));
401
402	/**
403	* Powers off the device.
404	*
405	* @returns VBox status code.
406	* @param pInterface Pointer to the device interface structure.
407	*/
408	DECLR3CALLBACKMEMBER(int, pfnPowerOff,(PVUSBIDEVICE pInterface));
409
410	/**
411	* Get the state of the device.
412	*
413	* @returns Device state.
414	* @param pInterface Pointer to the device interface structure.
415	*/
416	DECLR3CALLBACKMEMBER(VUSBDEVICESTATE, pfnGetState,(PVUSBIDEVICE pInterface));
417
418	} VUSBIDEVICE;
419
420
421	#ifdef IN_RING3
422	/**
423	* Resets the device.
424	*
425	* Since a device reset shall take at least 10ms from the guest point of view,
426	* it must be performed asynchronously. We create a thread which performs this
427	* operation and ensures it will take at least 10ms.
428	*
429	* At times - like init - a synchronous reset is required, this can be done
430	* by passing NULL for pfnDone.
431	*
432	* -- internal stuff, move it --
433	* While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
434	* On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
435	* or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
436	* -- internal stuff, move it --
437	*
438	* @returns VBox status code.
439	* @param pInterface Pointer to the device interface structure.
440	* @param fResetOnLinux Set if we can permit a real reset and a potential logical
441	* device reconnect on linux hosts.
442	* @param pfnDone Pointer to the completion routine. If NULL a synchronous
443	* reset is preformed not respecting the 10ms.
444	* @param pvUser User argument to the completion routine.
445	* @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
446	*/
447	DECLINLINE(int) VUSBIDevReset(PVUSBIDEVICE pInterface, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
448	{
449	return pInterface->pfnReset(pInterface, fResetOnLinux, pfnDone, pvUser, pVM);
450	}
451
452	/**
453	* Powers on the device.
454	*
455	* @returns VBox status code.
456	* @param pInterface Pointer to the device interface structure.
457	*/
458	DECLINLINE(int) VUSBIDevPowerOn(PVUSBIDEVICE pInterface)
459	{
460	return pInterface->pfnPowerOn(pInterface);
461	}
462
463	/**
464	* Powers off the device.
465	*
466	* @returns VBox status code.
467	* @param pInterface Pointer to the device interface structure.
468	*/
469	DECLINLINE(int) VUSBIDevPowerOff(PVUSBIDEVICE pInterface)
470	{
471	return pInterface->pfnPowerOff(pInterface);
472	}
473
474	/**
475	* Get the state of the device.
476	*
477	* @returns Device state.
478	* @param pInterface Pointer to the device interface structure.
479	*/
480	DECLINLINE(VUSBDEVICESTATE) VUSBIDevGetState(PVUSBIDEVICE pInterface)
481	{
482	return pInterface->pfnGetState(pInterface);
483	}
484	#endif /* IN_RING3 */
485
486
487	/** @name URB
488	* @{ */
489
490	/**
491	* VUSB Transfer status codes.
492	*/
493	typedef enum VUSBSTATUS
494	{
495	/** Transer was ok. */
496	VUSBSTATUS_OK = 0,
497	/** Transfer stalled, endpoint halted. */
498	VUSBSTATUS_STALL,
499	/** Device not responding. */
500	VUSBSTATUS_DNR,
501	/** CRC error. */
502	VUSBSTATUS_CRC,
503	/** Data overrun error. */
504	VUSBSTATUS_DATA_UNDERRUN,
505	/** Data overrun error. */
506	VUSBSTATUS_DATA_OVERRUN,
507	/** The isochronous buffer hasn't been touched. */
508	VUSBSTATUS_NOT_ACCESSED,
509	/** Invalid status. */
510	VUSBSTATUS_INVALID = 0x7f
511	} VUSBSTATUS;
512
513
514	/**
515	* VUSB Transfer types.
516	*/
517	typedef enum VUSBXFERTYPE
518	{
519	/** Control message. Used to represent a single control transfer. */
520	VUSBXFERTYPE_CTRL = 0,
521	/* Isochronous transfer. */
522	VUSBXFERTYPE_ISOC,
523	/** Bulk transfer. */
524	VUSBXFERTYPE_BULK,
525	/** Interrupt transfer. */
526	VUSBXFERTYPE_INTR,
527	/** Complete control message. Used to represent an entire control message. */
528	VUSBXFERTYPE_MSG,
529	/** Invalid transfer type. */
530	VUSBXFERTYPE_INVALID = 0x7f
531	} VUSBXFERTYPE;
532
533
534	/**
535	* VUSB transfer direction.
536	*/
537	typedef enum VUSBDIRECTION
538	{
539	/** Setup */
540	VUSBDIRECTION_SETUP = 0,
541	#define VUSB_DIRECTION_SETUP VUSBDIRECTION_SETUP
542	/** In - Device to host. */
543	VUSBDIRECTION_IN = 1,
544	#define VUSB_DIRECTION_IN VUSBDIRECTION_IN
545	/** Out - Host to device. */
546	VUSBDIRECTION_OUT = 2,
547	#define VUSB_DIRECTION_OUT VUSBDIRECTION_OUT
548	/** Invalid direction */
549	VUSBDIRECTION_INVALID = 0x7f
550	} VUSBDIRECTION;
551
552	/**
553	* The URB states
554	*/
555	typedef enum VUSBURBSTATE
556	{
557	/** The usual invalid state. */
558	VUSBURBSTATE_INVALID = 0,
559	/** The URB is free, i.e. not in use.
560	* Next state: ALLOCATED */
561	VUSBURBSTATE_FREE,
562	/** The URB is allocated, i.e. being prepared for submission.
563	* Next state: FREE, IN_FLIGHT */
564	VUSBURBSTATE_ALLOCATED,
565	/** The URB is in flight.
566	* Next state: REAPED, CANCELLED */
567	VUSBURBSTATE_IN_FLIGHT,
568	/** The URB has been reaped and is being completed.
569	* Next state: FREE */
570	VUSBURBSTATE_REAPED,
571	/** The URB has been cancelled and is awaiting reaping and immediate freeing.
572	* Next state: FREE */
573	VUSBURBSTATE_CANCELLED,
574	/** The end of the valid states (exclusive). */
575	VUSBURBSTATE_END,
576	/** The usual 32-bit blow up. */
577	VUSBURBSTATE_32BIT_HACK = 0x7fffffff
578	} VUSBURBSTATE;
579
580
581	/**
582	* Information about a isochronous packet.
583	*/
584	typedef struct VUSBURBISOCPKT
585	{
586	/** The size of the packet.
587	* IN: The packet size. I.e. the number of bytes to the next packet or end of buffer.
588	* OUT: The actual size transfered. */
589	uint16_t cb;
590	/** The offset of the packet. (Relative to VUSBURB::abData[0].)
591	* OUT: This can be changed by the USB device if it does some kind of buffer squeezing. */
592	uint16_t off;
593	/** The status of the transfer.
594	* IN: VUSBSTATUS_INVALID
595	* OUT: VUSBSTATUS_INVALID if nothing was done, otherwise the correct status. */
596	VUSBSTATUS enmStatus;
597	} VUSBURBISOCPKT;
598	/** Pointer to a isochronous packet. */
599	typedef VUSBURBISOCPKT *PVUSBURBISOCPTK;
600	/** Pointer to a const isochronous packet. */
601	typedef const VUSBURBISOCPKT *PCVUSBURBISOCPKT;
602
603	/**
604	* Asynchronous USB request descriptor
605	*/
606	typedef struct vusb_urb
607	{
608	/** URB magic value. */
609	uint32_t u32Magic;
610	/** The USR state. */
611	VUSBURBSTATE enmState;
612	/** URB description, can be null. intended for logging. */
613	char *pszDesc;
614
615	/** The VUSB data. */
616	struct VUSBURBVUSB
617	{
618	/** URB chain pointer. */
619	PVUSBURB pNext;
620	/** URB chain pointer. */
621	PVUSBURB *ppPrev;
622	/** Pointer to the original for control messages. */
623	PVUSBURB pCtrlUrb;
624	/** Sepcific to the pfnFree function. */
625	void *pvFreeCtx;
626	/**
627	* Callback which will free the URB once it's reaped and completed.
628	* @param pUrb The URB.
629	*/
630	DECLCALLBACKMEMBER(void, pfnFree)(PVUSBURB pUrb);
631	/** Submit timestamp. (logging only) */
632	uint64_t u64SubmitTS;
633	/** The allocated data length. */
634	uint32_t cbDataAllocated;
635	/** The allocated TD length. */
636	uint32_t cTdsAllocated;
637	} VUsb;
638
639	/** The host controller data. */
640	struct VUSBURBHCI
641	{
642	/** The endpoint descriptor address. */
643	uint32_t EdAddr;
644	/** Number of Tds in the array. */
645	uint32_t cTds;
646	/** Pointer to an array of TD info items.*/
647	struct VUSBURBHCITD
648	{
649	/** The address of the */
650	uint32_t TdAddr;
651	/** A copy of the TD. */
652	uint32_t TdCopy[8];
653	} *paTds;
654	/** URB chain pointer. */
655	PVUSBURB pNext;
656	/** When this URB was created.
657	* (Used for isochronous frames and for logging.) */
658	uint32_t u32FrameNo;
659	/** Flag indicating that the TDs have been unlinked. */
660	bool fUnlinked;
661	} Hci;
662
663	/** The device data. */
664	struct VUSBURBDEV
665	{
666	/** Pointer to the proxy URB. */
667	void *pvProxyUrb;
668	} Dev;
669
670	/** The device - NULL until a submit has been is attempted.
671	* This is set when allocating the URB. */
672	struct vusb_dev *pDev;
673	/** The device address.
674	* This is set at allocation time. */
675	uint8_t DstAddress;
676
677	/** The endpoint.
678	* IN: Must be set before submitting the URB. */
679	uint8_t EndPt;
680	/** The transfer type.
681	* IN: Must be set before submitting the URB. */
682	VUSBXFERTYPE enmType;
683	/** The transfer direction.
684	* IN: Must be set before submitting the URB. */
685	VUSBDIRECTION enmDir;
686	/** Indicates whether it is OK to receive/send less data than requested.
687	* IN: Must be initialized before submitting the URB. */
688	bool fShortNotOk;
689	/** The transfer status.
690	* OUT: This is set when reaping the URB. */
691	VUSBSTATUS enmStatus;
692
693	/** The number of isochronous packets describe in aIsocPkts.
694	* This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
695	uint32_t cIsocPkts;
696	/** The iso packets within abData.
697	* This is ignored when enmType isn't VUSBXFERTYPE_ISOC. */
698	VUSBURBISOCPKT aIsocPkts[8];
699
700	/** The message length.
701	* IN: The amount of data to send / receive - set at allocation time.
702	* OUT: The amount of data sent / received. */
703	uint32_t cbData;
704	/** The message data.
705	* IN: On host to device transfers, the data to send.
706	* OUT: On device to host transfers, the data to received. */
707	uint8_t abData[8*_1K];
708	} VUSBURB;
709
710	/** The magic value of a valid VUSBURB. (Murakami Haruki) */
711	#define VUSBURB_MAGIC 0x19490112
712
713	/** @} */
714
715
716	/** @} */
717
718	__END_DECLS
719
720	#endif

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

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

Download in other formats: