vusb.h@ 3617

Last change on this file since 3617 was 3617, checked in by vboxsync, 17 years ago
Hacking USB (isoc mainly) for darwin; removed the obosolete urb prepare method; changed urb logging...
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 23.4 KB

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

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

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

Download in other formats: