vusb.h@ 5605

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

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

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

Download in other formats: