VirtualBox

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

Last change on this file since 52934 was 52881, checked in by vboxsync, 10 years ago

Devices/USB: Fix race when resetting USB devices causing a crash later

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette