Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 350 insertions, 0 deletions

diff --git a/include/VBox/vmm/pdmsrv.h b/include/VBox/vmm/pdmsrv.h
new file mode 100644
index 00000000..e0b3f7ce
--- /dev/null
+++ b/include/VBox/vmm/pdmsrv.h
@@ -0,0 +1,350 @@
+/** @file
+ * PDM - Pluggable Device Manager, VM Services.
+ *
+ * @todo    This has not been implemented, consider dropping the concept.
+ */
+
+/*
+ * Copyright (C) 2006-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program 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 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef VBOX_INCLUDED_vmm_pdmsrv_h
+#define VBOX_INCLUDED_vmm_pdmsrv_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <VBox/vmm/pdmifs.h>
+#include <VBox/vmm/ssm.h>
+#include <VBox/vmm/cfgm.h>
+
+RT_C_DECLS_BEGIN
+
+/** @defgroup grp_pdm_services  The PDM Services API
+ * @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 DECLCALLBACKTYPE(int, FNPDMSRVCONSTRUCT,(PPDMSRVINS pSrvIns, PCFGMNODE pCfg));
+/** Pointer to a FNPDMSRVCONSTRUCT() function. */
+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 DECLCALLBACKTYPE(void, FNPDMSRVDESTRUCT,(PPDMSRVINS pSrvIns));
+/** Pointer to a FNPDMSRVDESTRUCT() function. */
+typedef FNPDMSRVDESTRUCT *PFNPDMSRVDESTRUCT;
+
+/**
+ * Power On notification.
+ *
+ * @param   pSrvIns     The service instance data.
+ */
+typedef DECLCALLBACKTYPE(void, FNPDMSRVPOWERON,(PPDMSRVINS pSrvIns));
+/** Pointer to a FNPDMSRVPOWERON() function. */
+typedef FNPDMSRVPOWERON *PFNPDMSRVPOWERON;
+
+/**
+ * Reset notification.
+ *
+ * @returns VBox status.
+ * @param   pSrvIns     The service instance data.
+ */
+typedef DECLCALLBACKTYPE(void, FNPDMSRVRESET,(PPDMSRVINS pSrvIns));
+/** Pointer to a FNPDMSRVRESET() function. */
+typedef FNPDMSRVRESET *PFNPDMSRVRESET;
+
+/**
+ * Suspend notification.
+ *
+ * @returns VBox status.
+ * @param   pSrvIns     The service instance data.
+ */
+typedef DECLCALLBACKTYPE(void, FNPDMSRVSUSPEND,(PPDMSRVINS pSrvIns));
+/** Pointer to a FNPDMSRVSUSPEND() function. */
+typedef FNPDMSRVSUSPEND *PFNPDMSRVSUSPEND;
+
+/**
+ * Resume notification.
+ *
+ * @returns VBox status.
+ * @param   pSrvIns     The service instance data.
+ */
+typedef DECLCALLBACKTYPE(void, FNPDMSRVRESUME,(PPDMSRVINS pSrvIns));
+/** Pointer to a FNPDMSRVRESUME() function. */
+typedef FNPDMSRVRESUME *PFNPDMSRVRESUME;
+
+/**
+ * Power Off notification.
+ *
+ * @param   pSrvIns     The service instance data.
+ */
+typedef DECLCALLBACKTYPE(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.
+ * @param   pDevIns     The device instance to detach.
+ * @param   pDrvIns     The driver instance to detach.
+ */
+typedef DECLCALLBACKTYPE(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 cross context VM structure.
+     * @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_UOFFSETOF(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 DECLCALLBACKTYPE(int, FNPDMVBOXSERVICESREGISTER,(PPDMSRVREGCB pCallbacks, uint32_t u32Version));
+
+
+/** @} */
+
+RT_C_DECLS_END
+
+#endif /* !VBOX_INCLUDED_vmm_pdmsrv_h */