VUSBInternal.h@ 52305

Last change on this file since 52305 was 52305, checked in by vboxsync, 10 years ago
Build fix, take 3
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.2 KB

Line
1	/* $Id: VUSBInternal.h 52305 2014-08-06 17:33:03Z vboxsync $ */
2	/** @file
3	* Virtual USB - Internal header.
4	*
5	* This subsystem implements USB devices in a host controller independent
6	* way. All the host controller code has to do is use VUSBHUB for its
7	* root hub implementation and any emulated USB device may be plugged into
8	* the virtual bus.
9	*/
10
11	/*
12	* Copyright (C) 2006-2011 Oracle Corporation
13	*
14	* This file is part of VirtualBox Open Source Edition (OSE), as
15	* available from http://www.virtualbox.org. This file is free software;
16	* you can redistribute it and/or modify it under the terms of the GNU
17	* General Public License (GPL) as published by the Free Software
18	* Foundation, in version 2 as it comes in the "COPYING" file of the
19	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
20	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
21	*/
22
23	#ifndef ___VUSBInternal_h
24	#define ___VUSBInternal_h
25
26	#include <VBox/cdefs.h>
27	#include <VBox/types.h>
28	#include <VBox/vusb.h>
29	#include <VBox/vmm/stam.h>
30	#include <iprt/assert.h>
31	#include <iprt/queueatomic.h>
32	#include <iprt/req.h>
33
34	RT_C_DECLS_BEGIN
35
36
37	/** @name Internal Device Operations, Structures and Constants.
38	* @{
39	*/
40
41	/** Pointer to a Virtual USB device (core). */
42	typedef struct VUSBDEV *PVUSBDEV;
43	/** Pointer to a VUSB hub device. */
44	typedef struct VUSBHUB *PVUSBHUB;
45	/** Pointer to a VUSB root hub. */
46	typedef struct VUSBROOTHUB *PVUSBROOTHUB;
47
48
49	/** Number of the default control endpoint */
50	#define VUSB_PIPE_DEFAULT 0
51
52	/** @name Device addresses
53	* @{ */
54	#define VUSB_DEFAULT_ADDRESS 0
55	#define VUSB_INVALID_ADDRESS UINT8_C(0xff)
56	/** @} */
57
58	/** @name Feature bits (1<<FEATURE for the u16Status bit)
59	* @{ */
60	#define VUSB_DEV_SELF_POWERED 0
61	#define VUSB_DEV_REMOTE_WAKEUP 1
62	#define VUSB_EP_HALT 0
63	/** @} */
64
65	/** Maximum number of endpoint addresses */
66	#define VUSB_PIPE_MAX 16
67
68	/**
69	* Control-pipe stages.
70	*/
71	typedef enum CTLSTAGE
72	{
73	/** the control pipe is in the setup stage. */
74	CTLSTAGE_SETUP = 0,
75	/** the control pipe is in the data stage. */
76	CTLSTAGE_DATA,
77	/** the control pipe is in the status stage. */
78	CTLSTAGE_STATUS
79	} CTLSTAGE;
80
81	/**
82	* Extra data for a control pipe.
83	*
84	* This is state information needed for the special multi-stage
85	* transfers performed on this kind of pipes.
86	*/
87	typedef struct vusb_ctrl_extra
88	{
89	/** Current pipe stage. */
90	CTLSTAGE enmStage;
91	/** Success indicator. */
92	bool fOk;
93	/** Set if the message URB has been submitted. */
94	bool fSubmitted;
95	/** Pointer to the SETUP.
96	* This is a pointer to Urb->abData[0]. */
97	PVUSBSETUP pMsg;
98	/** Current DATA pointer.
99	* This starts at pMsg + 1 and is incremented at we read/write data. */
100	uint8_t *pbCur;
101	/** The amount of data left to read on IN operations.
102	* On OUT operations this is not used. */
103	uint32_t cbLeft;
104	/** The amount of data we can house.
105	* This starts at the default 8KB, and this structure will be reallocated to
106	* accommodate any larger request (unlikely). */
107	uint32_t cbMax;
108	/** The message URB. */
109	VUSBURB Urb;
110	} VUSBCTRLEXTRA, *PVUSBCTRLEXTRA;
111
112	void vusbMsgFreeExtraData(PVUSBCTRLEXTRA pExtra);
113	void vusbMsgResetExtraData(PVUSBCTRLEXTRA pExtra);
114
115	/** Opaque VUSB read ahead buffer management handle. */
116	typedef struct VUSBREADAHEADINT *VUSBREADAHEAD;
117
118	/**
119	* A VUSB pipe
120	*/
121	typedef struct vusb_pipe
122	{
123	PCVUSBDESCENDPOINTEX in;
124	PCVUSBDESCENDPOINTEX out;
125	/** Pointer to the extra state data required to run a control pipe. */
126	PVUSBCTRLEXTRA pCtrl;
127	/** Count of active async transfers. */
128	volatile uint32_t async;
129	/** Read ahead handle. */
130	VUSBREADAHEAD hReadAhead;
131	} VUSBPIPE;
132	/** Pointer to a VUSB pipe structure. */
133	typedef VUSBPIPE *PVUSBPIPE;
134
135
136	/**
137	* Interface state and possible settings.
138	*/
139	typedef struct vusb_interface_state
140	{
141	/** Pointer to the interface descriptor of the currently selected (active)
142	* interface. */
143	PCVUSBDESCINTERFACEEX pCurIfDesc;
144	/** Pointer to the interface settings. */
145	PCVUSBINTERFACE pIf;
146	} VUSBINTERFACESTATE;
147	/** Pointer to interface state. */
148	typedef VUSBINTERFACESTATE *PVUSBINTERFACESTATE;
149	/** Pointer to const interface state. */
150	typedef const VUSBINTERFACESTATE *PCVUSBINTERFACESTATE;
151
152
153	/**
154	* A Virtual USB device (core).
155	*
156	* @implements VUSBIDEVICE
157	*/
158	typedef struct VUSBDEV
159	{
160	/** The device interface exposed to the HCI. */
161	VUSBIDEVICE IDevice;
162	/** Pointer to the PDM USB device instance. */
163	PPDMUSBINS pUsbIns;
164	/** Next device in the chain maintained by the roothub. */
165	PVUSBDEV pNext;
166	/** Pointer to the next device with the same address hash. */
167	PVUSBDEV pNextHash;
168	/** Pointer to the hub this device is attached to. */
169	PVUSBHUB pHub;
170	/** The device state.
171	* Only EMT changes this value. */
172	VUSBDEVICESTATE volatile enmState;
173
174	/** The device address. */
175	uint8_t u8Address;
176	/** The new device address. */
177	uint8_t u8NewAddress;
178	/** The port. */
179	int16_t i16Port;
180	/** Device status. (VUSB_DEV_SELF_POWERED or not.) */
181	uint16_t u16Status;
182
183	/** Pointer to the descriptor cache.
184	* (Provided by the device thru the pfnGetDescriptorCache method.) */
185	PCPDMUSBDESCCACHE pDescCache;
186	/** Current configuration. */
187	PCVUSBDESCCONFIGEX pCurCfgDesc;
188
189	/** Current interface state (including alternate interface setting) - maximum
190	* valid index is config->bNumInterfaces
191	*/
192	PVUSBINTERFACESTATE paIfStates;
193
194	/** Pipe/direction -> endpoint descriptor mapping */
195	VUSBPIPE aPipes[VUSB_PIPE_MAX];
196	/** Critical section protecting the active URB list. */
197	RTCRITSECT CritSectAsyncUrbs;
198	/** List of active async URBs. */
199	PVUSBURB pAsyncUrbHead;
200
201	/** Dumper state. */
202	union VUSBDEVURBDUMPERSTATE
203	{
204	/** The current scsi command. */
205	uint8_t u8ScsiCmd;
206	} Urb;
207
208	/** The reset timer handle. */
209	PTMTIMER pResetTimer;
210	/** Reset handler arguments. */
211	void *pvArgs;
212	/** URB submit and reap thread. */
213	RTTHREAD hUrbIoThread;
214	/** Request queue for executing tasks on the I/O thread which should be done
215	* synchronous and without any other thread accessing the USB device. */
216	RTREQQUEUE hReqQueueSync;
217	/** Flag whether the URB I/O thread should terminate. */
218	bool volatile fTerminate;
219	/** Flag whether the I/O thread was woken up. */
220	bool volatile fWokenUp;
221	#if HC_ARCH_BITS == 32
222	/** Align the size to a 8 byte boundary. */
223	bool afAlignment0[2];
224	#endif
225	} VUSBDEV;
226	AssertCompileSizeAlignment(VUSBDEV, 8);
227
228
229	/** Pointer to the virtual method table for a kind of USB devices. */
230	typedef struct vusb_dev_ops *PVUSBDEVOPS;
231
232	/** Pointer to the const virtual method table for a kind of USB devices. */
233	typedef const struct vusb_dev_ops *PCVUSBDEVOPS;
234
235	/**
236	* Virtual method table for USB devices - these are the functions you need to
237	* implement when writing a new device (or hub)
238	*
239	* Note that when creating your structure, you are required to zero the
240	* vusb_dev fields (ie. use calloc).
241	*/
242	typedef struct vusb_dev_ops
243	{
244	/* mandatory */
245	const char *name;
246	} VUSBDEVOPS;
247
248
249	int vusbDevInit(PVUSBDEV pDev, PPDMUSBINS pUsbIns);
250	int vusbDevCreateOld(const char pszDeviceName, void pvDriverInit, PCRTUUID pUuid, PVUSBDEV *ppDev);
251	void vusbDevDestroy(PVUSBDEV pDev);
252
253	DECLINLINE(bool) vusbDevIsRh(PVUSBDEV pDev)
254	{
255	return (pDev->pHub == (PVUSBHUB)pDev);
256	}
257
258	bool vusbDevDoSelectConfig(PVUSBDEV dev, PCVUSBDESCCONFIGEX pCfg);
259	void vusbDevMapEndpoint(PVUSBDEV dev, PCVUSBDESCENDPOINTEX ep);
260	int vusbDevDetach(PVUSBDEV pDev);
261	DECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev);
262	size_t vusbDevMaxInterfaces(PVUSBDEV dev);
263
264	DECLCALLBACK(int) vusbDevReset(PVUSBIDEVICE pDevice, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM);
265	DECLCALLBACK(int) vusbDevPowerOn(PVUSBIDEVICE pInterface);
266	DECLCALLBACK(int) vusbDevPowerOff(PVUSBIDEVICE pInterface);
267	DECLCALLBACK(VUSBDEVICESTATE) vusbDevGetState(PVUSBIDEVICE pInterface);
268	void vusbDevSetAddress(PVUSBDEV pDev, uint8_t u8Address);
269	bool vusbDevStandardRequest(PVUSBDEV pDev, int EndPt, PVUSBSETUP pSetup, void pvBuf, uint32_t pcbBuf);
270
271
272	/** @} */
273
274
275
276
277
278	/** @name Internal Hub Operations, Structures and Constants.
279	* @{
280	*/
281
282
283	/** Virtual method table for USB hub devices.
284	* Hub and roothub drivers need to implement these functions in addition to the
285	* vusb_dev_ops.
286	*/
287	typedef struct VUSBHUBOPS
288	{
289	int (*pfnAttach)(PVUSBHUB pHub, PVUSBDEV pDev);
290	void (*pfnDetach)(PVUSBHUB pHub, PVUSBDEV pDev);
291	} VUSBHUBOPS;
292	/** Pointer to a const HUB method table. */
293	typedef const VUSBHUBOPS *PCVUSBHUBOPS;
294
295	/** A VUSB Hub Device - Hub and roothub drivers need to use this struct
296	* @todo eliminate this (PDM / roothubs only).
297	*/
298	typedef struct VUSBHUB
299	{
300	VUSBDEV Dev;
301	PCVUSBHUBOPS pOps;
302	PVUSBROOTHUB pRootHub;
303	uint16_t cPorts;
304	uint16_t cDevices;
305	/** Name of the hub. Used for logging. */
306	char *pszName;
307	} VUSBHUB;
308	AssertCompileMemberAlignment(VUSBHUB, pOps, 8);
309	AssertCompileSizeAlignment(VUSBHUB, 8);
310
311	/** @} */
312
313
314	/** @name Internal Root Hub Operations, Structures and Constants.
315	* @{
316	*/
317
318	/**
319	* Per transfer type statistics.
320	*/
321	typedef struct VUSBROOTHUBTYPESTATS
322	{
323	STAMCOUNTER StatUrbsSubmitted;
324	STAMCOUNTER StatUrbsFailed;
325	STAMCOUNTER StatUrbsCancelled;
326
327	STAMCOUNTER StatReqBytes;
328	STAMCOUNTER StatReqReadBytes;
329	STAMCOUNTER StatReqWriteBytes;
330
331	STAMCOUNTER StatActBytes;
332	STAMCOUNTER StatActReadBytes;
333	STAMCOUNTER StatActWriteBytes;
334	} VUSBROOTHUBTYPESTATS, *PVUSBROOTHUBTYPESTATS;
335
336
337
338	/** The address hash table size. */
339	#define VUSB_ADDR_HASHSZ 5
340
341	/**
342	* The instance data of a root hub driver.
343	*
344	* This extends the generic VUSB hub.
345	*
346	* @implements VUSBIROOTHUBCONNECTOR
347	*/
348	typedef struct VUSBROOTHUB
349	{
350	/** The HUB.
351	* @todo remove this? */
352	VUSBHUB Hub;
353	/** Address hash table. */
354	PVUSBDEV apAddrHash[VUSB_ADDR_HASHSZ];
355	/** The default address. */
356	PVUSBDEV pDefaultAddress;
357
358	/** Pointer to the driver instance. */
359	PPDMDRVINS pDrvIns;
360	/** Pointer to the root hub port interface we're attached to. */
361	PVUSBIROOTHUBPORT pIRhPort;
362	/** Connector interface exposed upwards. */
363	VUSBIROOTHUBCONNECTOR IRhConnector;
364
365	/** Critical section protecting the device list. */
366	RTCRITSECT CritSectDevices;
367	/** Chain of devices attached to this hub. */
368	PVUSBDEV pDevices;
369	/** Availability Bitmap. */
370	VUSBPORTBITMAP Bitmap;
371
372	/** Critical section protecting the free list. */
373	RTCRITSECT CritSectFreeUrbs;
374	/** Chain of free URBs. (Singly linked) */
375	PVUSBURB pFreeUrbs;
376	/** The number of URBs in the pool. */
377	uint32_t cUrbsInPool;
378	/** Version of the attached Host Controller. */
379	uint32_t fHcVersions;
380	#ifdef VBOX_WITH_STATISTICS
381	#if HC_ARCH_BITS == 32
382	uint32_t Alignment1; /*< Counters must be 64-bit aligned. /
383	#endif
384	VUSBROOTHUBTYPESTATS Total;
385	VUSBROOTHUBTYPESTATS aTypes[VUSBXFERTYPE_MSG];
386	STAMCOUNTER StatIsocReqPkts;
387	STAMCOUNTER StatIsocReqReadPkts;
388	STAMCOUNTER StatIsocReqWritePkts;
389	STAMCOUNTER StatIsocActPkts;
390	STAMCOUNTER StatIsocActReadPkts;
391	STAMCOUNTER StatIsocActWritePkts;
392	struct
393	{
394	STAMCOUNTER Pkts;
395	STAMCOUNTER Ok;
396	STAMCOUNTER Ok0;
397	STAMCOUNTER DataUnderrun;
398	STAMCOUNTER DataUnderrun0;
399	STAMCOUNTER DataOverrun;
400	STAMCOUNTER NotAccessed;
401	STAMCOUNTER Misc;
402	STAMCOUNTER Bytes;
403	} aStatIsocDetails[8];
404
405	STAMPROFILE StatReapAsyncUrbs;
406	STAMPROFILE StatSubmitUrb;
407	#endif
408	} VUSBROOTHUB;
409	AssertCompileMemberAlignment(VUSBROOTHUB, IRhConnector, 8);
410	AssertCompileMemberAlignment(VUSBROOTHUB, Bitmap, 8);
411	AssertCompileMemberAlignment(VUSBROOTHUB, CritSectDevices, 8);
412	AssertCompileMemberAlignment(VUSBROOTHUB, CritSectFreeUrbs, 8);
413	#ifdef VBOX_WITH_STATISTICS
414	AssertCompileMemberAlignment(VUSBROOTHUB, Total, 8);
415	#endif
416
417	/** Converts a pointer to VUSBROOTHUB::IRhConnector to a PVUSBROOTHUB. */
418	#define VUSBIROOTHUBCONNECTOR_2_VUSBROOTHUB(pInterface) (PVUSBROOTHUB)( (uintptr_t)(pInterface) - RT_OFFSETOF(VUSBROOTHUB, IRhConnector) )
419
420	/**
421	* URB cancellation modes
422	*/
423	typedef enum CANCELMODE
424	{
425	/** complete the URB with an error (CRC). */
426	CANCELMODE_FAIL = 0,
427	/** do not change the URB contents. */
428	CANCELMODE_UNDO
429	} CANCELMODE;
430
431	/* @} */
432
433
434
435	/** @name Internal URB Operations, Structures and Constants.
436	* @{ */
437	int vusbUrbSubmit(PVUSBURB pUrb);
438	void vusbUrbTrace(PVUSBURB pUrb, const char *pszMsg, bool fComplete);
439	void vusbUrbDoReapAsync(PVUSBURB pHead, RTMSINTERVAL cMillies);
440	void vusbUrbDoReapAsyncDev(PVUSBDEV pDev, RTMSINTERVAL cMillies);
441	void vusbUrbCancel(PVUSBURB pUrb, CANCELMODE mode);
442	void vusbUrbCancelAsync(PVUSBURB pUrb, CANCELMODE mode);
443	void vusbUrbRipe(PVUSBURB pUrb);
444	void vusbUrbCompletionRh(PVUSBURB pUrb);
445	int vusbUrbSubmitHardError(PVUSBURB pUrb);
446	int vusbUrbErrorRh(PVUSBURB pUrb);
447	int vusbDevUrbIoThreadWakeup(PVUSBDEV pDev);
448	int vusbDevUrbIoThreadCreate(PVUSBDEV pDev);
449	int vusbDevUrbIoThreadDestroy(PVUSBDEV pDev);
450	DECLHIDDEN(int) vusbDevIoThreadExecV(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
451	DECLHIDDEN(int) vusbDevIoThreadExec(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
452	DECLHIDDEN(int) vusbDevIoThreadExecSync(PVUSBDEV pDev, PFNRT pfnFunction, unsigned cArgs, ...);
453	DECLHIDDEN(void) vusbUrbCancelWorker(PVUSBURB pUrb, CANCELMODE enmMode);
454
455	void vusbUrbCompletionReadAhead(PVUSBURB pUrb);
456	VUSBREADAHEAD vusbReadAheadStart(PVUSBDEV pDev, PVUSBPIPE pPipe);
457	void vusbReadAheadStop(VUSBREADAHEAD hReadAhead);
458	int vusbUrbQueueAsyncRh(PVUSBURB pUrb);
459	int vusbUrbSubmitBufferedRead(PVUSBURB pUrb, VUSBREADAHEAD hReadAhead);
460	PVUSBURB vusbRhNewUrb(PVUSBROOTHUB pRh, uint8_t DstAddress, uint32_t cbData, uint32_t cTds);
461
462
463	DECLINLINE(void) vusbUrbUnlink(PVUSBURB pUrb)
464	{
465	PVUSBDEV pDev = pUrb->VUsb.pDev;
466
467	RTCritSectEnter(&pDev->CritSectAsyncUrbs);
468	*pUrb->VUsb.ppPrev = pUrb->VUsb.pNext;
469	if (pUrb->VUsb.pNext)
470	pUrb->VUsb.pNext->VUsb.ppPrev = pUrb->VUsb.ppPrev;
471	pUrb->VUsb.pNext = NULL;
472	pUrb->VUsb.ppPrev = NULL;
473	RTCritSectLeave(&pDev->CritSectAsyncUrbs);
474	}
475
476	/** @def vusbUrbAssert
477	* Asserts that a URB is valid.
478	*/
479	#ifdef VBOX_STRICT
480	# define vusbUrbAssert(pUrb) do { \
481	AssertMsg(VALID_PTR((pUrb)), ("%p\n", (pUrb))); \
482	AssertMsg((pUrb)->u32Magic == VUSBURB_MAGIC, ("%#x", (pUrb)->u32Magic)); \
483	AssertMsg((pUrb)->enmState > VUSBURBSTATE_INVALID && (pUrb)->enmState < VUSBURBSTATE_END, \
484	("%d\n", (pUrb)->enmState)); \
485	} while (0)
486	#else
487	# define vusbUrbAssert(pUrb) do {} while (0)
488	#endif
489
490	/** Executes a function synchronously. */
491	#define VUSB_DEV_IO_THREAD_EXEC_FLAGS_SYNC RT_BIT_32(0)
492
493	/** @} */
494
495
496
497
498	/**
499	* Addresses are between 0 and 127 inclusive
500	*/
501	DECLINLINE(uint8_t) vusbHashAddress(uint8_t Address)
502	{
503	uint8_t u8Hash = Address;
504	u8Hash ^= (Address >> 2);
505	u8Hash ^= (Address >> 3);
506	u8Hash %= VUSB_ADDR_HASHSZ;
507	return u8Hash;
508	}
509
510
511	/**
512	* Gets the roothub of a device.
513	*
514	* @returns Pointer to the roothub instance the device is attached to.
515	* @returns NULL if not attached to any hub.
516	* @param pDev Pointer to the device in question.
517	*/
518	DECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev)
519	{
520	if (!pDev->pHub)
521	return NULL;
522	return pDev->pHub->pRootHub;
523	}
524
525
526
527	/** Strings for the CTLSTAGE enum values. */
528	extern const char * const g_apszCtlStates[4];
529	/** Default message pipe. */
530	extern const VUSBDESCENDPOINTEX g_Endpoint0;
531	/** Default configuration. */
532	extern const VUSBDESCCONFIGEX g_Config0;
533
534	RT_C_DECLS_END
535	#endif
536

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

source: vbox/trunk/src/VBox/Devices/USB/VUSBInternal.h@ 52305

Download in other formats: