pdmusb.h revision da957c069c2a3c582fe265ff88170ce4c42b499d
5b281ba489ca18f0380d7efc7a5108b606cce449vboxsync * PDM - Pluggable Device Manager, USB Devices.
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Copyright (C) 2006-2007 innotek GmbH
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * available from http://www.virtualbox.org. This file is free software;
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * you can redistribute it and/or modify it under the terms of the GNU
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * General Public License as published by the Free Software Foundation,
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * distribution. VirtualBox OSE is distributed in the hope that it will
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * be useful, but WITHOUT ANY WARRANTY of any kind.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * If you received this file as part of a commercial VirtualBox
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * distribution, then only the terms of your commercial VirtualBox
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * license agreement apply instead of the previous paragraph.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync/** @defgroup grp_pdm_usbdev USB Devices
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @ingroup grp_pdm
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync/** PDM USB Device Registration Structure,
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * This structure is used when registering a device from VBoxUsbRegister() in HC Ring-3.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * The PDM will make use of this structure untill the VM is destroyed.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsynctypedef struct PDMUSBREG
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync /** Structure version. PDM_DEVREG_VERSION defines the current version. */
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync /** Device name. */
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync /** The description of the device. The UTF-8 string pointed to shall, like this structure,
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * remain unchanged from registration till VM destruction. */
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync /** Flags, combination of the PDM_USBREG_FLAGS_* \#defines. */
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync /** Maximum number of instances (per VM). */
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync /** Size of the instance data. */
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * Construct an USB device instance for a VM.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @returns VBox status.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @param pUsbIns The USB device instance data.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * If the registration structure is needed, pUsbDev->pDevReg points to it.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @param iInstance Instance number. Use this to figure out which registers and such to use.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * The instance number is also found in pUsbDev->iInstance, but since it's
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * likely to be freqently used PDM passes it as parameter.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @param pCfg Configuration node handle for the device. Use this to obtain the configuration
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * of the device instance. It's also found in pUsbDev->pCfg, but since it's
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * primary usage will in this function it's passed as a parameter.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @param pCfgGlobal Handle to the global device configuration. Also found in pUsbDev->pCfgGlobal.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @remarks This callback is required.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync DECLR3CALLBACKMEMBER(int, pfnConstruct,(PPDMUSBINS pUsbIns, int iInstance, PCFGMNODE pCfg, PCFGMNODE pCfgGlobal));
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * Init complete notification.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * This can be done to do communication with other devices and other
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * initialization which requires everything to be in place.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @returns VBOX status code.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @param pUsbIns The USB device instance data.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @remarks Optional.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync DECLR3CALLBACKMEMBER(int, pfnInitComplete,(PPDMUSBINS pUsbIns));
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * Destruct an USB device instance.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * Most VM resources are freed by the VM. This callback is provided so that any non-VM
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * resources can be freed correctly.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * This method will be called regardless of the pfnConstruc result to avoid
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * complicated failure paths.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @returns VBox status.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @param pUsbIns The USB device instance data.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @remarks Optional.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync DECLR3CALLBACKMEMBER(int, pfnDestruct,(PPDMUSBINS pUsbIns));
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * Power On notification.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @returns VBox status.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @param pUsbIns The USB device instance data.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * @remarks Optional.
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync DECLR3CALLBACKMEMBER(void, pfnPowerOn,(PPDMUSBINS pUsbIns));
07db1daf0ffed7a0fe1224c296fc1e7ac40d7681vboxsync * Reset notification.
DECLR3CALLBACKMEMBER(int, pfnQueryInterface,(PPDMUSBINS pUsbIns, unsigned iLUN, PPDMIBASE *ppBase));
} PDMUSBREG;
#ifdef IN_RING3
typedef struct PDMUSBHLP
DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMUSBINS pUsbIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc));
DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction));
DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction));
DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction, const char *pszFormat, va_list va));
/** @todo DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMUSBINS pUsbIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERUSB pfnHandler)); */
/** @todo DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMUSBINS pUsbIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEUSB pfnCallback, PPDMQUEUE *ppQueue)); */
/** @todo DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMUSBINS pUsbIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMUSBINS pUsbIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
/** @todo DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMUSBINS pUsbIns, TMCLOCK enmClock, PFNTMTIMERUSB pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer)); */
DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMUSBINS pUsbIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMUSBINS pUsbIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
} PDMUSBHLP;
typedef struct PDMUSBINS
#ifdef PDMUSBINSINT_DECLARED
PDMUSBINSINT s;
} Internal;
} PDMUSBINS;
#define PDMIBASE_2_PDMUSB(pInterface) ( (PPDMUSBINS)((char *)(pInterface) - RT_OFFSETOF(PDMUSBINS, IBase)) )
#ifdef VBOX_STRICT
# define PDMUSB_ASSERT_EMT(pUsbIns) pUsbIns->pUsbHlp->pfnAssertEMT(pUsbIns, __FILE__, __LINE__, __FUNCTION__)
#ifdef VBOX_STRICT
# define PDMUSB_ASSERT_OTHER(pUsbIns) pUsbIns->pUsbHlp->pfnAssertOther(pUsbIns, __FILE__, __LINE__, __FUNCTION__)
#ifdef IN_RING3
#ifdef VBOX_STRICT
int rc;
return rc;
return VINF_SUCCESS;
typedef struct PDMUSBREGCB
} PDMUSBREGCB;