VUSBInternal.h@ 83298

Last change on this file since 83298 was 82968, checked in by vboxsync, 5 years ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 22.9 KB

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

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

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

Download in other formats: