VUSBInternal.h@ 93934

最後變更在這個檔案從93934是 93934,由 vboxsync 提交於 3 年前
Devices/USB/DrvVUSBRootHub: Get rid of device list which is superseeded by the array of devices, bugref:10196
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Author Date Id Revision`
檔案大小: 23.3 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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

以其他格式下載: