vusb.h@ 321

Last change on this file since 321 was 1, checked in by vboxsync, 55 years ago
import
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 23.5 KB

Line
1	/** @file
2	* VUSB - VirtualBox USB.
3	*/
4
5	/*
6	* Copyright (C) 2006 InnoTek Systemberatung 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	DECLCALLBACKMEMBER(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	DECLCALLBACKMEMBER(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	DECLCALLBACKMEMBER(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	DECLCALLBACKMEMBER(int, pfnReset)(PVUSBIROOTHUBPORT pInterface, bool fResetOnLinux);
105
106	/**
107	* Do transmit preparations.
108	*
109	* VUSB will call this upon submitting the URB request.
110	*
111	* @param pInterface Pointer to this structure.
112	* @param pUrb Pointer to the URB in question.
113	*/
114	DECLCALLBACKMEMBER(void, pfnXferPrepare)(PVUSBIROOTHUBPORT pInterface, PVUSBURB pUrb);
115
116	/**
117	* Transfer completion callback routine.
118	*
119	* VUSB will call this when a transfer have been completed
120	* in a one or another way.
121	*
122	* @param pInterface Pointer to this structure.
123	* @param pUrb Pointer to the URB in question.
124	*/
125	DECLCALLBACKMEMBER(void, pfnXferCompletion)(PVUSBIROOTHUBPORT pInterface, PVUSBURB urb);
126
127	/**
128	* Handle transfer errors.
129	*
130	* VUSB calls this when a transfer attempt failed. This function will respond
131	* indicating wheter to retry or complete the URB with failure.
132	*
133	* @returns Retry indicator.
134	* @param pInterface Pointer to this structure.
135	* @param pUrb Pointer to the URB in question.
136	*/
137	DECLCALLBACKMEMBER(bool, pfnXferError)(PVUSBIROOTHUBPORT pInterface, PVUSBURB pUrb);
138
139	} VUSBIROOTHUBPORT;
140
141
142	/** Pointer to a VUSB RootHub connector interface. */
143	typedef struct VUSBIROOTHUBCONNECTOR *PVUSBIROOTHUBCONNECTOR;
144
145	/**
146	* The VUSB RootHub connector interface provided by the VBox USB RootHub driver.
147	*/
148	typedef struct VUSBIROOTHUBCONNECTOR
149	{
150	/**
151	* Allocates a new URB for a transfer.
152	*
153	* Either submit using pfnSubmitUrb or free using VUSBUrbFree().
154	*
155	* @returns Pointer to a new URB.
156	* @returns NULL on failure - try again later.
157	* This will not fail if the device wasn't found. We'll fail it
158	* at submit time, since that makes the usage of this api simpler.
159	* @param pInterface Pointer to this struct.
160	* @param DstAddress The destination address of the URB.
161	* @param cbData The amount of data space required.
162	* @param cTds The amount of TD space.
163	*/
164	DECLCALLBACKMEMBER(PVUSBURB, pfnNewUrb)(PVUSBIROOTHUBCONNECTOR pInterface, uint8_t DstAddress, uint32_t cbData, uint32_t cTds);
165
166	/**
167	* Submits a URB for transfer.
168	* The transfer will do asynchronously if possible.
169	*
170	* @returns VBox status code.
171	* @param pInterface Pointer to this struct.
172	* @param pUrb Pointer to the URB returned by pfnNewUrb.
173	* The URB will be freed in case of failure.
174	*/
175	DECLCALLBACKMEMBER(int, pfnSubmitUrb)(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBURB pUrb);
176
177	/**
178	* Call to service asynchronous URB completions in a polling fashion.
179	*
180	* Reaped URBs will be finished by calling the completion callback,
181	* thus there is no return code or input or anything from this function
182	* except for potential state changes elsewhere.
183	*
184	* @returns VINF_SUCCESS if no URBs are pending upon return.
185	* @returns VERR_TIMEOUT if one or more URBs are still in flight upon returning.
186	* @returns Other VBox status code.
187	*
188	* @param pInterface Pointer to this struct.
189	* @param cMillies Number of milliseconds to poll for completion.
190	*/
191	DECLCALLBACKMEMBER(void, pfnReapAsyncUrbs)(PVUSBIROOTHUBCONNECTOR pInterface, unsigned cMillies);
192
193	/**
194	* Cancels and completes - with CRC failure - all in-flight async URBs.
195	* This is typically done before saving a state.
196	*
197	* @param pInterface Pointer to this struct.
198	*/
199	DECLCALLBACKMEMBER(void, pfnCancelAllUrbs)(PVUSBIROOTHUBCONNECTOR pInterface);
200
201	/**
202	* Attach the device to the root hub.
203	* The device must not be attached to any hub 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) attach.
208	*/
209	DECLCALLBACKMEMBER(int, pfnAttachDevice)(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice);
210
211	/**
212	* Detach the device from the root hub.
213	* The device must already be attached for this call to succeed.
214	*
215	* @returns VBox status code.
216	* @param pInterface Pointer to this struct.
217	* @param pDevice Pointer to the device (interface) to detach.
218	*/
219	DECLCALLBACKMEMBER(int, pfnDetachDevice)(PVUSBIROOTHUBCONNECTOR pInterface, PVUSBIDEVICE pDevice);
220
221	} VUSBIROOTHUBCONNECTOR;
222
223
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
260
261
262	/** Pointer to a Root Hub Configuration Interface. */
263	typedef struct VUSBIRHCONFIG *PVUSBIRHCONFIG;
264
265	/**
266	* Root Hub Configuration Interface (intended for MAIN).
267	*/
268	typedef struct VUSBIRHCONFIG
269	{
270	/**
271	* Creates a USB proxy device and attaches it to the root hub.
272	*
273	* @returns VBox status code.
274	* @param pInterface Pointer to the root hub configuration interface structure.
275	* @param pUuid Pointer to the UUID for the new device.
276	* @param fRemote Whether the device must use the VRDP backend.
277	* @param pszAddress OS specific device address.
278	* @param pvBackend An opaque pointer for the backend. Only used by
279	* the VRDP backend so far.
280	*/
281	DECLCALLBACKMEMBER(int, pfnCreateProxyDevice)(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid, bool fRemote, const char pszAddress, void pvBackend);
282
283	/**
284	* Removes a USB proxy device from the root hub and destroys it.
285	*
286	* @returns VBox status code.
287	* @param pInterface Pointer to the root hub configuration interface structure.
288	* @param pUuid Pointer to the UUID for the device.
289	*/
290	DECLCALLBACKMEMBER(int, pfnDestroyProxyDevice)(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid);
291
292	} VUSBIRHCONFIG;
293
294	/** @copydoc VUSBIRHCONFIG::pfnCreateProxyDevice */
295	DECLINLINE(int) VUSBIRhCreateProxyDevice(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid, bool fRemote, const char pszAddress, void pvBackend)
296	{
297	return pInterface->pfnCreateProxyDevice(pInterface, pUuid, fRemote, pszAddress, pvBackend);
298	}
299
300	/** @copydoc VUSBIRHCONFIG::pfnDestroyProxyDevice */
301	DECLINLINE(int) VUSBIRhDestroyProxyDevice(PVUSBIRHCONFIG pInterface, PCRTUUID pUuid)
302	{
303	return pInterface->pfnDestroyProxyDevice(pInterface, pUuid);
304	}
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	DECLCALLBACKMEMBER(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	DECLCALLBACKMEMBER(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	DECLCALLBACKMEMBER(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	DECLCALLBACKMEMBER(VUSBDEVICESTATE, pfnGetState)(PVUSBIDEVICE pInterface);
414
415	} VUSBIDEVICE;
416
417
418	/**
419	* Resets the device.
420	*
421	* Since a device reset shall take at least 10ms from the guest point of view,
422	* it must be performed asynchronously. We create a thread which performs this
423	* operation and ensures it will take at least 10ms.
424	*
425	* At times - like init - a synchronous reset is required, this can be done
426	* by passing NULL for pfnDone.
427	*
428	* -- internal stuff, move it --
429	* While the device is being reset it is in the VUSB_DEVICE_STATE_RESET state.
430	* On completion it will be in the VUSB_DEVICE_STATE_DEFAULT state if successful,
431	* or in the VUSB_DEVICE_STATE_DETACHED state if the rest failed.
432	* -- internal stuff, move it --
433	*
434	* @returns VBox status code.
435	* @param pInterface Pointer to the device interface structure.
436	* @param fResetOnLinux Set if we can permit a real reset and a potential logical
437	* device reconnect on linux hosts.
438	* @param pfnDone Pointer to the completion routine. If NULL a synchronous
439	* reset is preformed not respecting the 10ms.
440	* @param pvUser User argument to the completion routine.
441	* @param pVM Pointer to the VM handle if callback in EMT is required. (optional)
442	*/
443	DECLINLINE(int) VUSBIDevReset(PVUSBIDEVICE pInterface, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM)
444	{
445	return pInterface->pfnReset(pInterface, fResetOnLinux, pfnDone, pvUser, pVM);
446	}
447
448	/**
449	* Powers on the device.
450	*
451	* @returns VBox status code.
452	* @param pInterface Pointer to the device interface structure.
453	*/
454	DECLINLINE(int) VUSBIDevPowerOn(PVUSBIDEVICE pInterface)
455	{
456	return pInterface->pfnPowerOn(pInterface);
457	}
458
459	/**
460	* Powers off the device.
461	*
462	* @returns VBox status code.
463	* @param pInterface Pointer to the device interface structure.
464	*/
465	DECLINLINE(int) VUSBIDevPowerOff(PVUSBIDEVICE pInterface)
466	{
467	return pInterface->pfnPowerOff(pInterface);
468	}
469
470	/**
471	* Get the state of the device.
472	*
473	* @returns Device state.
474	* @param pInterface Pointer to the device interface structure.
475	*/
476	DECLINLINE(VUSBDEVICESTATE) VUSBIDevGetState(PVUSBIDEVICE pInterface)
477	{
478	return pInterface->pfnGetState(pInterface);
479	}
480
481
482	/** @name URB
483	* @{ */
484
485	/**
486	* VUSB Transfer status codes.
487	*/
488	typedef enum VUSBSTATUS
489	{
490	/** Transer was ok. */
491	VUSBSTATUS_OK = 0,
492	#define VUSB_XFER_OK VUSBSTATUS_OK
493	/** Transfer stalled, endpoint halted. */
494	VUSBSTATUS_STALL,
495	#define VUSB_XFER_STALL VUSBSTATUS_STALL
496	/** Device not responding. */
497	VUSBSTATUS_DNR,
498	#define VUSB_XFER_DNR VUSBSTATUS_DNR
499	/** CRC error. */
500	VUSBSTATUS_CRC,
501	#define VUSB_XFER_CRC VUSBSTATUS_CRC
502	/** Underflow error. */
503	VUSBSTATUS_UNDERFLOW,
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	#define VUSB_TRANSFER_TYPE_CTRL VUSBXFERTYPE_CTRL
519	/* Isochronous transfer. */
520	VUSBXFERTYPE_ISOC,
521	#define VUSB_TRANSFER_TYPE_ISOC VUSBXFERTYPE_ISOC
522	/** Bulk transfer. */
523	VUSBXFERTYPE_BULK,
524	#define VUSB_TRANSFER_TYPE_BULK VUSBXFERTYPE_BULK
525	/** Interrupt transfer. */
526	VUSBXFERTYPE_INTR,
527	#define VUSB_TRANSFER_TYPE_INTR VUSBXFERTYPE_INTR
528	/** Complete control message. Used to represent an entire control message. */
529	VUSBXFERTYPE_MSG,
530	#define VUSB_TRANSFER_TYPE_MSG VUSBXFERTYPE_MSG
531	/** Invalid transfer type. */
532	VUSBXFERTYPE_INVALID = 0x7f
533	} VUSBXFERTYPE;
534
535
536	/**
537	* VUSB transfer direction.
538	*/
539	typedef enum VUSBDIRECTION
540	{
541	/** Setup */
542	VUSBDIRECTION_SETUP = 0,
543	#define VUSB_DIRECTION_SETUP VUSBDIRECTION_SETUP
544	/** In - Device to host. */
545	VUSBDIRECTION_IN = 1,
546	#define VUSB_DIRECTION_IN VUSBDIRECTION_IN
547	/** Out - Host to device. */
548	VUSBDIRECTION_OUT = 2,
549	#define VUSB_DIRECTION_OUT VUSBDIRECTION_OUT
550	/** Invalid direction */
551	VUSBDIRECTION_INVALID = 0x7f
552	} VUSBDIRECTION;
553
554	/**
555	* The URB states
556	*/
557	typedef enum VUSBURBSTATE
558	{
559	/** The usual invalid state. */
560	VUSBURBSTATE_INVALID = 0,
561	/** The URB is free, i.e. not in use.
562	* Next state: ALLOCATED */
563	VUSBURBSTATE_FREE,
564	/** The URB is allocated, i.e. being prepared for submission.
565	* Next state: FREE, IN_FLIGHT */
566	VUSBURBSTATE_ALLOCATED,
567	/** The URB is in flight.
568	* Next state: REAPED, CANCELLED */
569	VUSBURBSTATE_IN_FLIGHT,
570	/** The URB has been reaped and is being completed.
571	* Next state: FREE */
572	VUSBURBSTATE_REAPED,
573	/** The URB has been cancelled and is awaiting reaping and immediate freeing.
574	* Next state: FREE */
575	VUSBURBSTATE_CANCELLED,
576	/** The end of the valid states (exclusive). */
577	VUSBURBSTATE_END,
578	/** The usual 32-bit blow up. */
579	VUSBURBSTATE_32BIT_HACK = 0x7fffffff
580	} VUSBURBSTATE;
581
582
583	/**
584	* Information about a isochronous packet.
585	*/
586	typedef struct VUSBURBISOCPKT
587	{
588	/** The size of the packet.
589	* IN: The packet size. I.e. the number of bytes to the next packet or end of buffer.
590	* OUT: The actual size transfered. */
591	uint16_t cb;
592	/** The offset of the packet. (Relative to VUSBURB::abData[0].)
593	* OUT: This can be changed by the USB device if it does some kind of buffer squeezing. */
594	uint16_t off;
595	/** The status of the transfer.
596	* IN: VUSBSTATUS_INVALID
597	* OUT: VUSBSTATUS_INVALID if nothing was done, otherwise the correct status. */
598	VUSBSTATUS enmStatus;
599	} VUSBURBISOCPKT;
600	/** Pointer to a isochronous packet. */
601	typedef VUSBURBISOCPKT *PVUSBURBISOCPTK;
602	/** Pointer to a const isochronous packet. */
603	typedef const VUSBURBISOCPKT *PCVUSBURBISOCPKT;
604
605	/**
606	* Asynchronous USB request descriptor
607	*/
608	typedef struct vusb_urb
609	{
610	/** URB magic value. */
611	uint32_t u32Magic;
612	/** The USR state. */
613	VUSBURBSTATE enmState;
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 - can be NULL untill submit 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@ 321

Download in other formats: