pdmdrv.h revision 29ffc69bf52217e6fa2386588fcf649bbac42589
7d32c065c7bb56f281651ae3dd2888f32ce4f1d9Bob Halley * PDM - Pluggable Device Manager, Drivers.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * Copyright (C) 2006-2007 innotek GmbH
15a44745412679c30a6d022733925af70a38b715David Lawrence * This file is part of VirtualBox Open Source Edition (OSE), as
15a44745412679c30a6d022733925af70a38b715David Lawrence * available from http://www.virtualbox.org. This file is free software;
15a44745412679c30a6d022733925af70a38b715David Lawrence * you can redistribute it and/or modify it under the terms of the GNU
15a44745412679c30a6d022733925af70a38b715David Lawrence * General Public License as published by the Free Software Foundation,
15a44745412679c30a6d022733925af70a38b715David Lawrence * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
15a44745412679c30a6d022733925af70a38b715David Lawrence * distribution. VirtualBox OSE is distributed in the hope that it will
15a44745412679c30a6d022733925af70a38b715David Lawrence * be useful, but WITHOUT ANY WARRANTY of any kind.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews/** @defgroup grp_pdm_driver Drivers
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * @ingroup grp_pdm
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * Construct a driver instance for a VM.
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * @returns VBox status.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * @param pDrvIns The driver instance data.
3ddd92da6651bc72aa79a04195ad389d86fd1a66Andreas Gustafsson * If the registration structure is needed, pDrvIns->pDrvReg points to it.
54c26ab21c61c6d6b1e484bb88dc3ac263845d17Mark Andrews * @param pCfgHandle Configuration node handle for the driver. Use this to obtain the configuration
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence * of the driver instance. It's also found in pDrvIns->pCfgHandle as it's expected
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * to be used frequently in this function.
34b394b43e2207e8f8f3703f0402422121455638David Lawrencetypedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle);
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews/** Pointer to a FNPDMDRVCONSTRUCT() function. */
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * Destruct a driver instance.
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * Most VM resources are freed by the VM. This callback is provided so that
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * any non-VM resources can be freed correctly.
3ddd92da6651bc72aa79a04195ad389d86fd1a66Andreas Gustafsson * @param pDrvIns The driver instance data.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrewstypedef DECLCALLBACK(void) FNPDMDRVDESTRUCT(PPDMDRVINS pDrvIns);
822f6cdabb1edd44472c7a758b5cae71376fa9beBrian Wellington/** Pointer to a FNPDMDRVDESTRUCT() function. */
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence * Driver I/O Control interface.
0e8cf9a887c70f96ac448b06c069d90b830215ccMark Andrews * This is used by external components, such as the COM interface, to
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * communicate with a driver using a driver specific interface. Generally,
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * the driver interfaces are used for this task.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * @returns VBox status code.
926234e867548c8c27428d0486a9a792535f8396David Lawrence * @param pDrvIns Pointer to the driver instance.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * @param uFunction Function to perform.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * @param pvIn Pointer to input data.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * @param cbIn Size of input data.
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * @param pvOut Pointer to output data.
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * @param cbOut Size of output data.
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * @param pcbOut Where to store the actual size of the output data.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrewstypedef DECLCALLBACK(int) FNPDMDRVIOCTL(PPDMDRVINS pDrvIns, RTUINT uFunction,
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews/** Pointer to a FNPDMDRVIOCTL() function. */
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * Power On notification.
0e8cf9a887c70f96ac448b06c069d90b830215ccMark Andrews * @param pDrvIns The driver instance data.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrewstypedef DECLCALLBACK(void) FNPDMDRVPOWERON(PPDMDRVINS pDrvIns);
34b394b43e2207e8f8f3703f0402422121455638David Lawrence/** Pointer to a FNPDMDRVPOWERON() function. */
54c26ab21c61c6d6b1e484bb88dc3ac263845d17Mark Andrews * Reset notification.
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * @returns VBox status.
34b394b43e2207e8f8f3703f0402422121455638David Lawrence * @param pDrvIns The driver instance data.
fad44a20eede1bbc66716241dede225500c91caaAndreas Gustafssontypedef DECLCALLBACK(void) FNPDMDRVRESET(PPDMDRVINS pDrvIns);
fad44a20eede1bbc66716241dede225500c91caaAndreas Gustafsson/** Pointer to a FNPDMDRVRESET() function. */
fad44a20eede1bbc66716241dede225500c91caaAndreas Gustafsson * Suspend notification.
419590499823ce15b5d2ad4fe71eaf04bd5a86c0Michael Graff * @returns VBox status.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * @param pDrvIns The driver instance data.
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Grafftypedef DECLCALLBACK(void) FNPDMDRVSUSPEND(PPDMDRVINS pDrvIns);
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence/** Pointer to a FNPDMDRVSUSPEND() function. */
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence * Resume notification.
926234e867548c8c27428d0486a9a792535f8396David Lawrence * @returns VBox status.
926234e867548c8c27428d0486a9a792535f8396David Lawrence * @param pDrvIns The driver instance data.
6e49e91bd08778d7eae45a2229dcf41ed97cc636David Lawrencetypedef DECLCALLBACK(void) FNPDMDRVRESUME(PPDMDRVINS pDrvIns);
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews/** Pointer to a FNPDMDRVRESUME() function. */
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * Power Off notification.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * @param pDrvIns The driver instance data.
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrencetypedef DECLCALLBACK(void) FNPDMDRVPOWEROFF(PPDMDRVINS pDrvIns);
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews/** Pointer to a FNPDMDRVPOWEROFF() function. */
926234e867548c8c27428d0486a9a792535f8396David Lawrence * Detach notification.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * This is called when a driver below it in the chain is detaching itself
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * from it. The driver should adjust it's state to reflect this.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * This is like ejecting a cdrom or floppy.
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence * @param pDrvIns The driver instance.
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrewstypedef DECLCALLBACK(void) FNPDMDRVDETACH(PPDMDRVINS pDrvIns);
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews/** Pointer to a FNPDMDRVDETACH() function. */
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews/** PDM Driver Registration Structure,
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * This structure is used when registering a driver from
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * VBoxInitDrivers() (HC Ring-3). PDM will continue use till
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews * the VM is terminated.
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews /** Structure version. PDM_DRVREG_VERSION defines the current version. */
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews /** Driver name. */
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews /** The description of the driver. The UTF-8 string pointed to shall, like this structure,
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews * remain unchanged from registration till VM destruction. */
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews /** Flags, combination of the PDM_DRVREG_FLAGS_* \#defines. */
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews /** Driver class(es), combination of the PDM_DRVREG_CLASS_* \#defines. */
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews /** Maximum number of instances (per VM). */
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Graff /** Size of the instance data. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews /** Construct instance - required. */
12a12d8ab469ba71e8593a71c28d91d4b25d5863Mark Andrews /** Destruct instance - optional. */
82ca33427bdd4f3bc4ed3431e86bd810fe751674Andreas Gustafsson /** I/O control - optional. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews /** Power on notification - optional. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews /** Reset notification - optional. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews /** Suspend notification - optional. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews /** Resume notification - optional. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews /** Detach notification - optional. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews /** Power off notification - optional. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews/** Pointer to a PDM Driver Structure. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews/** Const pointer to a PDM Driver Structure. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews/** Current DRVREG version number. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews/** PDM Device Flags.
94a3bcd132e515b4baa0884ba9dd0f361d2e17bcMark Andrews/** @def PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT
4529cdaedaf1a0a5f8ff89aeca510b7a4475446cBob Halley * The bit count for the current host. */
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x000000001
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x000000002
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews/** The host bit count mask. */
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews#define PDM_DRVREG_FLAGS_HOST_BITS_MASK 0x000000003
d981ca645597116d227a48bf37cc5edc061c854dBob Halley/** PDM Driver Classes.
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence/** Mouse input driver. */
d981ca645597116d227a48bf37cc5edc061c854dBob Halley/** Keyboard input driver. */
926234e867548c8c27428d0486a9a792535f8396David Lawrence/** Display driver. */
d981ca645597116d227a48bf37cc5edc061c854dBob Halley/** Network transport driver. */
d981ca645597116d227a48bf37cc5edc061c854dBob Halley/** Block driver. */
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Graff/** Media driver. */
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley/** Mountable driver. */
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley/** Audio driver. */
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley/** VMMDev driver. */
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley/** Status driver. */
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley/** ACPI driver. */
#ifdef IN_RING3
typedef struct PDMDRVHLP
* @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
DECLR3CALLBACKMEMBER(int, pfnMountPrepare,(PPDMDRVINS pDrvIns, const char *pszFilename, const char *pszCoreDriver));
DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));
DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue));
DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, const char *pszDesc, PPTMTIMERR3 ppTimer));
DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance));
DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName,
* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
DECLR3CALLBACKMEMBER(int, pfnSUPCallVMMR0Ex,(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg));
DECLR3CALLBACKMEMBER(int, pfnUSBRegisterHub,(PPDMDRVINS pDrvIns, void *pvReservedIn, void **ppvReservedHlp));
DECLR3CALLBACKMEMBER(int, pfnPDMThreadCreate,(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
} PDMDRVHLP;
typedef struct PDMDRVINS
#ifdef PDMDRVINSINT_DECLARED
PDMDRVINSINT s;
} Internal;
} PDMDRVINS;
#define PDMIBASE_2_PDMDRV(pInterface) ( (PPDMDRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDRVINS, IBase)) )
DECLINLINE(int) PDMDrvHlpVMSetError(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
return rc;
DECLINLINE(int) PDMDrvHlpVMSetRuntimeError(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...)
int rc;
return rc;
#ifdef VBOX_STRICT
# define PDMDRV_ASSERT_EMT(pDrvIns) pDrvIns->pDrvHlp->pfnAssertEMT(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
#ifdef VBOX_STRICT
# define PDMDRV_ASSERT_OTHER(pDrvIns) pDrvIns->pDrvHlp->pfnAssertOther(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
#ifdef IN_RING3
DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
DECLINLINE(void) PDMDrvHlpSTAMRegisterF(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
pDrvIns->pDrvHlp->pfnSTAMRegisterV(pDrvIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
DECLINLINE(int) PDMDrvHlpUSBRegisterHub(PPDMDRVINS pDrvIns, void *pvReservedIn, void **ppvReservedHlp)
DECLINLINE(int) PDMDrvHlpPDMThreadCreate(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
return pDrvIns->pDrvHlp->pfnPDMThreadCreate(pDrvIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
typedef struct PDMDRVREGCB
} PDMDRVREGCB;