VUSBInternal.h@ 58364

Last change on this file since 58364 was 56395, checked in by vboxsync, 10 years ago
VUSB: Reverted r100358, fixed xHCI device attaching differently.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 17.2 KB

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

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

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

Download in other formats: