VUSBInternal.h revision 49e18d6e5fc87bd475db9dcacbfee7c98e2d1b30
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Virtual USB - Internal header.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * This subsystem implements USB devices in a host controller independent
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * way. All the host controller code has to do is use VUSBHUB for its
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * root hub implementation and any emulated USB device may be plugged into
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * the virtual bus.
c58f1213e628a545081c70e26c6b67a841cff880vboxsync * Copyright (C) 2006-2011 Oracle Corporation
82bcaaf8077ba892f39afb721dca149353c63d2cvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
82bcaaf8077ba892f39afb721dca149353c63d2cvboxsync * available from http://www.virtualbox.org. This file is free software;
82bcaaf8077ba892f39afb721dca149353c63d2cvboxsync * you can redistribute it and/or modify it under the terms of the GNU
82bcaaf8077ba892f39afb721dca149353c63d2cvboxsync * General Public License (GPL) as published by the Free Software
82bcaaf8077ba892f39afb721dca149353c63d2cvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
82bcaaf8077ba892f39afb721dca149353c63d2cvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
82bcaaf8077ba892f39afb721dca149353c63d2cvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** @name Internal Device Operations, Structures and Constants.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to a Virtual USB device (core). */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to a VUSB hub device. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to a VUSB root hub. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Number of the default control endpoint */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** @name Device addresses
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** @name Feature bits (1<<FEATURE for the u16Status bit)
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Maximum number of endpoint addresses */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Control-pipe stages.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** the control pipe is in the setup stage. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** the control pipe is in the data stage. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** the control pipe is in the status stage. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Extra data for a control pipe.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * This is state information needed for the special multi-stage
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * transfers performed on this kind of pipes.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Current pipe stage. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Success indicator. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Set if the message URB has been submitted. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the SETUP.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * This is a pointer to Urb->abData[0]. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Current DATA pointer.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * This starts at pMsg + 1 and is incremented at we read/write data. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The amount of data left to read on IN operations.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * On OUT operations this is not used. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The amount of data we can house.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * This starts at the default 8KB, and this structure will be reallocated to
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * accommodate any larger request (unlikely). */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The message URB. */
ff1ea1a768f003a41f4b02f742060708e633819avboxsync/** Opaque VUSB read ahead buffer management handle. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * A VUSB pipe
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsynctypedef struct vusb_pipe
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the extra state data required to run a control pipe. */
49e18d6e5fc87bd475db9dcacbfee7c98e2d1b30vboxsync /** Critical section serializing access to the extra state data for a control pipe. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Count of active async transfers. */
ff1ea1a768f003a41f4b02f742060708e633819avboxsync /** Read ahead handle. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to a VUSB pipe structure. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Interface state and possible settings.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the interface descriptor of the currently selected (active)
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * interface. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the interface settings. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to interface state. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to const interface state. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsynctypedef const VUSBINTERFACESTATE *PCVUSBINTERFACESTATE;
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * A Virtual USB device (core).
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * @implements VUSBIDEVICE
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsynctypedef struct VUSBDEV
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The device interface exposed to the HCI. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the PDM USB device instance. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Next device in the chain maintained by the roothub. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the next device with the same address hash. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the hub this device is attached to. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The device state.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Only EMT changes this value. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The device address. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The new device address. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The port. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Device status. (VUSB_DEV_SELF_POWERED or not.) */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the descriptor cache.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * (Provided by the device thru the pfnGetDescriptorCache method.) */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Current configuration. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Current interface state (including alternate interface setting) - maximum
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * valid index is config->bNumInterfaces
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pipe/direction -> endpoint descriptor mapping */
ebe394fa0ecbdea5feff1a5edfc2e17a2ccfbd25vboxsync /** Critical section protecting the active URB list. */
ebe394fa0ecbdea5feff1a5edfc2e17a2ccfbd25vboxsync /** List of active async URBs. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Dumper state. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The current scsi command. */
a3cc5474f3cdd349476201c13a2a1c60484ffbb2vboxsync /** The reset timer handle. */
c4bcf8396f4cc15b50a94fde59325a01ec80be34vboxsync /** Reset handler arguments. */
d0e467f88aeb4288b409908dbe1b96d07c7133b2vboxsync /** URB submit and reap thread. */
ff1ea1a768f003a41f4b02f742060708e633819avboxsync /** Request queue for executing tasks on the I/O thread which should be done
ff1ea1a768f003a41f4b02f742060708e633819avboxsync * synchronous and without any other thread accessing the USB device. */
d0e467f88aeb4288b409908dbe1b96d07c7133b2vboxsync /** Flag whether the URB I/O thread should terminate. */
d0e467f88aeb4288b409908dbe1b96d07c7133b2vboxsync bool volatile fTerminate;
d0e467f88aeb4288b409908dbe1b96d07c7133b2vboxsync /** Flag whether the I/O thread was woken up. */
d0e467f88aeb4288b409908dbe1b96d07c7133b2vboxsync bool volatile fWokenUp;
bf7f0c7283957d64d924ab166eda258706eb7531vboxsync /** Align the size to a 8 byte boundary. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to the virtual method table for a kind of USB devices. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to the const virtual method table for a kind of USB devices. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Virtual method table for USB devices - these are the functions you need to
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * implement when writing a new device (or hub)
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Note that when creating your structure, you are required to zero the
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * vusb_dev fields (ie. use calloc).
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsynctypedef struct vusb_dev_ops
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /* mandatory */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync const char *name;
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncint vusbDevCreateOld(const char *pszDeviceName, void *pvDriverInit, PCRTUUID pUuid, PVUSBDEV *ppDev);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncbool vusbDevDoSelectConfig(PVUSBDEV dev, PCVUSBDESCCONFIGEX pCfg);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncvoid vusbDevMapEndpoint(PVUSBDEV dev, PCVUSBDESCENDPOINTEX ep);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncDECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncDECLCALLBACK(int) vusbDevReset(PVUSBIDEVICE pDevice, bool fResetOnLinux, PFNVUSBRESETDONE pfnDone, void *pvUser, PVM pVM);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncDECLCALLBACK(int) vusbDevPowerOn(PVUSBIDEVICE pInterface);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncDECLCALLBACK(int) vusbDevPowerOff(PVUSBIDEVICE pInterface);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncDECLCALLBACK(VUSBDEVICESTATE) vusbDevGetState(PVUSBIDEVICE pInterface);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncvoid vusbDevSetAddress(PVUSBDEV pDev, uint8_t u8Address);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncbool vusbDevStandardRequest(PVUSBDEV pDev, int EndPt, PVUSBSETUP pSetup, void *pvBuf, uint32_t *pcbBuf);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** @name Internal Hub Operations, Structures and Constants.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Virtual method table for USB hub devices.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Hub and roothub drivers need to implement these functions in addition to the
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * vusb_dev_ops.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsynctypedef struct VUSBHUBOPS
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Pointer to a const HUB method table. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** A VUSB Hub Device - Hub and roothub drivers need to use this struct
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * @todo eliminate this (PDM / roothubs only).
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsynctypedef struct VUSBHUB
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Name of the hub. Used for logging. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** @name Internal Root Hub Operations, Structures and Constants.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Per transfer type statistics.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** The address hash table size. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * The instance data of a root hub driver.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * This extends the generic VUSB hub.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * @implements VUSBIROOTHUBCONNECTOR
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsynctypedef struct VUSBROOTHUB
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The HUB.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * @todo remove this? */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Address hash table. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The default address. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the driver instance. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Pointer to the root hub port interface we're attached to. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Connector interface exposed upwards. */
ebe394fa0ecbdea5feff1a5edfc2e17a2ccfbd25vboxsync /** Critical section protecting the device list. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Chain of devices attached to this hub. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Availability Bitmap. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Critical section protecting the free list. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Chain of free URBs. (Singly linked) */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** The number of URBs in the pool. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync /** Version of the attached Host Controller. */
1343c0dc573781e1f309076f3d9819915bff1705vboxsync uint32_t Alignment2; /**< Counters must be 64-bit aligned. */
ee271ac5f5a0f262528a59171392bffd9108509bvboxsyncAssertCompileMemberAlignment(VUSBROOTHUB, IRhConnector, 8);
ee271ac5f5a0f262528a59171392bffd9108509bvboxsyncAssertCompileMemberAlignment(VUSBROOTHUB, Bitmap, 8);
ebe394fa0ecbdea5feff1a5edfc2e17a2ccfbd25vboxsyncAssertCompileMemberAlignment(VUSBROOTHUB, CritSectDevices, 8);
ebe394fa0ecbdea5feff1a5edfc2e17a2ccfbd25vboxsyncAssertCompileMemberAlignment(VUSBROOTHUB, CritSectFreeUrbs, 8);
ee271ac5f5a0f262528a59171392bffd9108509bvboxsyncAssertCompileMemberAlignment(VUSBROOTHUB, Total, 8);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Converts a pointer to VUSBROOTHUB::IRhConnector to a PVUSBROOTHUB. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync#define VUSBIROOTHUBCONNECTOR_2_VUSBROOTHUB(pInterface) (PVUSBROOTHUB)( (uintptr_t)(pInterface) - RT_OFFSETOF(VUSBROOTHUB, IRhConnector) )
abe2f4a16e43726264648542b029e782337fbc9cvboxsync * URB cancellation modes
abe2f4a16e43726264648542b029e782337fbc9cvboxsync /** complete the URB with an error (CRC). */
abe2f4a16e43726264648542b029e782337fbc9cvboxsync /** do not change the URB contents. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** @name Internal URB Operations, Structures and Constants.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncvoid vusbUrbTrace(PVUSBURB pUrb, const char *pszMsg, bool fComplete);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncvoid vusbUrbDoReapAsync(PVUSBURB pHead, RTMSINTERVAL cMillies);
d0e467f88aeb4288b409908dbe1b96d07c7133b2vboxsyncvoid vusbUrbDoReapAsyncDev(PVUSBDEV pDev, RTMSINTERVAL cMillies);
ebe394fa0ecbdea5feff1a5edfc2e17a2ccfbd25vboxsyncvoid vusbUrbCancelAsync(PVUSBURB pUrb, CANCELMODE mode);
c4bcf8396f4cc15b50a94fde59325a01ec80be34vboxsyncDECLHIDDEN(int) vusbDevIoThreadExecV(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
c4bcf8396f4cc15b50a94fde59325a01ec80be34vboxsyncDECLHIDDEN(int) vusbDevIoThreadExec(PVUSBDEV pDev, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
ff1ea1a768f003a41f4b02f742060708e633819avboxsyncDECLHIDDEN(int) vusbDevIoThreadExecSync(PVUSBDEV pDev, PFNRT pfnFunction, unsigned cArgs, ...);
ebe394fa0ecbdea5feff1a5edfc2e17a2ccfbd25vboxsyncDECLHIDDEN(void) vusbUrbCancelWorker(PVUSBURB pUrb, CANCELMODE enmMode);
ff1ea1a768f003a41f4b02f742060708e633819avboxsyncVUSBREADAHEAD vusbReadAheadStart(PVUSBDEV pDev, PVUSBPIPE pPipe);
ff1ea1a768f003a41f4b02f742060708e633819avboxsyncint vusbUrbSubmitBufferedRead(PVUSBURB pUrb, VUSBREADAHEAD hReadAhead);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncPVUSBURB vusbRhNewUrb(PVUSBROOTHUB pRh, uint8_t DstAddress, uint32_t cbData, uint32_t cTds);
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** @def vusbUrbAssert
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Asserts that a URB is valid.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync AssertMsg((pUrb)->u32Magic == VUSBURB_MAGIC, ("%#x", (pUrb)->u32Magic)); \
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync AssertMsg((pUrb)->enmState > VUSBURBSTATE_INVALID && (pUrb)->enmState < VUSBURBSTATE_END, \
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync } while (0)
c4bcf8396f4cc15b50a94fde59325a01ec80be34vboxsync/** Executes a function synchronously. */
c4bcf8396f4cc15b50a94fde59325a01ec80be34vboxsync#define VUSB_DEV_IO_THREAD_EXEC_FLAGS_SYNC RT_BIT_32(0)
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Addresses are between 0 and 127 inclusive
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncDECLINLINE(uint8_t) vusbHashAddress(uint8_t Address)
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * Gets the roothub of a device.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * @returns Pointer to the roothub instance the device is attached to.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * @returns NULL if not attached to any hub.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync * @param pDev Pointer to the device in question.
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsyncDECLINLINE(PVUSBROOTHUB) vusbDevGetRh(PVUSBDEV pDev)
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Strings for the CTLSTAGE enum values. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Default message pipe. */
cb4a18edeb5422163b264fe5a66276769cfe864dvboxsync/** Default configuration. */