sup.h revision ad27e1d5e48ca41245120c331cc88b50464813ce
/** AMD64 mode with global pages, no NX. */ /** AMD64 mode with NX, no global pages. */ /** AMD64 mode with global pages and NX. */ #
pragma pack(
1)
/* paranoia */ /** 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 /** 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. */ /** 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. */ /** Array of recent TSC interval deltas. * The most recent item is at index iTSCHistoryHead. * This history is used to calculate u32UpdateIntervalTSC. /** The interval between the last two NanoTS updates. (experiment for now) */ /** Reserved for future per processor data. */ /*AssertCompileMemberAlignment(SUPGIPCPU, u64TSC, 8); -fixme */ /** Pointer to per cpu data. * @remark there is no const version of this typedef, see g_pSUPGlobalInfoPage for details. */ * 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. /** Magic (SUPGLOBALINFOPAGE_MAGIC). */ /** The GIP update mode, see SUPGIPMODE. */ /** Reserved / padding. */ /** The update frequency of the of the NanoTS. */ /** The update interval in nanoseconds. (10^9 / u32UpdateHz) */ /** The timestamp of the last time we update the update frequency. */ /** 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. */ #
pragma pack()
/* end of paranoia *//** The value of the SUPGLOBALINFOPAGE::u32Magic field. (Soryo Fuyumi) */ * Upper 16 bits is the major version. Major version is only changed with * incompatible changes in the GIP. */ * SUPGLOBALINFOPAGE::u32Mode values. /** The usual invalid null entry. */ /** 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. */ /** 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 highly volatile and not trust it beyond * @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. #
else /* IN_RING0 && !RT_OS_WINDOWS *//** 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.) */ * We save a level of indirection by exporting the GIP instead of a variable * @returns Pointer to the GIP or NULL. * Gets the TSC frequency of the calling CPU. * @returns TSC frequency. * @param pGip The GIP pointer. * Request for generic VMMR0Entry calls. /** The magic. (SUPVMMR0REQHDR_MAGIC) */ /** The size of the request. */ /** Pointer to a ring-0 request header. */ /** the SUPVMMR0REQHDR::u32Magic value (Ethan Iverson - The Bad Plus). */ /** For the fast ioctl path. /** @see VMMR0_DO_RAW_RUN. */ /** @see VMMR0_DO_HWACC_RUN. */ /** SUPR3QueryVTCaps capability flags * Request for generic FNSUPR0SERVICEREQHANDLER calls. /** The magic. (SUPR0SERVICEREQHDR_MAGIC) */ /** The size of the request. */ /** Pointer to a ring-0 service request header. */ /** the SUPVMMR0REQHDR::u32Magic value (Esbjoern Svensson - E.S.P.). */ /** Event semaphore handle. Ring-0 / ring-3. */ /** Pointer to an event semaphore handle. */ /** Nil event semaphore handle. */ * Creates a single release event semaphore. * @returns VBox status code. * @param pSession The session handle of the caller. * @param phEvent Where to return the handle to the event semaphore. * Closes a single release event semaphore handle. * @returns VBox status code. * @retval VINF_OBJECT_DESTROYED if the semaphore was destroyed. * @retval VINF_SUCCESS if the handle was successfully closed but the semaphore * object remained alive because of other references. * @param pSession The session handle of the caller. * @param hEvent The handle. Nil is quietly ignored. * Signals a single release event semaphore. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEvent The semaphore handle. * Waits on a single release event semaphore, not interruptible. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEvent The semaphore handle. * @param cMillies The number of milliseconds to wait. * @remarks Not available in ring-3. * Waits on a single release event semaphore, interruptible. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEvent The semaphore handle. * @param cMillies The number of milliseconds to wait. * Waits on a single release event semaphore, interruptible. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEvent The semaphore handle. * @param uNsTimeout The deadline given on the RTTimeNanoTS() clock. * Waits on a single release event semaphore, interruptible. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEvent The semaphore handle. * @param cNsTimeout The number of nanoseconds to wait. * Gets the best timeout resolution that SUPSemEventWaitNsAbsIntr and * SUPSemEventWaitNsAbsIntr can do. * @returns The resolution in nanoseconds. * @param pSession The session handle of the caller. /** Multiple release event semaphore handle. Ring-0 / ring-3. */ /** Pointer to an multiple release event semaphore handle. */ /** Nil multiple release event semaphore handle. */ * Creates a multiple release event semaphore. * @returns VBox status code. * @param pSession The session handle of the caller. * @param phEventMulti Where to return the handle to the event semaphore. * Closes a multiple release event semaphore handle. * @returns VBox status code. * @retval VINF_OBJECT_DESTROYED if the semaphore was destroyed. * @retval VINF_SUCCESS if the handle was successfully closed but the semaphore * object remained alive because of other references. * @param pSession The session handle of the caller. * @param hEventMulti The handle. Nil is quietly ignored. * Signals a multiple release event semaphore. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEventMulti The semaphore handle. * Resets a multiple release event semaphore. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEventMulti The semaphore handle. * Waits on a multiple release event semaphore, not interruptible. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEventMulti The semaphore handle. * @param cMillies The number of milliseconds to wait. * @remarks Not available in ring-3. * Waits on a multiple release event semaphore, interruptible. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEventMulti The semaphore handle. * @param cMillies The number of milliseconds to wait. * Waits on a multiple release event semaphore, interruptible. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEventMulti The semaphore handle. * @param uNsTimeout The deadline given on the RTTimeNanoTS() clock. * Waits on a multiple release event semaphore, interruptible. * @returns VBox status code. * @param pSession The session handle of the caller. * @param hEventMulti The semaphore handle. * @param cNsTimeout The number of nanoseconds to wait. * Gets the best timeout resolution that SUPSemEventMultiWaitNsAbsIntr and * SUPSemEventMultiWaitNsRelIntr can do. * @returns The resolution in nanoseconds. * @param pSession The session handle of the caller. /** @defgroup grp_sup_r3 SUP Host Context Ring-3 API * Installs the support library. * @returns VBox status code. * Uninstalls the support library. * @returns VBox status code. * Trusted main entry point. * This is exported as "TrustedMain" by the dynamic libraries which contains the * "real" application binary for which the hardened stub is built. The entry * point is invoked upon successful initialization of the support library and * @returns main kind of exit code. * @param argc The argument count. * @param argv The argument vector. * @param envp The environment vector. /** Pointer to FNSUPTRUSTEDMAIN(). */ /** Which operation failed. */ /** Installation integrity error. */ /** IPRT init related. */ * Trusted error entry point, optional. * This is exported as "TrustedError" by the dynamic libraries which contains * the "real" application binary for which the hardened stub is built. * @param pszWhere Where the error occurred (function name). * @param enmWhat Which operation went wrong. * @param rc The status code. * @param pszMsgFmt Error message format string. * @param va The message format arguments. /** Pointer to FNSUPTRUSTEDERROR. */ * 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 * @returns Return code appropriate for main(). * @param pszProgName The program name. This will be used to figure out which * @param argc The argument count. * @param argv The argument vector. * @param envp The environment vector. /** @name SUPR3SecureMain flags. /** Don't open the device. (Intended for VirtualBox without -startvm.) */ * Initializes the support library. * Each successful call to SUPR3Init() must be countered by a * call to SUPR3Term(false). * @returns VBox status code. * @param ppSession Where to store the session handle. Defaults to NULL. * Terminates the support library. * @returns VBox status code. * @param fForced Forced termination. This means to ignore the * init call count and just terminated. * 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 idCpu The virtual CPU ID. * @param uOperation Operation to execute. * Variant of SUPR3CallVMMR0, 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. * @param idCpu The virtual CPU ID. * Calls the HC R0 VMM entry point, in a safer but slower manner than * SUPR3CallVMMR0. 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 idCpu The virtual CPU ID. * @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. * Calls a ring-0 service. * The operation and the request packet is specific to the service. * @returns error code specific to uFunction. * @param pszService The service name. * @param cchService The length of the service name. * @param uReq The request number. * @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. * Changes the settings of the specified ring-0 logger. * @returns VBox status code. * @param enmWhich Which logger. * @param pszFlags The flags settings. * @param pszGroups The groups settings. * @param pszDest The destination specificier. * Creates a ring-0 logger instance. * @returns VBox status code. * @param enmWhich Which logger to create. * @param pszFlags The flags settings. * @param pszGroups The groups settings. * @param pszDest The destination specificier. * Destroys a ring-0 logger instance. * @returns VBox status code. * @param enmWhich Which logger. * Queries the paging mode of the host OS. * @returns The paging mode. * Allocate zero-filled pages. * Use this to allocate a number of pages suitable for seeding / locking. * Call SUPR3PageFree() to free the pages once done with them. * @param cPages Number of pages to allocate. * @param ppvPages Where to store the base pointer to the allocated pages. * Frees pages allocated with SUPR3PageAlloc(). * @param pvPages Pointer returned by SUPR3PageAlloc(). * @param cPages Number of pages that was allocated. * Allocate non-zeroed, locked, pages with user and, optionally, kernel * Use SUPR3PageFreeEx() to free memory allocated with this function. * @returns VBox status code. * @param cPages The number of pages to allocate. * @param fFlags Flags, reserved. Must be zero. * @param ppvPages Where to store the address of the user mapping. * @param pR0Ptr Where to store the address of the kernel mapping. * NULL if no kernel mapping is desired. * @param paPages Where to store the physical addresses of each page. * Maps a portion of a ring-3 only allocation into kernel space. * @returns VBox status code. * @param pvR3 The address SUPR3PageAllocEx return. * @param off Offset to start mapping at. Must be page aligned. * @param cb Number of bytes to map. Must be page aligned. * @param fFlags Flags, must be zero. * @param pR0Ptr Where to store the address on success. * Changes the protection of * @returns VBox status code. * @retval VERR_NOT_SUPPORTED if the OS doesn't allow us to change page level * protection. See also RTR0MemObjProtect. * @param pvR3 The ring-3 address SUPR3PageAllocEx returned. * @param R0Ptr The ring-0 address SUPR3PageAllocEx returned if it * is desired that the corresponding ring-0 page * mappings should change protection as well. Pass * NIL_RTR0PTR if the ring-0 pages should remain * @param off Offset to start at which to start chagning the page * level protection. Must be page aligned. * @param cb Number of bytes to change. Must be page aligned. * @param fProt The new page level protection, either a combination * of RTMEM_PROT_READ, RTMEM_PROT_WRITE and * RTMEM_PROT_EXEC, or just RTMEM_PROT_NONE. * Free pages allocated by SUPR3PageAllocEx. * @returns VBox status code. * @param pvPages The address of the user mapping. * @param cPages The number of pages. * 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 SUPR3ContFree(). * @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 * Frees memory allocated with SUPR3ContAlloc(). * @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 * SUPR3LowFree 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 SUPR3LowAlloc(). * @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. * This will verify the file integrity in a similar manner as * SUPR3HardenedVerifyFile before loading it. * @returns VBox status code. * @param pszFilename The path to the image file. * @param pszModule The module name. Max 32 bytes. * @param ppvImageBase Where to store the image address. * Load a module into R0 HC. * This will verify the file integrity in a similar manner as * SUPR3HardenedVerifyFile before loading it. * @returns VBox status code. * @param pszFilename The path to the image file. * @param pszModule The module name. Max 32 bytes. * @param pszSrvReqHandler The name of the service request handler entry * point. See FNSUPR0SERVICEREQHANDLER. * @param ppvImageBase Where to store the image address. * @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. * @returns VBox status code. * @deprecated Use SUPR3LoadModule(pszFilename, "VMMR0.r0", &pvImageBase) * Unloads R0 HC VMM code. * @returns VBox status code. * @deprecated Use SUPR3FreeModule(). * Get the physical address of the GIP. * @returns VBox status code. * @param pHCPhys Where to store the physical address of the GIP. * Verifies the integrity of a file, and optionally opens it. * The integrity check is for whether the file is suitable for loading into * the hypervisor or VM process. The integrity check may include verifying * @returns VBox status code. On failure it will have printed a LogRel message. * @param pszFilename The file. * @param pszWhat For the LogRel on failure. * @param phFile Where to store the handle to the opened file. This is optional, pass NULL * if the file should not be opened. * Same as RTLdrLoad() but will verify the files it loads (hardened builds). * Will add dll suffix if missing and try load the file. * @returns iprt status code. * @param pszFilename Image filename. This must have a path. * @param phLdrMod Where to store the handle to the loaded module. * Same as RTLdrLoadAppPriv() but it will verify the files it loads (hardened * Will add dll suffix to the file if missing, then look for it in the * architecture dependent application directory. * @returns iprt status code. * @param pszFilename Image filename. * @param phLdrMod Where to store the handle to the loaded module. * Check if the host kernel can run in VMX root mode. * @returns VINF_SUCCESS if supported, error code indicating why if not. * @returns VINF_SUCCESS if supported, error code indicating why if not. * @param pfCaps Pointer to capability dword (out). * @todo Intended for main, which means we need to relax the privilege requires * when accessing certain vboxdrv functions. /** @defgroup grp_sup_r0 SUP Host Context Ring-0 API /** The usual invalid object. */ /** A Virtual Machine instance. */ /** Internal network interface. */ /** Single release event semaphore. */ /** Multiple release event semaphore. */ /** The first invalid object type in this end. */ /** The usual 32-bit type size hack. */ * 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(). */ /** @name Absolute symbols * Take the address of these, don't try call them. * 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 /** The (unique) name of the component factory. */ * 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. /** Pointer to a support driver factory. */ /** Pointer to a const support driver factory. */ * Service request callback function. * @returns VBox status code. * @param pSession The caller's session. * @param u64Arg 64-bit integer argument. * @param pReqHdr The request header. Input / Output. Optional. /** Pointer to a FNR0SERVICEREQHANDLER(). */ /** @defgroup grp_sup_r0_idc The IDC Interface /** 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 Communication Handle. /** Padding for opaque usage. * Must be greater or equal in size than the private struct. */ /** Pointer to a handle. */