VirtualBox

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

Last change on this file since 59701 was 59701, checked in by vboxsync, 9 years ago

VUSB: Some structural cleanup (#2 Remove the HCI specific bits from the VUSBURB structure and let each controller manage it by itself just telling the root hub how much space it needs for each URB)

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

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