VUSBInternal.h@ 62477

Last change on this file since 62477 was 62294, checked in by vboxsync, 8 years ago
VUSB: Add reference couting to the USB device structure to prevent races between EMT and the worker threads when the device is attached leading to crashes
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 24.4 KB

Line
1	/* $Id: VUSBInternal.h 62294 2016-07-18 10:12:57Z 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 <VBox/vmm/pdm.h>
31	#include <VBox/vmm/vmapi.h>
32	#include <VBox/vmm/pdmusb.h>
33	#include <iprt/asm.h>
34	#include <iprt/assert.h>
35	#include <iprt/req.h>
36	#include <iprt/asm.h>
37	#include <iprt/list.h>
38
39	#include "VUSBSniffer.h"
40
41	RT_C_DECLS_BEGIN
42
43
44	/** @name Internal Device Operations, Structures and Constants.
45	* @{
46	*/
47
48	/** Pointer to a Virtual USB device (core). */
49	typedef struct VUSBDEV *PVUSBDEV;
50	/** Pointer to a VUSB hub device. */
51	typedef struct VUSBHUB *PVUSBHUB;
52	/** Pointer to a VUSB root hub. */
53	typedef struct VUSBROOTHUB *PVUSBROOTHUB;
54
55
56	/** Number of the default control endpoint */
57	#define VUSB_PIPE_DEFAULT 0
58
59	/** @name Device addresses
60	* @{ */
61	#define VUSB_DEFAULT_ADDRESS 0
62	#define VUSB_INVALID_ADDRESS UINT8_C(0xff)
63	/** @} */
64
65	/** @name Feature bits (1<<FEATURE for the u16Status bit)
66	* @{ */
67	#define VUSB_DEV_SELF_POWERED 0
68	#define VUSB_DEV_REMOTE_WAKEUP 1
69	#define VUSB_EP_HALT 0
70	/** @} */
71
72	/** Maximum number of endpoint addresses */
73	#define VUSB_PIPE_MAX 16
74
75	/**
76	* The VUSB URB data.
77	*/
78	typedef struct VUSBURBVUSBINT
79	{
80	/** Node for one of the lists the URB can be in. */
81	RTLISTNODE NdLst;
82	/** Pointer to the URB this structure is part of. */
83	PVUSBURB pUrb;
84	/** Pointer to the original for control messages. */
85	PVUSBURB pCtrlUrb;
86	/** Pointer to the VUSB device.
87	* This may be NULL if the destination address is invalid. */
88	PVUSBDEV pDev;
89	/** Specific to the pfnFree function. */
90	void *pvFreeCtx;
91	/**
92	* Callback which will free the URB once it's reaped and completed.
93	* @param pUrb The URB.
94	*/
95	DECLCALLBACKMEMBER(void, pfnFree)(PVUSBURB pUrb);
96	/** Submit timestamp. (logging only) */
97	uint64_t u64SubmitTS;
98	/** Opaque data holder when this is an URB from a buffered pipe. */
99	void *pvBuffered;
100	} VUSBURBVUSBINT;
101
102	/**
103	* Control-pipe stages.
104	*/
105	typedef enum CTLSTAGE
106	{
107	/** the control pipe is in the setup stage. */
108	CTLSTAGE_SETUP = 0,
109	/** the control pipe is in the data stage. */
110	CTLSTAGE_DATA,
111	/** the control pipe is in the status stage. */
112	CTLSTAGE_STATUS
113	} CTLSTAGE;
114
115	/**
116	* Extra data for a control pipe.
117	*
118	* This is state information needed for the special multi-stage
119	* transfers performed on this kind of pipes.
120	*/
121	typedef struct vusb_ctrl_extra
122	{
123	/** Current pipe stage. */
124	CTLSTAGE enmStage;
125	/** Success indicator. */
126	bool fOk;
127	/** Set if the message URB has been submitted. */
128	bool fSubmitted;
129	/** Pointer to the SETUP.
130	* This is a pointer to Urb->abData[0]. */
131	PVUSBSETUP pMsg;
132	/** Current DATA pointer.
133	* This starts at pMsg + 1 and is incremented at we read/write data. */
134	uint8_t *pbCur;
135	/** The amount of data left to read on IN operations.
136	* On OUT operations this is not used. */
137	uint32_t cbLeft;
138	/** The amount of data we can house.
139	* This starts at the default 8KB, and this structure will be reallocated to
140	* accommodate any larger request (unlikely). */
141	uint32_t cbMax;
142	/** The message URB. */
143	VUSBURB Urb;
144	} VUSBCTRLEXTRA, *PVUSBCTRLEXTRA;
145
146	void vusbMsgFreeExtraData(PVUSBCTRLEXTRA pExtra);
147	void vusbMsgResetExtraData(PVUSBCTRLEXTRA pExtra);
148
149	/** Opaque VUSB buffered pipe management handle. */
150	typedef struct VUSBBUFFEREDPIPEINT *VUSBBUFFEREDPIPE;
151	/** Pointer to a VUSB buffered pipe handle. */
152	typedef VUSBBUFFEREDPIPE *PVUSBBUFFEREDPIPE;
153
154	/**
155	* A VUSB pipe
156	*/
157	typedef struct vusb_pipe
158	{
159	PCVUSBDESCENDPOINTEX in;
160	PCVUSBDESCENDPOINTEX out;
161	/** Pointer to the extra state data required to run a control pipe. */
162	PVUSBCTRLEXTRA pCtrl;
163	/** Critical section serializing access to the extra state data for a control pipe. */
164	RTCRITSECT CritSectCtrl;
165	/** Count of active async transfers. */
166	volatile uint32_t async;
167	/** Pipe buffer - only valid for isochronous endpoints. */
168	VUSBBUFFEREDPIPE hBuffer;
169	} VUSBPIPE;
170	/** Pointer to a VUSB pipe structure. */
171	typedef VUSBPIPE *PVUSBPIPE;
172
173
174	/**
175	* Interface state and possible settings.
176	*/
177	typedef struct vusb_interface_state
178	{
179	/** Pointer to the interface descriptor of the currently selected (active)
180	* interface. */
181	PCVUSBDESCINTERFACEEX pCurIfDesc;
182	/** Pointer to the interface settings. */
183	PCVUSBINTERFACE pIf;
184	} VUSBINTERFACESTATE;
185	/** Pointer to interface state. */
186	typedef VUSBINTERFACESTATE *PVUSBINTERFACESTATE;
187	/** Pointer to const interface state. */
188	typedef const VUSBINTERFACESTATE *PCVUSBINTERFACESTATE;
189
190
191	/**
192	* VUSB URB pool.
193	*/
194	typedef struct VUSBURBPOOL
195	{
196	/** Critical section protecting the pool. */
197	RTCRITSECT CritSectPool;
198	/** Chain of free URBs by type. (Singly linked) */
199	RTLISTANCHOR aLstFreeUrbs[VUSBXFERTYPE_ELEMENTS];
200	/** The number of URBs in the pool. */
201	volatile uint32_t cUrbsInPool;
202	/** Align the size to a 8 byte boundary. */
203	uint32_t Alignment0;
204	} VUSBURBPOOL;
205	/** Pointer to a VUSB URB pool. */
206	typedef VUSBURBPOOL *PVUSBURBPOOL;
207
208	AssertCompileSizeAlignment(VUSBURBPOOL, 8);
209
210	/**
211	* A Virtual USB device (core).
212	*
213	* @implements VUSBIDEVICE
214	*/
215	typedef struct VUSBDEV
216	{
217	/** The device interface exposed to the HCI. */
218	VUSBIDEVICE IDevice;
219	/** Pointer to the PDM USB device instance. */
220	PPDMUSBINS pUsbIns;
221	/** Next device in the chain maintained by the roothub. */
222	PVUSBDEV pNext;
223	/** Pointer to the next device with the same address hash. */
224	PVUSBDEV pNextHash;
225	/** Pointer to the hub this device is attached to. */
226	PVUSBHUB pHub;
227	/** The device state. */
228	VUSBDEVICESTATE volatile enmState;
229	/** Reference counter to protect the device structure from going away. */
230	uint32_t volatile cRefs;
231
232	/** The device address. */
233	uint8_t u8Address;
234	/** The new device address. */
235	uint8_t u8NewAddress;
236	/** The port. */
237	int16_t i16Port;
238	/** Device status. (VUSB_DEV_SELF_POWERED or not.) */
239	uint16_t u16Status;
240
241	/** Pointer to the descriptor cache.
242	* (Provided by the device thru the pfnGetDescriptorCache method.) */
243	PCPDMUSBDESCCACHE pDescCache;
244	/** Current configuration. */
245	PCVUSBDESCCONFIGEX pCurCfgDesc;
246
247	/** Current interface state (including alternate interface setting) - maximum
248	* valid index is config->bNumInterfaces
249	*/
250	PVUSBINTERFACESTATE paIfStates;
251
252	/** Pipe/direction -> endpoint descriptor mapping */
253	VUSBPIPE aPipes[VUSB_PIPE_MAX];
254	/** Critical section protecting the active URB list. */
255	RTCRITSECT CritSectAsyncUrbs;
256	/** List of active async URBs. */
257	RTLISTANCHOR LstAsyncUrbs;
258
259	/** Dumper state. */
260	union VUSBDEVURBDUMPERSTATE
261	{
262	/** The current scsi command. */
263	uint8_t u8ScsiCmd;
264	} Urb;
265
266	/** The reset timer handle. */
267	PTMTIMER pResetTimer;
268	/** Reset handler arguments. */
269	void *pvArgs;
270	/** URB submit and reap thread. */
271	RTTHREAD hUrbIoThread;
272	/** Request queue for executing tasks on the I/O thread which should be done
273	* synchronous and without any other thread accessing the USB device. */
274	RTREQQUEUE hReqQueueSync;
275	/** Sniffer instance for this device if configured. */
276	VUSBSNIFFER hSniffer;
277	/** Flag whether the URB I/O thread should terminate. */
278	bool volatile fTerminate;
279	/** Flag whether the I/O thread was woken up. */
280	bool volatile fWokenUp;
281	#if HC_ARCH_BITS == 32
282	/** Align the size to a 8 byte boundary. */
283	bool afAlignment0[2];
284	#endif
285	/** The pool of free URBs for faster allocation. */
286	VUSBURBPOOL UrbPool;
287	} VUSBDEV;
288	AssertCompileSizeAlignment(VUSBDEV, 8);
289
290
291	int vusbDevInit(PVUSBDEV pDev, PPDMUSBINS pUsbIns, const char *pszCaptureFilename);
292	void vusbDevDestroy(PVUSBDEV pDev);
293
294	DECLINLINE(bool) vusbDevIsRh(PVUSBDEV pDev)
295	{
296	return (pDev->pHub == (PVUSBHUB)pDev);
297	}
298
299	bool vusbDevDoSelectConfig(PVUSBDEV dev, PCVUSBDESCCONFIGEX pCfg);
300	void vusbDevMapEndpoint(PVUSBDEV dev, PCVUSBDESCENDPOINTEX ep);
301	int vusbDevDetach(PVUSBDEV pDev);
302	DECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev);
303	size_t vusbDevMaxInterfaces(PVUSBDEV dev);
304
305	void vusbDevSetAddress(PVUSBDEV pDev, uint8_t u8Address);
306	bool vusbDevStandardRequest(PVUSBDEV pDev, int EndPt, PVUSBSETUP pSetup, void pvBuf, uint32_t pcbBuf);
307
308
309	/** @} */
310
311
312	/** @name Internal Hub Operations, Structures and Constants.
313	* @{
314	*/
315
316
317	/** Virtual method table for USB hub devices.
318	* Hub and roothub drivers need to implement these functions in addition to the
319	* vusb_dev_ops.
320	*/
321	typedef struct VUSBHUBOPS
322	{
323	int (*pfnAttach)(PVUSBHUB pHub, PVUSBDEV pDev);
324	void (*pfnDetach)(PVUSBHUB pHub, PVUSBDEV pDev);
325	} VUSBHUBOPS;
326	/** Pointer to a const HUB method table. */
327	typedef const VUSBHUBOPS *PCVUSBHUBOPS;
328
329	/** A VUSB Hub Device - Hub and roothub drivers need to use this struct
330	* @todo eliminate this (PDM / roothubs only).
331	*/
332	typedef struct VUSBHUB
333	{
334	VUSBDEV Dev;
335	PCVUSBHUBOPS pOps;
336	PVUSBROOTHUB pRootHub;
337	uint16_t cPorts;
338	uint16_t cDevices;
339	/** Name of the hub. Used for logging. */
340	char *pszName;
341	} VUSBHUB;
342	AssertCompileMemberAlignment(VUSBHUB, pOps, 8);
343	AssertCompileSizeAlignment(VUSBHUB, 8);
344
345	/** @} */
346
347
348	/** @name Internal Root Hub Operations, Structures and Constants.
349	* @{
350	*/
351
352	/**
353	* Per transfer type statistics.
354	*/
355	typedef struct VUSBROOTHUBTYPESTATS
356	{
357	STAMCOUNTER StatUrbsSubmitted;
358	STAMCOUNTER StatUrbsFailed;
359	STAMCOUNTER StatUrbsCancelled;
360
361	STAMCOUNTER StatReqBytes;
362	STAMCOUNTER StatReqReadBytes;
363	STAMCOUNTER StatReqWriteBytes;
364
365	STAMCOUNTER StatActBytes;
366	STAMCOUNTER StatActReadBytes;
367	STAMCOUNTER StatActWriteBytes;
368	} VUSBROOTHUBTYPESTATS, *PVUSBROOTHUBTYPESTATS;
369
370
371
372	/** The address hash table size. */
373	#define VUSB_ADDR_HASHSZ 5
374
375	/**
376	* The instance data of a root hub driver.
377	*
378	* This extends the generic VUSB hub.
379	*
380	* @implements VUSBIROOTHUBCONNECTOR
381	*/
382	typedef struct VUSBROOTHUB
383	{
384	/** The HUB.
385	* @todo remove this? */
386	VUSBHUB Hub;
387	/** Address hash table. */
388	PVUSBDEV apAddrHash[VUSB_ADDR_HASHSZ];
389	/** The default address. */
390	PVUSBDEV pDefaultAddress;
391
392	/** Pointer to the driver instance. */
393	PPDMDRVINS pDrvIns;
394	/** Pointer to the root hub port interface we're attached to. */
395	PVUSBIROOTHUBPORT pIRhPort;
396	/** Connector interface exposed upwards. */
397	VUSBIROOTHUBCONNECTOR IRhConnector;
398
399	/** Critical section protecting the device list. */
400	RTCRITSECT CritSectDevices;
401	/** Chain of devices attached to this hub. */
402	PVUSBDEV pDevices;
403
404	#if HC_ARCH_BITS == 32
405	uint32_t Alignment0;
406	#endif
407
408	/** Availability Bitmap. */
409	VUSBPORTBITMAP Bitmap;
410
411	/** Sniffer instance for the root hub. */
412	VUSBSNIFFER hSniffer;
413	/** Version of the attached Host Controller. */
414	uint32_t fHcVersions;
415	/** Size of the HCI specific data for each URB. */
416	size_t cbHci;
417	/** Size of the HCI specific TD. */
418	size_t cbHciTd;
419
420	/** The periodic frame processing thread. */
421	R3PTRTYPE(PPDMTHREAD) hThreadPeriodFrame;
422	/** Event semaphore to interact with the periodic frame processing thread. */
423	R3PTRTYPE(RTSEMEVENTMULTI) hSemEventPeriodFrame;
424	/** Event semaphore to release the thread waiting for the periodic frame processing thread to stop. */
425	R3PTRTYPE(RTSEMEVENTMULTI) hSemEventPeriodFrameStopped;
426	/** Current default frame rate for periodic frame processing thread. */
427	volatile uint32_t uFrameRateDefault;
428	/** Current frame rate (can be lower than the default frame rate if there is no activity). */
429	uint32_t uFrameRate;
430	/** How long to wait until the next frame. */
431	uint64_t nsWait;
432	/** Timestamp when the last frame was processed. */
433	uint64_t tsFrameProcessed;
434	/** Number of USB work cycles with no transfers. */
435	uint32_t cIdleCycles;
436
437	/** Flag whether a frame is currently being processed. */
438	volatile bool fFrameProcessing;
439
440	#if HC_ARCH_BITS == 32
441	uint32_t Alignment1;
442	#endif
443
444	#ifdef LOG_ENABLED
445	/** A serial number for URBs submitted on the roothub instance.
446	* Only logging builds. */
447	uint32_t iSerial;
448	/** Alignment */
449	uint32_t Alignment2;
450	#endif
451	#ifdef VBOX_WITH_STATISTICS
452	VUSBROOTHUBTYPESTATS Total;
453	VUSBROOTHUBTYPESTATS aTypes[VUSBXFERTYPE_MSG];
454	STAMCOUNTER StatIsocReqPkts;
455	STAMCOUNTER StatIsocReqReadPkts;
456	STAMCOUNTER StatIsocReqWritePkts;
457	STAMCOUNTER StatIsocActPkts;
458	STAMCOUNTER StatIsocActReadPkts;
459	STAMCOUNTER StatIsocActWritePkts;
460	struct
461	{
462	STAMCOUNTER Pkts;
463	STAMCOUNTER Ok;
464	STAMCOUNTER Ok0;
465	STAMCOUNTER DataUnderrun;
466	STAMCOUNTER DataUnderrun0;
467	STAMCOUNTER DataOverrun;
468	STAMCOUNTER NotAccessed;
469	STAMCOUNTER Misc;
470	STAMCOUNTER Bytes;
471	} aStatIsocDetails[8];
472
473	STAMPROFILE StatReapAsyncUrbs;
474	STAMPROFILE StatSubmitUrb;
475	STAMCOUNTER StatFramesProcessedClbk;
476	STAMCOUNTER StatFramesProcessedThread;
477	#endif
478	} VUSBROOTHUB;
479	AssertCompileMemberAlignment(VUSBROOTHUB, IRhConnector, 8);
480	AssertCompileMemberAlignment(VUSBROOTHUB, Bitmap, 8);
481	AssertCompileMemberAlignment(VUSBROOTHUB, CritSectDevices, 8);
482	#ifdef VBOX_WITH_STATISTICS
483	AssertCompileMemberAlignment(VUSBROOTHUB, Total, 8);
484	#endif
485
486	/** Converts a pointer to VUSBROOTHUB::IRhConnector to a PVUSBROOTHUB. */
487	#define VUSBIROOTHUBCONNECTOR_2_VUSBROOTHUB(pInterface) (PVUSBROOTHUB)( (uintptr_t)(pInterface) - RT_OFFSETOF(VUSBROOTHUB, IRhConnector) )
488
489	/**
490	* URB cancellation modes
491	*/
492	typedef enum CANCELMODE
493	{
494	/** complete the URB with an error (CRC). */
495	CANCELMODE_FAIL = 0,
496	/** do not change the URB contents. */
497	CANCELMODE_UNDO
498	} CANCELMODE;
499
500	/* @} */
501
502
503
504	/** @name Internal URB Operations, Structures and Constants.
505	* @{ */
506	int vusbUrbSubmit(PVUSBURB pUrb);
507	void vusbUrbDoReapAsync(PRTLISTANCHOR pUrbLst, RTMSINTERVAL cMillies);
508	void vusbUrbDoReapAsyncDev(PVUSBDEV pDev, RTMSINTERVAL cMillies);
509	void vusbUrbCancel(PVUSBURB pUrb, CANCELMODE mode);
510	void vusbUrbCancelAsync(PVUSBURB pUrb, CANCELMODE mode);
511	void vusbUrbRipe(PVUSBURB pUrb);
512	void vusbUrbCompletionRh(PVUSBURB pUrb);
513	int vusbUrbSubmitHardError(PVUSBURB pUrb);
514	int vusbUrbErrorRh(PVUSBURB pUrb);
515	int vusbDevUrbIoThreadWakeup(PVUSBDEV pDev);
516	int vusbDevUrbIoThreadCreate(PVUSBDEV pDev);
517	int vusbDevUrbIoThreadDestroy(PVUSBDEV pDev);
518	DECLHIDDEN(void) vusbDevCancelAllUrbs(PVUSBDEV pDev, bool fDetaching);
519	DECLHIDDEN(int) vusbDevIoThreadExecV(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
520	DECLHIDDEN(int) vusbDevIoThreadExec(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
521	DECLHIDDEN(int) vusbDevIoThreadExecSync(PVUSBDEV pDev, PFNRT pfnFunction, unsigned cArgs, ...);
522	DECLHIDDEN(int) vusbUrbCancelWorker(PVUSBURB pUrb, CANCELMODE enmMode);
523
524	DECLHIDDEN(uint64_t) vusbRhR3ProcessFrame(PVUSBROOTHUB pThis, bool fCallback);
525
526	int vusbUrbQueueAsyncRh(PVUSBURB pUrb);
527
528	/**
529	* Completes an URB from a buffered pipe.
530	*
531	* @returns nothing.
532	* @param pUrb The URB to complete.
533	*/
534	DECLHIDDEN(void) vusbBufferedPipeCompleteUrb(PVUSBURB pUrb);
535
536	/**
537	* Creates a new buffered pipe.
538	*
539	* @returns VBox status code.
540	* @retval VERR_NOT_SUPPORTED if buffering is not supported for the given pipe.
541	* @param pDev The device instance the pipe is associated with.
542	* @param pPipe The pipe to buffer.
543	* @param enmDirection The direction for the buffering.
544	* @param enmSpeed USB device speed.
545	* @param cLatencyMs The maximum latency the buffering should introduce, this influences
546	* the amount of data to buffer.
547	* @param phBuffer Where to store the handle to the buffer on success.
548	*/
549	DECLHIDDEN(int) vusbBufferedPipeCreate(PVUSBDEV pDev, PVUSBPIPE pPipe, VUSBDIRECTION enmDirection,
550	VUSBSPEED enmSpeed, uint32_t cLatencyMs,
551	PVUSBBUFFEREDPIPE phBuffer);
552
553	/**
554	* Destroys a buffered pipe, freeing all acquired resources.
555	*
556	* @returns nothing.
557	* @param hBuffer The buffered pipe handle.
558	*/
559	DECLHIDDEN(void) vusbBufferedPipeDestroy(VUSBBUFFEREDPIPE hBuffer);
560
561	/**
562	* Submits a URB from the HCD which is subject to buffering.
563	*
564	* @returns VBox status code.
565	* @param hBuffer The buffered pipe handle.
566	* @param pUrb The URB from the HCD which is subject to buffering.
567	*/
568	DECLHIDDEN(int) vusbBufferedPipeSubmitUrb(VUSBBUFFEREDPIPE hBuffer, PVUSBURB pUrb);
569
570	/**
571	* Initializes the given URB pool.
572	*
573	* @returns VBox status code.
574	* @param pUrbPool The URB pool to initialize.
575	*/
576	DECLHIDDEN(int) vusbUrbPoolInit(PVUSBURBPOOL pUrbPool);
577
578	/**
579	* Destroy a given URB pool freeing all ressources.
580	*
581	* @returns nothing.
582	* @param pUrbPool The URB pool to destroy.
583	*/
584	DECLHIDDEN(void) vusbUrbPoolDestroy(PVUSBURBPOOL pUrbPool);
585
586	/**
587	* Allocate a new URB from the given URB pool.
588	*
589	* @returns Pointer to the new URB or NULL if out of memory.
590	* @param pUrbPool The URB pool to allocate from.
591	* @param enmType Type of the URB.
592	* @param enmDir The direction of the URB.
593	* @param cbData The number of bytes to allocate for the data buffer.
594	* @param cbHci Size of the data private to the HCI for each URB when allocated.
595	* @param cbHciTd Size of one transfer descriptor.
596	* @param cTds Number of transfer descriptors.
597	*/
598	DECLHIDDEN(PVUSBURB) vusbUrbPoolAlloc(PVUSBURBPOOL pUrbPool, VUSBXFERTYPE enmType,
599	VUSBDIRECTION enmDir, size_t cbData,
600	size_t cbHci, size_t cbHciTd, unsigned cTds);
601
602	/**
603	* Frees a given URB.
604	*
605	* @returns nothing.
606	* @param pUrbPool The URB pool the URB was allocated from.
607	* @param pUrb The URB to free.
608	*/
609	DECLHIDDEN(void) vusbUrbPoolFree(PVUSBURBPOOL pUrbPool, PVUSBURB pUrb);
610
611	#ifdef LOG_ENABLED
612	/**
613	* Logs an URB in the debug log.
614	*
615	* @returns nothing.
616	* @param pUrb The URB to log.
617	* @param pszMsg Additional message to log.
618	* @param fComplete Flag whther the URB is completing.
619	*/
620	DECLHIDDEN(void) vusbUrbTrace(PVUSBURB pUrb, const char *pszMsg, bool fComplete);
621
622	/**
623	* Return the USB direction as a string from the given enum.
624	*/
625	DECLHIDDEN(const char *) vusbUrbDirName(VUSBDIRECTION enmDir);
626
627	/**
628	* Return the URB type as string from the given enum.
629	*/
630	DECLHIDDEN(const char *) vusbUrbTypeName(VUSBXFERTYPE enmType);
631
632	/**
633	* Return the URB status as string from the given enum.
634	*/
635	DECLHIDDEN(const char *) vusbUrbStatusName(VUSBSTATUS enmStatus);
636	#endif
637
638	DECLINLINE(void) vusbUrbUnlink(PVUSBURB pUrb)
639	{
640	PVUSBDEV pDev = pUrb->pVUsb->pDev;
641
642	RTCritSectEnter(&pDev->CritSectAsyncUrbs);
643	RTListNodeRemove(&pUrb->pVUsb->NdLst);
644	RTCritSectLeave(&pDev->CritSectAsyncUrbs);
645	}
646
647	/** @def vusbUrbAssert
648	* Asserts that a URB is valid.
649	*/
650	#ifdef VBOX_STRICT
651	# define vusbUrbAssert(pUrb) do { \
652	AssertMsg(VALID_PTR((pUrb)), ("%p\n", (pUrb))); \
653	AssertMsg((pUrb)->u32Magic == VUSBURB_MAGIC, ("%#x", (pUrb)->u32Magic)); \
654	AssertMsg((pUrb)->enmState > VUSBURBSTATE_INVALID && (pUrb)->enmState < VUSBURBSTATE_END, \
655	("%d\n", (pUrb)->enmState)); \
656	} while (0)
657	#else
658	# define vusbUrbAssert(pUrb) do {} while (0)
659	#endif
660
661	/**
662	* @def VUSBDEV_ASSERT_VALID_STATE
663	* Asserts that the give device state is valid.
664	*/
665	#define VUSBDEV_ASSERT_VALID_STATE(enmState) \
666	AssertMsg((enmState) > VUSB_DEVICE_STATE_INVALID && (enmState) < VUSB_DEVICE_STATE_DESTROYED, ("enmState=%#x\n", enmState));
667
668	/** Executes a function synchronously. */
669	#define VUSB_DEV_IO_THREAD_EXEC_FLAGS_SYNC RT_BIT_32(0)
670
671	/** @} */
672
673
674
675
676	/**
677	* Addresses are between 0 and 127 inclusive
678	*/
679	DECLINLINE(uint8_t) vusbHashAddress(uint8_t Address)
680	{
681	uint8_t u8Hash = Address;
682	u8Hash ^= (Address >> 2);
683	u8Hash ^= (Address >> 3);
684	u8Hash %= VUSB_ADDR_HASHSZ;
685	return u8Hash;
686	}
687
688
689	/**
690	* Gets the roothub of a device.
691	*
692	* @returns Pointer to the roothub instance the device is attached to.
693	* @returns NULL if not attached to any hub.
694	* @param pDev Pointer to the device in question.
695	*/
696	DECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev)
697	{
698	if (!pDev->pHub)
699	return NULL;
700	return pDev->pHub->pRootHub;
701	}
702
703
704	/**
705	* Returns the state of the USB device.
706	*
707	* @returns State of the USB device.
708	* @param pDev Pointer to the device.
709	*/
710	DECLINLINE(VUSBDEVICESTATE) vusbDevGetState(PVUSBDEV pDev)
711	{
712	VUSBDEVICESTATE enmState = (VUSBDEVICESTATE)ASMAtomicReadU32((volatile uint32_t *)&pDev->enmState);
713	VUSBDEV_ASSERT_VALID_STATE(enmState);
714	return enmState;
715	}
716
717
718	/**
719	* Sets the given state for the USB device.
720	*
721	* @returns The old state of the device.
722	* @param pDev Pointer to the device.
723	* @param enmState The new state to set.
724	*/
725	DECLINLINE(VUSBDEVICESTATE) vusbDevSetState(PVUSBDEV pDev, VUSBDEVICESTATE enmState)
726	{
727	VUSBDEV_ASSERT_VALID_STATE(enmState);
728	VUSBDEVICESTATE enmStateOld = (VUSBDEVICESTATE)ASMAtomicXchgU32((volatile uint32_t *)&pDev->enmState, enmState);
729	VUSBDEV_ASSERT_VALID_STATE(enmStateOld);
730	return enmStateOld;
731	}
732
733
734	/**
735	* Compare and exchange the states for the given USB device.
736	*
737	* @returns true if the state was changed.
738	* @returns false if the state wasn't changed.
739	* @param pDev Pointer to the device.
740	* @param enmStateNew The new state to set.
741	* @param enmStateOld The old state to compare with.
742	*/
743	DECLINLINE(bool) vusbDevSetStateCmp(PVUSBDEV pDev, VUSBDEVICESTATE enmStateNew, VUSBDEVICESTATE enmStateOld)
744	{
745	VUSBDEV_ASSERT_VALID_STATE(enmStateNew);
746	VUSBDEV_ASSERT_VALID_STATE(enmStateOld);
747	return ASMAtomicCmpXchgU32((volatile uint32_t *)&pDev->enmState, enmStateNew, enmStateOld);
748	}
749
750	/**
751	* Retains the given VUSB device pointer.
752	*
753	* @returns New reference count.
754	* @param pThis The VUSB device pointer.
755	*/
756	DECLINLINE(uint32_t) vusbDevRetain(PVUSBDEV pThis)
757	{
758	AssertPtrReturn(pThis, UINT32_MAX);
759
760	uint32_t cRefs = ASMAtomicIncU32(&pThis->cRefs);
761	AssertMsg(cRefs > 1 && cRefs < _1M, ("%#x %p\n", cRefs, pThis));
762	return cRefs;
763	}
764
765	/**
766	* Releases the given VUSB device pointer.
767	*
768	* @returns New reference count.
769	* @retval 0 if no onw is holding a reference anymore causing the device to be destroyed.
770	*/
771	DECLINLINE(uint32_t) vusbDevRelease(PVUSBDEV pThis)
772	{
773	AssertPtrReturn(pThis, UINT32_MAX);
774
775	uint32_t cRefs = ASMAtomicDecU32(&pThis->cRefs);
776	AssertMsg(cRefs < _1M, ("%#x %p\n", cRefs, pThis));
777	if (cRefs == 0)
778	vusbDevDestroy(pThis);
779	return cRefs;
780	}
781
782	/** Strings for the CTLSTAGE enum values. */
783	extern const char * const g_apszCtlStates[4];
784	/** Default message pipe. */
785	extern const VUSBDESCENDPOINTEX g_Endpoint0;
786	/** Default configuration. */
787	extern const VUSBDESCCONFIGEX g_Config0;
788
789	RT_C_DECLS_END
790	#endif
791

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

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

Download in other formats: