sup.h revision 1c2c968fd241148110002d75b2c0fdeddc211e14
/** @file
* SUP - Support Library.
*/
/*
* Copyright (C) 2006-2007 Sun Microsystems, Inc.
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) 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.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE 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.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#ifndef ___VBox_sup_h
#define ___VBox_sup_h
/** @defgroup grp_sup The Support Library API
* @{
*/
/**
* Physical page descriptor.
*/
typedef struct SUPPAGE
{
/** Physical memory address. */
/** Reserved entry for internal use by the caller. */
} SUPPAGE;
#pragma pack()
/** Pointer to a page descriptor. */
/** Pointer to a const page descriptor. */
/**
* The paging mode.
*/
typedef enum SUPPAGINGMODE
{
/** The usual invalid entry.
* This is returned by SUPGetPagingMode() */
/** Normal 32-bit paging, no global pages */
/** Normal 32-bit paging with global pages. */
/** PAE mode, no global pages, no NX. */
/** PAE mode with global pages. */
/** PAE mode with NX, no global pages. */
/** PAE mode with global pages and NX. */
/** AMD64 mode, no global pages. */
/** AMD64 mode with global pages, no NX. */
/** AMD64 mode with NX, no global pages. */
/** AMD64 mode with global pages and NX. */
/**
* Per CPU data.
* This is only used when
*/
typedef struct SUPGIPCPU
{
/** Update transaction number.
* This number is incremented at the start and end of each update. It follows
* thusly that odd numbers indicates update in progress, while even numbers
* indicate stable data. Use this to make sure that the data items you fetch
* are consistent. */
volatile uint32_t u32TransactionId;
/** The interval in TSC ticks between two NanoTS updates.
* This is the average interval over the last 2, 4 or 8 updates + a little slack.
* The slack makes the time go a tiny tiny bit slower and extends the interval enough
* to avoid ending up with too many 1ns increments. */
volatile uint32_t u32UpdateIntervalTSC;
/** Current nanosecond timestamp. */
/** The TSC at the time of u64NanoTS. */
/** Current CPU Frequency. */
/** Number of errors during updating.
/** Index of the head item in au32TSCHistory. */
volatile uint32_t iTSCHistoryHead;
/** Array of recent TSC interval deltas.
* The most recent item is at index iTSCHistoryHead.
* This history is used to calculate u32UpdateIntervalTSC.
*/
/** Reserved for future per processor data. */
} SUPGIPCPU;
/*AssertCompileMemberAlignment(SUPGIPCPU, u64TSC, 8); -fixme */
/** Pointer to per cpu data.
* @remark there is no const version of this typedef, see g_pSUPGlobalInfoPage for details. */
typedef SUPGIPCPU *PSUPGIPCPU;
/**
* Global Information Page.
*
* This page contains useful information and can be mapped into any
* process or VM. It can be accessed thru the g_pSUPGlobalInfoPage
* pointer when a session is open.
*/
typedef struct SUPGLOBALINFOPAGE
{
/** Magic (SUPGLOBALINFOPAGE_MAGIC). */
/** The GIP version. */
/** The GIP update mode, see SUPGIPMODE. */
/** Reserved / padding. */
/** The update frequency of the of the NanoTS. */
volatile uint32_t u32UpdateHz;
/** The update interval in nanoseconds. (10^9 / u32UpdateHz) */
volatile uint32_t u32UpdateIntervalNS;
/** The timestamp of the last time we update the update frequency. */
volatile uint64_t u64NanoTSLastUpdateHz;
/** Padding / reserved space for future data. */
/** Array of per-cpu data.
* If u32Mode == SUPGIPMODE_SYNC_TSC then only the first entry is used.
* If u32Mode == SUPGIPMODE_ASYNC_TSC then the CPU ACPI ID is used as an
* index into the array. */
/* AssertCompileMemberAlignment(SUPGLOBALINFOPAGE, aCPU, 32); - fixme */
/** Pointer to the global info page.
* @remark there is no const version of this typedef, see g_pSUPGlobalInfoPage for details. */
typedef SUPGLOBALINFOPAGE *PSUPGLOBALINFOPAGE;
#pragma pack() /* end of paranoia */
/** The value of the SUPGLOBALINFOPAGE::u32Magic field. (Soryo Fuyumi) */
#define SUPGLOBALINFOPAGE_MAGIC 0x19590106
/** The GIP version.
* Upper 16 bits is the major version. Major version is only changed with
* incompatible changes in the GIP. */
#define SUPGLOBALINFOPAGE_VERSION 0x00020000
/**
* SUPGLOBALINFOPAGE::u32Mode values.
*/
typedef enum SUPGIPMODE
{
/** The usual invalid null entry. */
SUPGIPMODE_INVALID = 0,
/** The TSC of the cores and cpus in the system is in sync. */
/** Each core has it's own TSC. */
/** The usual 32-bit hack. */
SUPGIPMODE_32BIT_HACK = 0x7fffffff
} SUPGIPMODE;
/** Pointer to the Global Information Page.
*
* This pointer is valid as long as SUPLib has a open session. Anyone using
* the page must treat this pointer as higly volatile and not trust it beyond
* one transaction.
*
* @remark The GIP page is read-only to everyone but the support driver and
* is actually mapped read only everywhere but in ring-0. However
* it is not marked 'const' as this might confuse compilers into
* thinking that values doesn't change even if members are marked
* as volatile. Thus, there is no PCSUPGLOBALINFOPAGE type.
*/
/** Workaround for ELF+GCC problem on 64-bit hosts.
* (GCC emits a mov with a R_X86_64_32 reloc, we need R_X86_64_64.) */
{
: "=a" (pGIP));
return pGIP;
}
# define g_pSUPGlobalInfoPage (SUPGetGIP())
# else
# define g_pSUPGlobalInfoPage (&g_SUPGlobalInfoPage)
# endif
#else
#endif
/**
* Gets the TSC frequency of the calling CPU.
*
* @returns TSC frequency.
* @param pGip The GIP pointer.
*/
{
unsigned iCpu;
return ~(uint64_t)0;
iCpu = 0;
else
{
iCpu = ASMGetApicId();
return ~(uint64_t)0;
}
}
/**
* Request for generic VMMR0Entry calls.
*/
typedef struct SUPVMMR0REQHDR
{
/** The magic. (SUPVMMR0REQHDR_MAGIC) */
/** The size of the request. */
/** Pointer to a ring-0 request header. */
typedef SUPVMMR0REQHDR *PSUPVMMR0REQHDR;
/** the SUPVMMR0REQHDR::u32Magic value (Ethan Iverson - The Bad Plus). */
/** For the fast ioctl path.
* @{
*/
/** @see VMMR0_DO_RAW_RUN. */
#define SUP_VMMR0_DO_RAW_RUN 0
/** @see VMMR0_DO_HWACC_RUN. */
#define SUP_VMMR0_DO_HWACC_RUN 1
/** @see VMMR0_DO_NOP */
#define SUP_VMMR0_DO_NOP 2
/** @} */
#ifdef IN_RING3
/** @defgroup grp_sup_r3 SUP Host Context Ring 3 API
* @ingroup grp_sup
* @{
*/
/**
* Installs the support library.
*
* @returns VBox status code.
*/
SUPR3DECL(int) SUPInstall(void);
/**
* Uninstalls the support library.
*
* @returns VBox status code.
*/
SUPR3DECL(int) SUPUninstall(void);
/**
* Secure main.
*
* This is used for the set-user-ID-on-execute binaries on unixy systems
* and when using the open-vboxdrv-via-root-service setup on Windows.
*
* This function will perform the integrity checks of the VirtualBox
* installation, open the support driver, open the root service (later),
* and load the DLL corresponding to \a pszProgName and execute its main
* function.
*
* @returns Return code appropriate for main().
*
* @param pszProgName The program name. This will be used to figure out which
* @param fFlags Flags.
* @param argc The argument count.
* @param argv The argument vector.
* @param envp The environment vector.
*/
DECLHIDDEN(int) SUPR3HardenedMain(const char *pszProgName, uint32_t fFlags, int argc, char **argv, char **envp);
/** @name SUPR3SecureMain flags.
* @{ */
/** Don't open the device. (Intended for VirtualBox without -startvm.) */
#define SUPSECMAIN_FLAGS_DONT_OPEN_DEV RT_BIT_32(0)
/** @} */
/**
* Initializes the support library.
* Each succesful call to SUPInit() must be countered by a
* call to SUPTerm(false).
*
* @returns VBox status code.
* @param ppSession Where to store the session handle. Defaults to NULL.
* @param cbReserve The number of bytes of contiguous memory that should be reserved by
* the runtime / support library.
* Set this to 0 if no reservation is required. (default)
* Set this to ~0 if the maximum amount supported by the VM is to be
* attempted reserved, or the maximum available.
*/
#ifdef __cplusplus
#else
#endif
/**
* Terminates the support library.
*
* @returns VBox status code.
* @param fForced Forced termination. This means to ignore the
* init call count and just terminated.
*/
#ifdef __cplusplus
#else
#endif
/**
* Sets the ring-0 VM handle for use with fast IOCtls.
*
* @returns VBox status code.
* @param pVMR0 The ring-0 VM handle.
* NIL_RTR0PTR can be used to unset the handle when the
* VM is about to be destroyed.
*/
/**
* Calls the HC R0 VMM entry point.
* See VMMR0Entry() for more details.
*
* @returns error code specific to uFunction.
* @param pVMR0 Pointer to the Ring-0 (Host Context) mapping of the VM structure.
* @param uOperation Operation to execute.
* @param pvArg Argument.
*/
/**
* Variant of SUPCallVMMR0, except that this takes the fast ioclt path
* regardsless of compile-time defaults.
*
* @returns VBox status code.
* @param pVMR0 The ring-0 VM handle.
* @param uOperation The operation; only the SUP_VMMR0_DO_* ones are valid.
*/
/**
* Calls the HC R0 VMM entry point, in a safer but slower manner than SUPCallVMMR0.
* When entering using this call the R0 components can call into the host kernel
* (i.e. use the SUPR0 and RT APIs).
*
* See VMMR0Entry() for more details.
*
* @returns error code specific to uFunction.
* @param pVMR0 Pointer to the Ring-0 (Host Context) mapping of the VM structure.
* @param uOperation Operation to execute.
* @param u64Arg Constant argument.
* @param pReqHdr Pointer to a request header. Optional.
* This will be copied in and out of kernel space. There currently is a size
* limit on this, just below 4KB.
*/
SUPR3DECL(int) SUPCallVMMR0Ex(PVMR0 pVMR0, unsigned uOperation, uint64_t u64Arg, PSUPVMMR0REQHDR pReqHdr);
/**
* Queries the paging mode of the host OS.
*
* @returns The paging mode.
*/
/**
* Allocate zero-filled pages.
*
* Use this to allocate a number of pages rather than using RTMem*() and mess with
* alignment. The returned address is of course page aligned. Call SUPPageFree()
* to free the pages once done with them.
*
* @returns VBox status.
* @param cPages Number of pages to allocate.
* @param ppvPages Where to store the base pointer to the allocated pages.
*/
/**
* Frees pages allocated with SUPPageAlloc().
*
* @returns VBox status.
* @param pvPages Pointer returned by SUPPageAlloc().
* @param cPages Number of pages that was allocated.
*/
/**
* Allocate zero-filled locked pages.
*
* Use this to allocate a number of pages rather than using RTMem*() and mess with
* alignment. The returned address is of course page aligned. Call SUPPageFreeLocked()
* to free the pages once done with them.
*
* @returns VBox status.
* @param cPages Number of pages to allocate.
* @param ppvPages Where to store the base pointer to the allocated pages.
*/
/**
* Allocate zero-filled locked pages.
*
* Use this to allocate a number of pages rather than using RTMem*() and mess with
* alignment. The returned address is of course page aligned. Call SUPPageFreeLocked()
* to free the pages once done with them.
*
* @returns VBox status code.
* @param cPages Number of pages to allocate.
* @param ppvPages Where to store the base pointer to the allocated pages.
* @param paPages Where to store the physical page addresses returned.
* On entry this will point to an array of with cbMemory >> PAGE_SHIFT entries.
* NULL is allowed.
*/
/**
* Frees locked pages allocated with SUPPageAllocLocked().
*
* @returns VBox status.
* @param pvPages Pointer returned by SUPPageAlloc().
* @param cPages Number of pages that was allocated.
*/
/**
* Locks down the physical memory backing a virtual memory
* range in the current process.
*
* @returns VBox status code.
* @param pvStart Start of virtual memory range.
* Must be page aligned.
* @param cPages Number of pages.
* @param paPages Where to store the physical page addresses returned.
* On entry this will point to an array of with cbMemory >> PAGE_SHIFT entries.
*/
/**
* Releases locked down pages.
*
* @returns VBox status code.
* @param pvStart Start of virtual memory range previously locked
* down by SUPPageLock().
*/
/**
* Allocated memory with page aligned memory with a contiguous and locked physical
* memory backing below 4GB.
*
* @returns Pointer to the allocated memory (virtual address).
* *pHCPhys is set to the physical address of the memory.
* The returned memory must be freed using SUPContFree().
* @returns NULL on failure.
* @param cPages Number of pages to allocate.
* @param pHCPhys Where to store the physical address of the memory block.
*/
/**
* Allocated memory with page aligned memory with a contiguous and locked physical
* memory backing below 4GB.
*
* @returns Pointer to the allocated memory (virtual address).
* *pHCPhys is set to the physical address of the memory.
* If ppvR0 isn't NULL, *ppvR0 is set to the ring-0 mapping.
* The returned memory must be freed using SUPContFree().
* @returns NULL on failure.
* @param cPages Number of pages to allocate.
* @param pR0Ptr Where to store the ring-0 mapping of the allocation. (optional)
* @param pHCPhys Where to store the physical address of the memory block.
*
* @remark This 2nd version of this API exists because we're not able to map the
* ring-3 mapping executable on WIN64. This is a serious problem in regard to
* the world switchers.
*/
/**
* Frees memory allocated with SUPContAlloc().
*
* @returns VBox status code.
* @param pv Pointer to the memory block which should be freed.
* @param cPages Number of pages to be freed.
*/
/**
* Allocated non contiguous physical memory below 4GB.
*
* The memory isn't zeroed.
*
* @returns VBox status code.
* @returns NULL on failure.
* @param cPages Number of pages to allocate.
* @param ppvPages Where to store the pointer to the allocated memory.
* The pointer stored here on success must be passed to SUPLowFree when
* the memory should be released.
* @param ppvPagesR0 Where to store the ring-0 pointer to the allocated memory. optional.
* @param paPages Where to store the physical addresses of the individual pages.
*/
/**
* Frees memory allocated with SUPLowAlloc().
*
* @returns VBox status code.
* @param pv Pointer to the memory block which should be freed.
* @param cPages Number of pages that was allocated.
*/
/**
* Load a module into R0 HC.
*
* @returns VBox status code.
* @param pszFilename The path to the image file.
* @param pszModule The module name. Max 32 bytes.
*/
/**
* Frees a R0 HC module.
*
* @returns VBox status code.
* @param pszModule The module to free.
* @remark This will not actually 'free' the module, there are of course usage counting.
*/
/**
* Get the address of a symbol in a ring-0 module.
*
* @returns VBox status code.
* @param pszModule The module name.
* @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
* ordinal value rather than a string pointer.
* @param ppvValue Where to store the symbol value.
*/
/**
* Load R0 HC VMM code.
*
* @returns VBox status code.
* @deprecated Use SUPLoadModule(pszFilename, "VMMR0.r0", &pvImageBase)
*/
/**
* Unloads R0 HC VMM code.
*
* @returns VBox status code.
* @deprecated Use SUPFreeModule().
*/
SUPR3DECL(int) SUPUnloadVMM(void);
/**
* Get the physical address of the GIP.
*
* @returns VBox status code.
* @param pHCPhys Where to store the physical address of the GIP.
*/
/** @} */
#endif /* IN_RING3 */
#ifdef IN_RING0
/** @defgroup grp_sup_r0 SUP Host Context Ring 0 API
* @ingroup grp_sup
* @{
*/
/**
*/
#define SUPDRVEXECCALLBACK_CPU_ALL (~0)
/**
* Security objectype.
*/
typedef enum SUPDRVOBJTYPE
{
/** The usual invalid object. */
/** A Virtual Machine instance. */
/** Internal network. */
/** Internal network interface. */
/** The first invalid object type in this end. */
/** The usual 32-bit type size hack. */
SUPDRVOBJTYPE_32_BIT_HACK = 0x7ffffff
/**
* Object destructor callback.
* This is called for reference counted objectes when the count reaches 0.
*
* @param pvObj The object pointer.
* @param pvUser1 The first user argument.
* @param pvUser2 The second user argument.
*/
/** Pointer to a FNSUPDRVDESTRUCTOR(). */
typedef FNSUPDRVDESTRUCTOR *PFNSUPDRVDESTRUCTOR;
SUPR0DECL(void *) SUPR0ObjRegister(PSUPDRVSESSION pSession, SUPDRVOBJTYPE enmType, PFNSUPDRVDESTRUCTOR pfnDestructor, void *pvUser1, void *pvUser2);
SUPR0DECL(int) SUPR0LockMem(PSUPDRVSESSION pSession, RTR3PTR pvR3, uint32_t cPages, PRTHCPHYS paPages);
SUPR0DECL(int) SUPR0ContAlloc(PSUPDRVSESSION pSession, uint32_t cPages, PRTR0PTR ppvR0, PRTR3PTR ppvR3, PRTHCPHYS pHCPhys);
SUPR0DECL(int) SUPR0LowAlloc(PSUPDRVSESSION pSession, uint32_t cPages, PRTR0PTR ppvR0, PRTR3PTR ppvR3, PRTHCPHYS paPages);
SUPR0DECL(int) SUPR0PageAlloc(PSUPDRVSESSION pSession, uint32_t cPages, PRTR3PTR ppvR3, PRTHCPHYS paPages);
/**
* Support driver component factory.
*
* Component factories are registered by drivers that provides services
* such as the host network interface filtering and access to the host
*
* @remark Module dependencies and making sure that a component doesn't
* get unloaded while in use, is the sole responsibility of the
*/
typedef struct SUPDRVFACTORY
{
/** The (unique) name of the component factory. */
char szName[56];
/**
* Queries a factory interface.
*
* The factory interface is specific to each component and will be be
* found in the header(s) for the component alongside its UUID.
*
* @returns Pointer to the factory interfaces on success, NULL on failure.
*
* @param pSupDrvFactory Pointer to this structure.
* @param pSession The SUPDRV session making the query.
* @param pszInterfaceUuid The UUID of the factory interface.
*/
DECLR0CALLBACKMEMBER(void *, pfnQueryFactoryInterface,(struct SUPDRVFACTORY const *pSupDrvFactory, PSUPDRVSESSION pSession, const char *pszInterfaceUuid));
/** Pointer to a support driver factory. */
typedef SUPDRVFACTORY *PSUPDRVFACTORY;
/** Pointer to a const support driver factory. */
typedef SUPDRVFACTORY const *PCSUPDRVFACTORY;
SUPR0DECL(int) SUPR0ComponentQueryFactory(PSUPDRVSESSION pSession, const char *pszName, const char *pszInterfaceUuid, void **ppvFactoryIf);
/** @defgroup grp_sup_r0_idc The IDC Interface
* @ingroup grp_sup_r0
* @{
*/
/** The current SUPDRV IDC version.
* This follows the usual high word / low word rules, i.e. high word is the
* major number and it signifies incompatible interface changes. */
/**
* Inter-Driver Communcation Handle.
*/
typedef union SUPDRVIDCHANDLE
{
/** Padding for opaque usage.
* Must be greater or equal in size than the private struct. */
void *apvPadding[4];
/** The private view. */
struct SUPDRVIDCHANDLEPRIVATE s;
#endif
/** Pointer to a handle. */
typedef SUPDRVIDCHANDLE *PSUPDRVIDCHANDLE;
SUPR0DECL(int) SUPR0IdcComponentRegisterFactory(PSUPDRVIDCHANDLE pHandle, PCSUPDRVFACTORY pFactory);
SUPR0DECL(int) SUPR0IdcComponentDeregisterFactory(PSUPDRVIDCHANDLE pHandle, PCSUPDRVFACTORY pFactory);
/** @} */
/** @} */
#endif
/** @} */
#endif