1b33c96954667ba382fa595baf7b31290bfdd517vboxsync/** @file
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * PDM - Pluggable Device Manager, VM Services.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync *
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * @todo This has not been implemented, consider dropping the concept.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync */
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync/*
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * Copyright (C) 2006-2010 Oracle Corporation
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync *
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * available from http://www.virtualbox.org. This file is free software;
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * you can redistribute it and/or modify it under the terms of the GNU
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * General Public License (GPL) as published by the Free Software
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync *
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * The contents of this file may alternatively be used under the terms
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * of the Common Development and Distribution License Version 1.0
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * VirtualBox OSE distribution, in which case the provisions of the
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * CDDL are applicable instead of those of the GPL.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync *
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * You may elect to license modified versions of this file under the
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * terms and conditions of either the GPL or the CDDL or both.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync */
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync#ifndef ___VBox_vmm_pdmsrv_h
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync#define ___VBox_vmm_pdmsrv_h
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync#include <VBox/vmm/pdmifs.h>
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync#include <VBox/vmm/ssm.h>
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync#include <VBox/vmm/cfgm.h>
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync
1b33c96954667ba382fa595baf7b31290bfdd517vboxsyncRT_C_DECLS_BEGIN
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync/** @defgroup grp_pdm_services The PDM Services API
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * @ingroup grp_pdm
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * @{
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync */
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync/**
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * Construct a service instance for a VM.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync *
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * @returns VBox status.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * @param pSrvIns The service instance data.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * If the registration structure is needed, pSrvIns->pReg points to it.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * @param pCfg Configuration node handle for the service. Use this to obtain the configuration
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * of the driver instance. It's also found in pSrvIns->pCfg, but since it's primary
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * usage is expected in this function it is passed as a parameter.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync */
1b33c96954667ba382fa595baf7b31290bfdd517vboxsynctypedef DECLCALLBACK(int) FNPDMSRVCONSTRUCT(PPDMSRVINS pSrvIns, PCFGMNODE pCfg);
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync/** Pointer to a FNPDMSRVCONSTRUCT() function. */
1b33c96954667ba382fa595baf7b31290bfdd517vboxsynctypedef FNPDMSRVCONSTRUCT *PFNPDMSRVCONSTRUCT;
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync/**
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * Destruct a driver instance.
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync *
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * Most VM resources are freed by the VM. This callback is provided so that any non-VM
1b33c96954667ba382fa595baf7b31290bfdd517vboxsync * resources can be freed correctly.
*
* @param pSrvIns The service instance data.
*/
typedef DECLCALLBACK(void) FNPDMSRVDESTRUCT(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVDESTRUCT() function. */
typedef FNPDMSRVDESTRUCT *PFNPDMSRVDESTRUCT;
/**
* Power On notification.
*
* @param pSrvIns The service instance data.
*/
typedef DECLCALLBACK(void) FNPDMSRVPOWERON(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVPOWERON() function. */
typedef FNPDMSRVPOWERON *PFNPDMSRVPOWERON;
/**
* Reset notification.
*
* @returns VBox status.
* @param pSrvIns The service instance data.
*/
typedef DECLCALLBACK(void) FNPDMSRVRESET(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVRESET() function. */
typedef FNPDMSRVRESET *PFNPDMSRVRESET;
/**
* Suspend notification.
*
* @returns VBox status.
* @param pSrvIns The service instance data.
*/
typedef DECLCALLBACK(void) FNPDMSRVSUSPEND(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVSUSPEND() function. */
typedef FNPDMSRVSUSPEND *PFNPDMSRVSUSPEND;
/**
* Resume notification.
*
* @returns VBox status.
* @param pSrvIns The service instance data.
*/
typedef DECLCALLBACK(void) FNPDMSRVRESUME(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVRESUME() function. */
typedef FNPDMSRVRESUME *PFNPDMSRVRESUME;
/**
* Power Off notification.
*
* @param pSrvIns The service instance data.
*/
typedef DECLCALLBACK(void) FNPDMSRVPOWEROFF(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVPOWEROFF() function. */
typedef FNPDMSRVPOWEROFF *PFNPDMSRVPOWEROFF;
/**
* Detach notification.
*
* This is called when a driver or device is detached from the service
*
* @param pSrvIns The service instance data.
*/
typedef DECLCALLBACK(void) FNPDMSRVDETACH(PPDMSRVINS pSrvIns, PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns);
/** Pointer to a FNPDMSRVDETACH() function. */
typedef FNPDMSRVDETACH *PFNPDMSRVDETACH;
/** PDM Service Registration Structure,
* This structure is used when registering a driver from
* VBoxServicesRegister() (HC Ring-3). PDM will continue use till
* the VM is terminated.
*/
typedef struct PDMSRVREG
{
/** Structure version. PDM_SRVREG_VERSION defines the current version. */
uint32_t u32Version;
/** Driver name. */
char szServiceName[32];
/** The description of the driver. The UTF-8 string pointed to shall, like this structure,
* remain unchanged from registration till VM destruction. */
const char *pszDescription;
/** Flags, combination of the PDM_SRVREG_FLAGS_* \#defines. */
RTUINT fFlags;
/** Size of the instance data. */
RTUINT cbInstance;
/** Construct instance - required. */
PFNPDMSRVCONSTRUCT pfnConstruct;
/** Destruct instance - optional. */
PFNPDMSRVDESTRUCT pfnDestruct;
/** Power on notification - optional. */
PFNPDMSRVPOWERON pfnPowerOn;
/** Reset notification - optional. */
PFNPDMSRVRESET pfnReset;
/** Suspend notification - optional. */
PFNPDMSRVSUSPEND pfnSuspend;
/** Resume notification - optional. */
PFNPDMSRVRESUME pfnResume;
/** Detach notification - optional. */
PFNPDMSRVDETACH pfnDetach;
/** Power off notification - optional. */
PFNPDMSRVPOWEROFF pfnPowerOff;
} PDMSRVREG;
/** Pointer to a PDM Driver Structure. */
typedef PDMSRVREG *PPDMSRVREG;
/** Const pointer to a PDM Driver Structure. */
typedef PDMSRVREG const *PCPDMSRVREG;
/**
* PDM Service API.
*/
typedef struct PDMSRVHLP
{
/** Structure version. PDM_SRVHLP_VERSION defines the current version. */
uint32_t u32Version;
/**
* Assert that the current thread is the emulation thread.
*
* @returns True if correct.
* @returns False if wrong.
* @param pSrvIns Service instance.
* @param pszFile Filename of the assertion location.
* @param iLine Linenumber of the assertion location.
* @param pszFunction Function of the assertion location.
*/
DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMSRVINS pSrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
/**
* Assert that the current thread is NOT the emulation thread.
*
* @returns True if correct.
* @returns False if wrong.
* @param pSrvIns Service instance.
* @param pszFile Filename of the assertion location.
* @param iLine Linenumber of the assertion location.
* @param pszFunction Function of the assertion location.
*/
DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMSRVINS pSrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
/**
* Creates a timer.
*
* @returns VBox status.
* @param pVM The VM to create the timer in.
* @param pSrvIns Service instance.
* @param enmClock The clock to use on this timer.
* @param pfnCallback Callback function.
* @param pszDesc Pointer to description string which must stay around
* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
* @param ppTimer Where to store the timer on success.
*/
DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMSRVINS pSrvIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERR3 ppTimer));
/**
* Query the virtual timer frequency.
*
* @returns Frequency in Hz.
* @param pSrvIns Service instance.
* @thread Any thread.
*/
DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMSRVINS pSrvIns));
/**
* Query the virtual time.
*
* @returns The current virtual time.
* @param pSrvIns Service instance.
* @thread Any thread.
*/
DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMSRVINS pSrvIns));
} PDMSRVHLP;
/** Pointer PDM Service API. */
typedef PDMSRVHLP *PPDMSRVHLP;
/** Pointer const PDM Service API. */
typedef const PDMSRVHLP *PCPDMSRVHLP;
/** Current SRVHLP version number. */
#define PDM_SRVHLP_VERSION PDM_VERSION_MAKE(0xdfff, 1, 0)
/**
* PDM Service Instance.
*/
typedef struct PDMSRVINS
{
/** Structure version. PDM_SRVINS_VERSION defines the current version. */
uint32_t u32Version;
/** Internal data. */
union
{
#ifdef PDMSRVINSINT_DECLARED
PDMSRVINSINT s;
#endif
uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 32];
} Internal;
/** Pointer the PDM Service API. */
R3PTRTYPE(PCPDMSRVHLP) pHlp;
/** Pointer to driver registration structure. */
R3PTRTYPE(PCPDMSRVREG) pReg;
/** Configuration handle. */
R3PTRTYPE(PCFGMNODE) pCfg;
/** The base interface of the service.
* The service constructor initializes this. */
PDMIBASE IBase;
/* padding to make achInstanceData aligned at 16 byte boundary. */
uint32_t au32Padding[2];
/** Pointer to driver instance data. */
R3PTRTYPE(void *) pvInstanceData;
/** Driver instance data. The size of this area is defined
* in the PDMSRVREG::cbInstanceData field. */
char achInstanceData[4];
} PDMSRVINS;
/** Current PDMSRVREG version number. */
#define PDM_SRVINS_VERSION PDM_VERSION_MAKE(0xdffe, 1, 0)
/** Converts a pointer to the PDMSRVINS::IBase to a pointer to PDMSRVINS. */
#define PDMIBASE_2_PDMSRV(pInterface) ( (PPDMSRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMSRVINS, IBase)) )
/** Pointer to callbacks provided to the VBoxServiceRegister() call. */
typedef struct PDMSRVREGCB *PPDMSRVREGCB;
/**
* Callbacks for VBoxServiceRegister().
*/
typedef struct PDMSRVREGCB
{
/** Interface version.
* This is set to PDM_SRVREG_CB_VERSION. */
uint32_t u32Version;
/**
* Registers a service with the current VM instance.
*
* @returns VBox status code.
* @param pCallbacks Pointer to the callback table.
* @param pSrvReg Pointer to the device registration record.
* This data must be permanent and readonly.
*/
DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMSRVREGCB pCallbacks, PCPDMSRVREG pSrvReg));
} PDMSRVREGCB;
/** Current version of the PDMSRVREGCB structure. */
#define PDM_SRVREG_CB_VERSION PDM_VERSION_MAKE(0xdffd, 1, 0)
/**
* The VBoxServicesRegister callback function.
*
* PDM will invoke this function after loading a device module and letting
* the module decide which devices to register and how to handle conflicts.
*
* @returns VBox status code.
* @param pCallbacks Pointer to the callback table.
* @param u32Version VBox version number.
*/
typedef DECLCALLBACK(int) FNPDMVBOXSERVICESREGISTER(PPDMSRVREGCB pCallbacks, uint32_t u32Version);
/** @} */
RT_C_DECLS_END
#endif