VirtualBox

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

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

Alignment.

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