Logo Search packages:      
Sourcecode: virtualbox-ose version File versions  Download package

pdmsrv.h

Go to the documentation of this file.
/** @file
 * PDM - Pluggable Device Manager, VM Services.
 */

/*
 * Copyright (C) 2006-2007 innotek GmbH
 *
 * This file is part of VirtualBox Open Source Edition (OSE), as
 * available from http://www.virtualbox.org. This file is free software;
 * you can redistribute it and/or modify it under the terms of the GNU
 * General Public License as published by the Free Software Foundation,
 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
 * distribution. VirtualBox OSE is distributed in the hope that it will
 * be useful, but WITHOUT ANY WARRANTY of any kind.
 */

#ifndef ___VBox_pdmsrv_h
#define ___VBox_pdmsrv_h

#include <VBox/pdmifs.h>
#include <VBox/ssm.h>
#include <VBox/cfgm.h>

__BEGIN_DECLS

/** @defgroup grp_pdm_services  Services
 * @ingroup grp_pdm
 * @{
 */

/**
 * Construct a service instance for a VM.
 *
 * @returns VBox status.
 * @param   pSrvIns     The service instance data.
 *                      If the registration structure is needed, pSrvIns->pReg points to it.
 * @param   pCfg        Configuration node handle for the service. Use this to obtain the configuration
 *                      of the driver instance. It's also found in pSrvIns->pCfg, but since it's primary
 *                      usage is expected in this function it is passed as a parameter.
 */
typedef DECLCALLBACK(int)   FNPDMSRVCONSTRUCT(PPDMSRVINS pSrvIns, PCFGMNODE pCfg);
/** Pointer to a FNPDMSRVCONSTRUCT() function. */
00043 typedef FNPDMSRVCONSTRUCT *PFNPDMSRVCONSTRUCT;

/**
 * Destruct a driver instance.
 *
 * Most VM resources are freed by the VM. This callback is provided so that any non-VM
 * resources can be freed correctly.
 *
 * @param   pSrvIns     The service instance data.
 */
typedef DECLCALLBACK(void)   FNPDMSRVDESTRUCT(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVDESTRUCT() function. */
00055 typedef FNPDMSRVDESTRUCT *PFNPDMSRVDESTRUCT;

/**
 * Power On notification.
 *
 * @param   pSrvIns     The service instance data.
 */
typedef DECLCALLBACK(void)   FNPDMSRVPOWERON(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVPOWERON() function. */
00064 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. */
00074 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. */
00084 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. */
00094 typedef FNPDMSRVRESUME *PFNPDMSRVRESUME;

/**
 * Power Off notification.
 *
 * @param   pSrvIns     The service instance data.
 */
typedef DECLCALLBACK(void)   FNPDMSRVPOWEROFF(PPDMSRVINS pSrvIns);
/** Pointer to a FNPDMSRVPOWEROFF() function. */
00103 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. */
00114 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.
 */
00123 typedef struct PDMSRVREG
{
    /** Structure version. PDM_SRVREG_VERSION defines the current version. */
00126     uint32_t            u32Version;
    /** Driver name. */
00128     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. */
00131     const char         *pszDescription;

    /** Flags, combination of the PDM_SRVREG_FLAGS_* \#defines. */
00134     RTUINT              fFlags;
    /** Size of the instance data. */
00136     RTUINT              cbInstance;

    /** Construct instance - required. */
00139     PFNPDMSRVCONSTRUCT  pfnConstruct;
    /** Destruct instance - optional. */
00141     PFNPDMSRVDESTRUCT   pfnDestruct;
    /** Power on notification - optional. */
00143     PFNPDMSRVPOWERON    pfnPowerOn;
    /** Reset notification - optional. */
00145     PFNPDMSRVRESET      pfnReset;
    /** Suspend notification  - optional. */
00147     PFNPDMSRVSUSPEND    pfnSuspend;
    /** Resume notification - optional. */
00149     PFNPDMSRVRESUME     pfnResume;
    /** Detach notification - optional. */
00151     PFNPDMSRVDETACH     pfnDetach;
    /** Power off notification - optional. */
00153     PFNPDMSRVPOWEROFF   pfnPowerOff;

} PDMSRVREG;
/** Pointer to a PDM Driver Structure. */
00157 typedef PDMSRVREG *PPDMSRVREG;
/** Const pointer to a PDM Driver Structure. */
00159 typedef PDMSRVREG const *PCPDMSRVREG;



/**
 * PDM Service API.
 */
00166 typedef struct PDMSRVHLP
{
    /** Structure version. PDM_SRVHLP_VERSION defines the current version. */
00169     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, PPTMTIMERHC 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. */
00229 typedef PDMSRVHLP *PPDMSRVHLP;
/** Pointer const PDM Service API. */
00231 typedef const PDMSRVHLP *PCPDMSRVHLP;

/** Current SRVHLP version number. */
00234 #define PDM_SRVHLP_VERSION  0xf9010000


/**
 * PDM Service Instance.
 */
00240 typedef struct PDMSRVINS
{
    /** Structure version. PDM_SRVINS_VERSION defines the current version. */
00243     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. */
    HCPTRTYPE(PCPDMSRVHLP)      pHlp;
    /** Pointer to driver registration structure.  */
    HCPTRTYPE(PCPDMSRVREG)      pReg;
    /** Configuration handle. */
    HCPTRTYPE(PCFGMNODE)        pCfg;
    /** The base interface of the service.
     * The service constructor initializes this. */
00262     PDMIBASE                    IBase;
    /* padding to make achInstanceData aligned at 16 byte boundrary. */
    uint32_t                    au32Padding[2];
    /** Pointer to driver instance data. */
    HCPTRTYPE(void *)           pvInstanceData;
    /** Driver instance data. The size of this area is defined
     * in the PDMSRVREG::cbInstanceData field. */
00269     char                        achInstanceData[4];
} PDMSRVINS;

/** Current PDMSRVREG version number. */
00273 #define PDM_SRVINS_VERSION  0xf7010000

/** Converts a pointer to the PDMSRVINS::IBase to a pointer to PDMSRVINS. */
00276 #define PDMIBASE_2_PDMSRV(pInterface) ( (PPDMSRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMSRVINS, IBase)) )



/** Pointer to callbacks provided to the VBoxServiceRegister() call. */
00281 typedef struct PDMSRVREGCB *PPDMSRVREGCB;

/**
 * Callbacks for VBoxServiceRegister().
 */
00286 typedef struct PDMSRVREGCB
{
    /** Interface version.
     * This is set to PDM_SRVREG_CB_VERSION. */
00290     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. */
00304 #define PDM_SRVREG_CB_VERSION 0xf8010000


/**
 * 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);


/** @} */

__END_DECLS

#endif

Generated by  Doxygen 1.6.0   Back to index