VirtualBox

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

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

USB: Minor cleanup, kill a few unused declarations
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.2 KB
Line 
1/* $Id: VUSBInternal.h 56141 2015-05-28 17:43:35Z 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.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/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
332#if HC_ARCH_BITS == 32
333 uint32_t Alignment0;
334#endif
335
336 /** Pointer to the driver instance. */
337 PPDMDRVINS pDrvIns;
338 /** Pointer to the root hub port interface we're attached to. */
339 PVUSBIROOTHUBPORT pIRhPort;
340 /** Connector interface exposed upwards. */
341 VUSBIROOTHUBCONNECTOR IRhConnector;
342
343#if HC_ARCH_BITS == 32
344 uint32_t Alignment1;
345#endif
346
347 /** Critical section protecting the device list. */
348 RTCRITSECT CritSectDevices;
349 /** Chain of devices attached to this hub. */
350 PVUSBDEV pDevices;
351
352#if HC_ARCH_BITS == 32
353 uint32_t Alignment2;
354#endif
355
356 /** Availability Bitmap. */
357 VUSBPORTBITMAP Bitmap;
358
359 /** Critical section protecting the free list. */
360 RTCRITSECT CritSectFreeUrbs;
361 /** Chain of free URBs. (Singly linked) */
362 PVUSBURB pFreeUrbs;
363 /** Sniffer instance for the root hub. */
364 VUSBSNIFFER hSniffer;
365 /** The number of URBs in the pool. */
366 uint32_t cUrbsInPool;
367 /** Version of the attached Host Controller. */
368 uint32_t fHcVersions;
369#ifdef VBOX_WITH_STATISTICS
370 VUSBROOTHUBTYPESTATS Total;
371 VUSBROOTHUBTYPESTATS aTypes[VUSBXFERTYPE_MSG];
372 STAMCOUNTER StatIsocReqPkts;
373 STAMCOUNTER StatIsocReqReadPkts;
374 STAMCOUNTER StatIsocReqWritePkts;
375 STAMCOUNTER StatIsocActPkts;
376 STAMCOUNTER StatIsocActReadPkts;
377 STAMCOUNTER StatIsocActWritePkts;
378 struct
379 {
380 STAMCOUNTER Pkts;
381 STAMCOUNTER Ok;
382 STAMCOUNTER Ok0;
383 STAMCOUNTER DataUnderrun;
384 STAMCOUNTER DataUnderrun0;
385 STAMCOUNTER DataOverrun;
386 STAMCOUNTER NotAccessed;
387 STAMCOUNTER Misc;
388 STAMCOUNTER Bytes;
389 } aStatIsocDetails[8];
390
391 STAMPROFILE StatReapAsyncUrbs;
392 STAMPROFILE StatSubmitUrb;
393#endif
394} VUSBROOTHUB;
395AssertCompileMemberAlignment(VUSBROOTHUB, IRhConnector, 8);
396AssertCompileMemberAlignment(VUSBROOTHUB, Bitmap, 8);
397AssertCompileMemberAlignment(VUSBROOTHUB, CritSectDevices, 8);
398AssertCompileMemberAlignment(VUSBROOTHUB, CritSectFreeUrbs, 8);
399#ifdef VBOX_WITH_STATISTICS
400AssertCompileMemberAlignment(VUSBROOTHUB, Total, 8);
401#endif
402
403/** Converts a pointer to VUSBROOTHUB::IRhConnector to a PVUSBROOTHUB. */
404#define VUSBIROOTHUBCONNECTOR_2_VUSBROOTHUB(pInterface) (PVUSBROOTHUB)( (uintptr_t)(pInterface) - RT_OFFSETOF(VUSBROOTHUB, IRhConnector) )
405
406/**
407 * URB cancellation modes
408 */
409typedef enum CANCELMODE
410{
411 /** complete the URB with an error (CRC). */
412 CANCELMODE_FAIL = 0,
413 /** do not change the URB contents. */
414 CANCELMODE_UNDO
415} CANCELMODE;
416
417/* @} */
418
419
420
421/** @name Internal URB Operations, Structures and Constants.
422 * @{ */
423int vusbUrbSubmit(PVUSBURB pUrb);
424void vusbUrbTrace(PVUSBURB pUrb, const char *pszMsg, bool fComplete);
425void vusbUrbDoReapAsync(PVUSBURB pHead, RTMSINTERVAL cMillies);
426void vusbUrbDoReapAsyncDev(PVUSBDEV pDev, RTMSINTERVAL cMillies);
427void vusbUrbCancel(PVUSBURB pUrb, CANCELMODE mode);
428void vusbUrbCancelAsync(PVUSBURB pUrb, CANCELMODE mode);
429void vusbUrbRipe(PVUSBURB pUrb);
430void vusbUrbCompletionRh(PVUSBURB pUrb);
431int vusbUrbSubmitHardError(PVUSBURB pUrb);
432int vusbUrbErrorRh(PVUSBURB pUrb);
433int vusbDevUrbIoThreadWakeup(PVUSBDEV pDev);
434int vusbDevUrbIoThreadCreate(PVUSBDEV pDev);
435int vusbDevUrbIoThreadDestroy(PVUSBDEV pDev);
436DECLHIDDEN(int) vusbDevIoThreadExecV(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
437DECLHIDDEN(int) vusbDevIoThreadExec(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
438DECLHIDDEN(int) vusbDevIoThreadExecSync(PVUSBDEV pDev, PFNRT pfnFunction, unsigned cArgs, ...);
439DECLHIDDEN(int) vusbUrbCancelWorker(PVUSBURB pUrb, CANCELMODE enmMode);
440
441void vusbUrbCompletionReadAhead(PVUSBURB pUrb);
442VUSBREADAHEAD vusbReadAheadStart(PVUSBDEV pDev, PVUSBPIPE pPipe);
443void vusbReadAheadStop(VUSBREADAHEAD hReadAhead);
444int vusbUrbQueueAsyncRh(PVUSBURB pUrb);
445int vusbUrbSubmitBufferedRead(PVUSBURB pUrb, VUSBREADAHEAD hReadAhead);
446PVUSBURB vusbRhNewUrb(PVUSBROOTHUB pRh, uint8_t DstAddress, uint32_t cbData, uint32_t cTds);
447
448
449DECLINLINE(void) vusbUrbUnlink(PVUSBURB pUrb)
450{
451 PVUSBDEV pDev = pUrb->VUsb.pDev;
452
453 RTCritSectEnter(&pDev->CritSectAsyncUrbs);
454 *pUrb->VUsb.ppPrev = pUrb->VUsb.pNext;
455 if (pUrb->VUsb.pNext)
456 pUrb->VUsb.pNext->VUsb.ppPrev = pUrb->VUsb.ppPrev;
457 pUrb->VUsb.pNext = NULL;
458 pUrb->VUsb.ppPrev = NULL;
459 RTCritSectLeave(&pDev->CritSectAsyncUrbs);
460}
461
462/** @def vusbUrbAssert
463 * Asserts that a URB is valid.
464 */
465#ifdef VBOX_STRICT
466# define vusbUrbAssert(pUrb) do { \
467 AssertMsg(VALID_PTR((pUrb)), ("%p\n", (pUrb))); \
468 AssertMsg((pUrb)->u32Magic == VUSBURB_MAGIC, ("%#x", (pUrb)->u32Magic)); \
469 AssertMsg((pUrb)->enmState > VUSBURBSTATE_INVALID && (pUrb)->enmState < VUSBURBSTATE_END, \
470 ("%d\n", (pUrb)->enmState)); \
471 } while (0)
472#else
473# define vusbUrbAssert(pUrb) do {} while (0)
474#endif
475
476/**
477 * @def VUSBDEV_ASSERT_VALID_STATE
478 * Asserts that the give device state is valid.
479 */
480#define VUSBDEV_ASSERT_VALID_STATE(enmState) \
481 AssertMsg((enmState) > VUSB_DEVICE_STATE_INVALID && (enmState) < VUSB_DEVICE_STATE_DESTROYED, ("enmState=%#x\n", enmState));
482
483/** Executes a function synchronously. */
484#define VUSB_DEV_IO_THREAD_EXEC_FLAGS_SYNC RT_BIT_32(0)
485
486/** @} */
487
488
489
490
491/**
492 * Addresses are between 0 and 127 inclusive
493 */
494DECLINLINE(uint8_t) vusbHashAddress(uint8_t Address)
495{
496 uint8_t u8Hash = Address;
497 u8Hash ^= (Address >> 2);
498 u8Hash ^= (Address >> 3);
499 u8Hash %= VUSB_ADDR_HASHSZ;
500 return u8Hash;
501}
502
503
504/**
505 * Gets the roothub of a device.
506 *
507 * @returns Pointer to the roothub instance the device is attached to.
508 * @returns NULL if not attached to any hub.
509 * @param pDev Pointer to the device in question.
510 */
511DECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev)
512{
513 if (!pDev->pHub)
514 return NULL;
515 return pDev->pHub->pRootHub;
516}
517
518
519/**
520 * Returns the state of the USB device.
521 *
522 * @returns State of the USB device.
523 * @param pDev Pointer to the device.
524 */
525DECLINLINE(VUSBDEVICESTATE) vusbDevGetState(PVUSBDEV pDev)
526{
527 VUSBDEVICESTATE enmState = (VUSBDEVICESTATE)ASMAtomicReadU32((volatile uint32_t *)&pDev->enmState);
528 VUSBDEV_ASSERT_VALID_STATE(enmState);
529 return enmState;
530}
531
532
533/**
534 * Sets the given state for the USB device.
535 *
536 * @returns The old state of the device.
537 * @param pDev Pointer to the device.
538 * @param enmState The new state to set.
539 */
540DECLINLINE(VUSBDEVICESTATE) vusbDevSetState(PVUSBDEV pDev, VUSBDEVICESTATE enmState)
541{
542 VUSBDEV_ASSERT_VALID_STATE(enmState);
543 VUSBDEVICESTATE enmStateOld = (VUSBDEVICESTATE)ASMAtomicXchgU32((volatile uint32_t *)&pDev->enmState, enmState);
544 VUSBDEV_ASSERT_VALID_STATE(enmStateOld);
545 return enmStateOld;
546}
547
548
549/**
550 * Compare and exchange the states for the given USB device.
551 *
552 * @returns true if the state was changed.
553 * @returns false if the state wasn't changed.
554 * @param pDev Pointer to the device.
555 * @param enmStateNew The new state to set.
556 * @param enmStateOld The old state to compare with.
557 */
558DECLINLINE(bool) vusbDevSetStateCmp(PVUSBDEV pDev, VUSBDEVICESTATE enmStateNew, VUSBDEVICESTATE enmStateOld)
559{
560 VUSBDEV_ASSERT_VALID_STATE(enmStateNew);
561 VUSBDEV_ASSERT_VALID_STATE(enmStateOld);
562 return ASMAtomicCmpXchgU32((volatile uint32_t *)&pDev->enmState, enmStateNew, enmStateOld);
563}
564
565/** Strings for the CTLSTAGE enum values. */
566extern const char * const g_apszCtlStates[4];
567/** Default message pipe. */
568extern const VUSBDESCENDPOINTEX g_Endpoint0;
569/** Default configuration. */
570extern const VUSBDESCCONFIGEX g_Config0;
571
572RT_C_DECLS_END
573#endif
574
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