vusb.h@ 4071

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

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

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

Download in other formats: