VirtualBox

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

Last change on this file since 82781 was 81369, checked in by vboxsync, 5 years ago

*: doxygen fixes
  • 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 81369 2019-10-18 21:13:03Z 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-2019 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
44RT_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). */
58typedef struct VUSBDEV *PVUSBDEV;
59/** Pointer to a VUSB hub device. */
60typedef struct VUSBHUB *PVUSBHUB;
61/** Pointer to a VUSB root hub. */
62typedef 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 */
87typedef 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 */
112typedef 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 */
128typedef 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
153void vusbMsgFreeExtraData(PVUSBCTRLEXTRA pExtra);
154void vusbMsgResetExtraData(PVUSBCTRLEXTRA pExtra);
155
156/**
157 * A VUSB pipe
158 */
159typedef 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. */
175typedef VUSBPIPE *PVUSBPIPE;
176
177
178/**
179 * Interface state and possible settings.
180 */
181typedef 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. */
190typedef VUSBINTERFACESTATE *PVUSBINTERFACESTATE;
191/** Pointer to const interface state. */
192typedef const VUSBINTERFACESTATE *PCVUSBINTERFACESTATE;
193
194
195/**
196 * VUSB URB pool.
197 */
198typedef 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. */
210typedef VUSBURBPOOL *PVUSBURBPOOL;
211
212AssertCompileSizeAlignment(VUSBURBPOOL, 8);
213
214/**
215 * A Virtual USB device (core).
216 *
217 * @implements VUSBIDEVICE
218 */
219typedef 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;
292AssertCompileSizeAlignment(VUSBDEV, 8);
293
294
295int vusbDevInit(PVUSBDEV pDev, PPDMUSBINS pUsbIns, const char *pszCaptureFilename);
296void vusbDevDestroy(PVUSBDEV pDev);
297
298DECLINLINE(bool) vusbDevIsRh(PVUSBDEV pDev)
299{
300 return (pDev->pHub == (PVUSBHUB)pDev);
301}
302
303bool vusbDevDoSelectConfig(PVUSBDEV dev, PCVUSBDESCCONFIGEX pCfg);
304void vusbDevMapEndpoint(PVUSBDEV dev, PCVUSBDESCENDPOINTEX ep);
305int vusbDevDetach(PVUSBDEV pDev);
306int vusbDevAttach(PVUSBDEV pDev, PVUSBHUB pHub);
307DECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev);
308size_t vusbDevMaxInterfaces(PVUSBDEV dev);
309
310void vusbDevSetAddress(PVUSBDEV pDev, uint8_t u8Address);
311bool 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 */
326typedef 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. */
332typedef 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 */
337typedef 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;
347AssertCompileMemberAlignment(VUSBHUB, pOps, 8);
348AssertCompileSizeAlignment(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 */
360typedef 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 */
387typedef 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;
484AssertCompileMemberAlignment(VUSBROOTHUB, IRhConnector, 8);
485AssertCompileMemberAlignment(VUSBROOTHUB, Bitmap, 8);
486AssertCompileMemberAlignment(VUSBROOTHUB, CritSectDevices, 8);
487#ifdef VBOX_WITH_STATISTICS
488AssertCompileMemberAlignment(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 */
497typedef 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 * @{ */
511int vusbUrbSubmit(PVUSBURB pUrb);
512void vusbUrbDoReapAsync(PRTLISTANCHOR pUrbLst, RTMSINTERVAL cMillies);
513void vusbUrbDoReapAsyncDev(PVUSBDEV pDev, RTMSINTERVAL cMillies);
514void vusbUrbCancel(PVUSBURB pUrb, CANCELMODE mode);
515void vusbUrbCancelAsync(PVUSBURB pUrb, CANCELMODE mode);
516void vusbUrbRipe(PVUSBURB pUrb);
517void vusbUrbCompletionRh(PVUSBURB pUrb);
518int vusbUrbSubmitHardError(PVUSBURB pUrb);
519int vusbUrbErrorRh(PVUSBURB pUrb);
520int vusbDevUrbIoThreadWakeup(PVUSBDEV pDev);
521int vusbDevUrbIoThreadCreate(PVUSBDEV pDev);
522int vusbDevUrbIoThreadDestroy(PVUSBDEV pDev);
523DECLHIDDEN(void) vusbDevCancelAllUrbs(PVUSBDEV pDev, bool fDetaching);
524DECLHIDDEN(int) vusbDevIoThreadExecV(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
525DECLHIDDEN(int) vusbDevIoThreadExec(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
526DECLHIDDEN(int) vusbDevIoThreadExecSync(PVUSBDEV pDev, PFNRT pfnFunction, unsigned cArgs, ...);
527DECLHIDDEN(int) vusbUrbCancelWorker(PVUSBURB pUrb, CANCELMODE enmMode);
528
529DECLHIDDEN(uint64_t) vusbRhR3ProcessFrame(PVUSBROOTHUB pThis, bool fCallback);
530
531int 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 */
539DECLHIDDEN(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 */
547DECLHIDDEN(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 */
561DECLHIDDEN(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 */
572DECLHIDDEN(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 */
583DECLHIDDEN(void) vusbUrbTrace(PVUSBURB pUrb, const char *pszMsg, bool fComplete);
584
585/**
586 * Return the USB direction as a string from the given enum.
587 */
588DECLHIDDEN(const char *) vusbUrbDirName(VUSBDIRECTION enmDir);
589
590/**
591 * Return the URB type as string from the given enum.
592 */
593DECLHIDDEN(const char *) vusbUrbTypeName(VUSBXFERTYPE enmType);
594
595/**
596 * Return the URB status as string from the given enum.
597 */
598DECLHIDDEN(const char *) vusbUrbStatusName(VUSBSTATUS enmStatus);
599#endif
600
601DECLINLINE(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 */
642DECLINLINE(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 */
659DECLINLINE(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 */
673DECLINLINE(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 */
688DECLINLINE(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 */
706DECLINLINE(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 */
719DECLINLINE(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 */
734DECLINLINE(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. */
746extern const char * const g_apszCtlStates[4];
747
748/** @} */
749RT_C_DECLS_END
750#endif /* !VBOX_INCLUDED_SRC_USB_VUSBInternal_h */
751
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use