VUSBInternal.h@ 52379

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

Line
1	/* $Id: VUSBInternal.h 52307 2014-08-06 18:18:04Z 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	#if HC_ARCH_BITS == 32
366	uint32_t Alignment0;
367	#endif
368	/** Critical section protecting the device list. */
369	RTCRITSECT CritSectDevices;
370	/** Chain of devices attached to this hub. */
371	PVUSBDEV pDevices;
372
373	#if HC_ARCH_BITS == 32
374	uint32_t Alignment1;
375	#endif
376
377	/** Availability Bitmap. */
378	VUSBPORTBITMAP Bitmap;
379
380	/** Critical section protecting the free list. */
381	RTCRITSECT CritSectFreeUrbs;
382	/** Chain of free URBs. (Singly linked) */
383	PVUSBURB pFreeUrbs;
384	/** The number of URBs in the pool. */
385	uint32_t cUrbsInPool;
386	/** Version of the attached Host Controller. */
387	uint32_t fHcVersions;
388	#ifdef VBOX_WITH_STATISTICS
389	#if HC_ARCH_BITS == 32
390	uint32_t Alignment2; /*< Counters must be 64-bit aligned. /
391	#endif
392	VUSBROOTHUBTYPESTATS Total;
393	VUSBROOTHUBTYPESTATS aTypes[VUSBXFERTYPE_MSG];
394	STAMCOUNTER StatIsocReqPkts;
395	STAMCOUNTER StatIsocReqReadPkts;
396	STAMCOUNTER StatIsocReqWritePkts;
397	STAMCOUNTER StatIsocActPkts;
398	STAMCOUNTER StatIsocActReadPkts;
399	STAMCOUNTER StatIsocActWritePkts;
400	struct
401	{
402	STAMCOUNTER Pkts;
403	STAMCOUNTER Ok;
404	STAMCOUNTER Ok0;
405	STAMCOUNTER DataUnderrun;
406	STAMCOUNTER DataUnderrun0;
407	STAMCOUNTER DataOverrun;
408	STAMCOUNTER NotAccessed;
409	STAMCOUNTER Misc;
410	STAMCOUNTER Bytes;
411	} aStatIsocDetails[8];
412
413	STAMPROFILE StatReapAsyncUrbs;
414	STAMPROFILE StatSubmitUrb;
415	#endif
416	} VUSBROOTHUB;
417	AssertCompileMemberAlignment(VUSBROOTHUB, IRhConnector, 8);
418	AssertCompileMemberAlignment(VUSBROOTHUB, Bitmap, 8);
419	AssertCompileMemberAlignment(VUSBROOTHUB, CritSectDevices, 8);
420	AssertCompileMemberAlignment(VUSBROOTHUB, CritSectFreeUrbs, 8);
421	#ifdef VBOX_WITH_STATISTICS
422	AssertCompileMemberAlignment(VUSBROOTHUB, Total, 8);
423	#endif
424
425	/** Converts a pointer to VUSBROOTHUB::IRhConnector to a PVUSBROOTHUB. */
426	#define VUSBIROOTHUBCONNECTOR_2_VUSBROOTHUB(pInterface) (PVUSBROOTHUB)( (uintptr_t)(pInterface) - RT_OFFSETOF(VUSBROOTHUB, IRhConnector) )
427
428	/**
429	* URB cancellation modes
430	*/
431	typedef enum CANCELMODE
432	{
433	/** complete the URB with an error (CRC). */
434	CANCELMODE_FAIL = 0,
435	/** do not change the URB contents. */
436	CANCELMODE_UNDO
437	} CANCELMODE;
438
439	/* @} */
440
441
442
443	/** @name Internal URB Operations, Structures and Constants.
444	* @{ */
445	int vusbUrbSubmit(PVUSBURB pUrb);
446	void vusbUrbTrace(PVUSBURB pUrb, const char *pszMsg, bool fComplete);
447	void vusbUrbDoReapAsync(PVUSBURB pHead, RTMSINTERVAL cMillies);
448	void vusbUrbDoReapAsyncDev(PVUSBDEV pDev, RTMSINTERVAL cMillies);
449	void vusbUrbCancel(PVUSBURB pUrb, CANCELMODE mode);
450	void vusbUrbCancelAsync(PVUSBURB pUrb, CANCELMODE mode);
451	void vusbUrbRipe(PVUSBURB pUrb);
452	void vusbUrbCompletionRh(PVUSBURB pUrb);
453	int vusbUrbSubmitHardError(PVUSBURB pUrb);
454	int vusbUrbErrorRh(PVUSBURB pUrb);
455	int vusbDevUrbIoThreadWakeup(PVUSBDEV pDev);
456	int vusbDevUrbIoThreadCreate(PVUSBDEV pDev);
457	int vusbDevUrbIoThreadDestroy(PVUSBDEV pDev);
458	DECLHIDDEN(int) vusbDevIoThreadExecV(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
459	DECLHIDDEN(int) vusbDevIoThreadExec(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
460	DECLHIDDEN(int) vusbDevIoThreadExecSync(PVUSBDEV pDev, PFNRT pfnFunction, unsigned cArgs, ...);
461	DECLHIDDEN(void) vusbUrbCancelWorker(PVUSBURB pUrb, CANCELMODE enmMode);
462
463	void vusbUrbCompletionReadAhead(PVUSBURB pUrb);
464	VUSBREADAHEAD vusbReadAheadStart(PVUSBDEV pDev, PVUSBPIPE pPipe);
465	void vusbReadAheadStop(VUSBREADAHEAD hReadAhead);
466	int vusbUrbQueueAsyncRh(PVUSBURB pUrb);
467	int vusbUrbSubmitBufferedRead(PVUSBURB pUrb, VUSBREADAHEAD hReadAhead);
468	PVUSBURB vusbRhNewUrb(PVUSBROOTHUB pRh, uint8_t DstAddress, uint32_t cbData, uint32_t cTds);
469
470
471	DECLINLINE(void) vusbUrbUnlink(PVUSBURB pUrb)
472	{
473	PVUSBDEV pDev = pUrb->VUsb.pDev;
474
475	RTCritSectEnter(&pDev->CritSectAsyncUrbs);
476	*pUrb->VUsb.ppPrev = pUrb->VUsb.pNext;
477	if (pUrb->VUsb.pNext)
478	pUrb->VUsb.pNext->VUsb.ppPrev = pUrb->VUsb.ppPrev;
479	pUrb->VUsb.pNext = NULL;
480	pUrb->VUsb.ppPrev = NULL;
481	RTCritSectLeave(&pDev->CritSectAsyncUrbs);
482	}
483
484	/** @def vusbUrbAssert
485	* Asserts that a URB is valid.
486	*/
487	#ifdef VBOX_STRICT
488	# define vusbUrbAssert(pUrb) do { \
489	AssertMsg(VALID_PTR((pUrb)), ("%p\n", (pUrb))); \
490	AssertMsg((pUrb)->u32Magic == VUSBURB_MAGIC, ("%#x", (pUrb)->u32Magic)); \
491	AssertMsg((pUrb)->enmState > VUSBURBSTATE_INVALID && (pUrb)->enmState < VUSBURBSTATE_END, \
492	("%d\n", (pUrb)->enmState)); \
493	} while (0)
494	#else
495	# define vusbUrbAssert(pUrb) do {} while (0)
496	#endif
497
498	/** Executes a function synchronously. */
499	#define VUSB_DEV_IO_THREAD_EXEC_FLAGS_SYNC RT_BIT_32(0)
500
501	/** @} */
502
503
504
505
506	/**
507	* Addresses are between 0 and 127 inclusive
508	*/
509	DECLINLINE(uint8_t) vusbHashAddress(uint8_t Address)
510	{
511	uint8_t u8Hash = Address;
512	u8Hash ^= (Address >> 2);
513	u8Hash ^= (Address >> 3);
514	u8Hash %= VUSB_ADDR_HASHSZ;
515	return u8Hash;
516	}
517
518
519	/**
520	* Gets the roothub of a device.
521	*
522	* @returns Pointer to the roothub instance the device is attached to.
523	* @returns NULL if not attached to any hub.
524	* @param pDev Pointer to the device in question.
525	*/
526	DECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev)
527	{
528	if (!pDev->pHub)
529	return NULL;
530	return pDev->pHub->pRootHub;
531	}
532
533
534
535	/** Strings for the CTLSTAGE enum values. */
536	extern const char * const g_apszCtlStates[4];
537	/** Default message pipe. */
538	extern const VUSBDESCENDPOINTEX g_Endpoint0;
539	/** Default configuration. */
540	extern const VUSBDESCCONFIGEX g_Config0;
541
542	RT_C_DECLS_END
543	#endif
544

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

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

Download in other formats: