mm.h revision 3e6c6998d1dfeded8b9a23f5aa94ad63e9a681d9
/** @file
* MM - The Memory Manager.
*/
/*
* 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;
* 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_mm_h
#define ___VBox_mm_h
/** @defgroup grp_mm The Memory Manager API
* @{
*/
/** @name RAM Page Flags
* Since internal ranges have a byte granularity it's possible for a
* page be flagged for several uses. The access virtualization in PGM
* will choose the most restricted one and use EM to emulate access to
* the less restricted areas of the page.
*
* Bits 0-11 only since they are fitted into the offset part of a physical memory address.
* @{
*/
/** Reserved - Not RAM, ROM nor MMIO2.
* If this bit is cleared the memory is assumed to be some kind of RAM.
* Normal MMIO may set it but that depends on whether the RAM range was
* created specially for the MMIO or not.
*
* @remarks The current implementation will always reserve backing
* memory for reserved ranges to simplify things.
*/
#define MM_RAM_FLAGS_RESERVED RT_BIT(0)
/** ROM - Read Only Memory.
* The page have a HC physical address which contains the BIOS code. All write
* access is trapped and ignored.
*
* HACK: Writable shadow ROM is indicated by both ROM and MMIO2 being
* set. (We're out of bits.)
*/
/** MMIO - Memory Mapped I/O.
* All access is trapped and emulated. No physical backing is required, but
* might for various reasons be present.
*/
/** MMIO2 - Memory Mapped I/O, variation 2.
* The virtualization is performed using real memory and only catching
* a few accesses for like keeping track for dirty pages.
* @remark Involved in the shadow ROM hack.
*/
/** PGM has virtual page access handler(s) defined for pages with this flag. */
/** PGM has virtual page access handler(s) for write access. */
/** PGM has virtual page access handler(s) for all access. */
/** PGM has physical page access handler(s) defined for pages with this flag. */
/** PGM has physical page access handler(s) for write access. */
/** PGM has physical page access handler(s) for all access. */
/** PGM has physical page access handler(s) for this page and has temporarily disabled it. */
#ifndef NEW_PHYS_CODE
/** Physical backing memory is allocated dynamically. Not set implies a one time static allocation. */
#endif /* !NEW_PHYS_CODE */
/** The shift used to get the reference count. */
#define MM_RAM_FLAGS_CREFS_SHIFT 62
/** The mask applied to the the page pool idx after using MM_RAM_FLAGS_CREFS_SHIFT to shift it down. */
#define MM_RAM_FLAGS_CREFS_MASK 0x3
/** The (shifted) cRef value used to indiciate that the idx is the head of a
* physical cross reference extent list. */
/** The shift used to get the page pool idx. (Apply MM_RAM_FLAGS_IDX_MASK to the result when shifting down). */
#define MM_RAM_FLAGS_IDX_SHIFT 48
/** The mask applied to the the page pool idx after using MM_RAM_FLAGS_IDX_SHIFT to shift it down. */
#define MM_RAM_FLAGS_IDX_MASK 0x3fff
/** The idx value when we're out of of extents or there are simply too many mappings of this page. */
/** Mask for masking off any references to the page. */
/** @} */
/** @name MMR3PhysRegisterEx registration type
* @{
*/
typedef enum
{
/** Normal physical region (flags specify exact page type) */
MM_PHYS_TYPE_NORMAL = 0,
/** Allocate part of a dynamically allocated physical region */
MM_PHYS_TYPE_32BIT_HACK = 0x7fffffff
} MMPHYSREG;
/** @} */
/**
* Memory Allocation Tags.
* For use with MMHyperAlloc(), MMR3HeapAlloc(), MMR3HeapAllocEx(),
* MMR3HeapAllocZ() and MMR3HeapAllocZEx().
*
* @remark Don't forget to update the dump command in MMHeap.cpp!
*/
typedef enum MMTAG
{
MM_TAG_INVALID = 0,
MM_TAG_32BIT_HACK = 0x7fffffff
} MMTAG;
/** @defgroup grp_mm_hyper Hypervisor Memory Management
* @ingroup grp_mm
* @{ */
/**
* Converts a ring-0 host context address in the Hypervisor memory region to a ring-3 host context address.
*
* @returns ring-3 host context address.
* @param pVM The VM to operate on.
* @param R0Ptr The ring-0 host context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
/**
* Converts a ring-0 host context address in the Hypervisor memory region to a guest context address.
*
* @returns guest context address.
* @param pVM The VM to operate on.
* @param R0Ptr The ring-0 host context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
/**
* Converts a ring-0 host context address in the Hypervisor memory region to a current context address.
*
* @returns current context address.
* @param pVM The VM to operate on.
* @param R0Ptr The ring-0 host context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
#ifndef IN_RING0
#endif
/**
* Converts a ring-3 host context address in the Hypervisor memory region to a ring-0 host context address.
*
* @returns ring-0 host context address.
* @param pVM The VM to operate on.
* @param R3Ptr The ring-3 host context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
/**
* Converts a ring-3 host context address in the Hypervisor memory region to a guest context address.
*
* @returns guest context address.
* @param pVM The VM to operate on.
* @param R3Ptr The ring-3 host context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
/**
* Converts a ring-3 host context address in the Hypervisor memory region to a current context address.
*
* @returns current context address.
* @param pVM The VM to operate on.
* @param R3Ptr The ring-3 host context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
#ifndef IN_RING3
#else
{
return R3Ptr;
}
#endif
/**
* Converts a guest context address in the Hypervisor memory region to a ring-3 context address.
*
* @returns ring-3 host context address.
* @param pVM The VM to operate on.
* @param GCPtr The guest context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
/**
* Converts a guest context address in the Hypervisor memory region to a ring-0 host context address.
*
* @returns ring-0 host context address.
* @param pVM The VM to operate on.
* @param GCPtr The guest context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
/**
* Converts a guest context address in the Hypervisor memory region to a current context address.
*
* @returns current context address.
* @param pVM The VM to operate on.
* @param GCPtr The guest host context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
#ifndef IN_GC
#else
{
return GCPtr;
}
#endif
/**
* Converts a current context address in the Hypervisor memory region to a ring-3 host context address.
*
* @returns ring-3 host context address.
* @param pVM The VM to operate on.
* @param pv The current context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
#ifndef IN_RING3
#else
{
return pv;
}
#endif
/**
* Converts a current context address in the Hypervisor memory region to a ring-0 host context address.
*
* @returns ring-0 host context address.
* @param pVM The VM to operate on.
* @param pv The current context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
#ifndef IN_RING0
#else
{
return pv;
}
#endif
/**
* Converts a current context address in the Hypervisor memory region to a guest context address.
*
* @returns guest context address.
* @param pVM The VM to operate on.
* @param pv The current context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
*/
#ifndef IN_GC
#else
{
return pv;
}
#endif
/**
* Converts a current context address in the Hypervisor memory region to a HC address.
* The memory must have been allocated with MMHyperAlloc().
*
* @returns HC address.
* @param pVM The VM to operate on.
* @param Ptr The current context address.
* @thread The Emulation Thread.
* @deprecated
*/
#ifdef IN_GC
#else
{
}
#endif
/**
* Converts a current context address in the Hypervisor memory region to a GC address.
* The memory must have been allocated with MMHyperAlloc().
*
* @returns HC address.
* @param pVM The VM to operate on.
* @param Ptr The current context address.
* @thread The Emulation Thread.
*/
#ifndef IN_GC
#else
{
}
#endif
/**
* Converts a HC address in the Hypervisor memory region to a GC address.
* The memory must have been allocated with MMGCHyperAlloc() or MMR3HyperAlloc().
*
* @returns GC address.
* @param pVM The VM to operate on.
* @param HCPtr The host context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
* @deprecated
*/
/**
* Converts a GC address in the Hypervisor memory region to a HC address.
* The memory must have been allocated with MMGCHyperAlloc() or MMR3HyperAlloc().
*
* @returns HC address.
* @param pVM The VM to operate on.
* @param GCPtr The guest context address.
* You'll be damned if this is not in the HMA! :-)
* @thread The Emulation Thread.
* @deprecated
*/
/**
* Allocates memory in the Hypervisor (GC VMM) area.
* The returned memory is of course zeroed.
*
* @returns VBox status code.
* @param pVM The VM to operate on.
* @param cb Number of bytes to allocate.
* @param uAlignment Required memory alignment in bytes.
* Values are 0,8,16,32 and PAGE_SIZE.
* 0 -> default alignment, i.e. 8 bytes.
* @param enmTag The statistics tag.
* @param ppv Where to store the address to the allocated
* memory.
* @remark This is assumed not to be used at times when serialization is required.
*/
/**
* Free memory allocated using MMHyperAlloc().
*
* It's not possible to free memory which is page aligned!
*
* @returns VBox status code.
* @param pVM The VM to operate on.
* @param pv The memory to free.
* @remark Try avoid freeing hyper memory.
* @thread The Emulation Thread.
*/
#ifdef DEBUG
/**
* Dumps the hypervisor heap to Log.
* @param pVM VM Handle.
* @thread The Emulation Thread.
*/
#endif
/**
* Query the amount of free memory in the hypervisor heap.
*
* @returns Number of free bytes in the hypervisor heap.
* @thread Any.
*/
/**
* Query the size the hypervisor heap.
*
* @returns The size of the hypervisor heap in bytes.
* @thread Any.
*/
/**
* Query the address and size the hypervisor memory area.
*
* @returns Base address of the hypervisor area.
* @param pVM VM Handle.
* @param pcb Where to store the size of the hypervisor area. (out)
* @thread Any.
*/
/**
* Checks if an address is within the hypervisor memory area.
*
* @returns true if inside.
* @returns false if outside.
* @param pVM VM handle.
* @param GCPtr The pointer to check.
* @thread The Emulation Thread.
*/
/**
* Convert a page in the page pool to a HC physical address.
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
* and MMR3PageAllocLow().
*
* @returns Physical address for the specified page table.
* @param pVM VM handle.
* @param pvPage Page which physical address we query.
* @thread The Emulation Thread.
*/
/**
* Convert physical address of a page to a HC virtual address.
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
* and MMR3PageAllocLow().
*
* @returns Pointer to the page at that physical address.
* @param pVM VM handle.
* @param HCPhysPage The physical address of a page.
* @thread The Emulation Thread.
*/
/**
* Convert physical address of a page to a HC virtual address.
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
* and MMR3PageAllocLow().
*
* @returns VBox status code.
* @param pVM VM handle.
* @param HCPhysPage The physical address of a page.
* @param ppvPage Where to store the address corresponding to HCPhysPage.
* @thread The Emulation Thread.
*/
/**
* Try convert physical address of a page to a HC virtual address.
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
* and MMR3PageAllocLow().
*
* @returns VBox status code.
* @param pVM VM handle.
* @param HCPhysPage The physical address of a page.
* @param ppvPage Where to store the address corresponding to HCPhysPage.
* @thread The Emulation Thread.
*/
/**
* Convert GC physical address to HC virtual address.
*
* @returns HC virtual address.
* @param pVM VM Handle
* @param GCPhys Guest context physical address.
* @param cbRange Physical range
* @thread The Emulation Thread.
* @deprecated
*/
/** @def MMHYPER_GC_ASSERT_GCPTR
* Asserts that an address is either NULL or inside the hypervisor memory area.
* This assertion only works while IN_GC, it's a NOP everywhere else.
* @thread The Emulation Thread.
*/
#ifdef IN_GC
# define MMHYPER_GC_ASSERT_GCPTR(pVM, GCPtr) Assert(MMHyperIsInsideArea((pVM), (GCPtr)) || !(GCPtr))
#else
#endif
/** @} */
#ifdef IN_RING3
/** @defgroup grp_mm_r3 The MM Host Context Ring-3 API
* @ingroup grp_mm
* @{
*/
/**
* Initialization of MM (save anything depending on PGM).
*
* @returns VBox status code.
* @param pVM The VM to operate on.
* @thread The Emulation Thread.
*/
/**
* Initializes the MM parts which depends on PGM being initialized.
*
* @returns VBox status code.
* @param pVM The VM to operate on.
* @thread The Emulation Thread.
*/
/**
* Finalizes the HMA mapping.
*
* This is called later during init, most (all) HMA allocations should be done
* by the time this function is called.
*
* @returns VBox status.
*/
/**
* Terminates the MM.
*
* Termination means cleaning up and freeing all resources,
* the VM it self is at this point powered off or suspended.
*
* @returns VBox status code.
* @param pVM The VM to operate on.
* @thread The Emulation Thread.
*/
/**
* Reset notification.
*
* MM will reload shadow ROMs into RAM at this point and make
* the ROM writable.
*
* @param pVM The VM handle.
*/
/**
* Convert HC Physical address to HC Virtual address.
*
* @returns VBox status.
* @param pVM VM handle.
* @param HCPhys The host context virtual address.
* @param ppv Where to store the resulting address.
* @thread The Emulation Thread.
*/
/**
* Read memory from GC virtual address using the current guest CR3.
*
* @returns VBox status.
* @param pVM VM handle.
* @param pvDst Destination address (HC of course).
* @param GCPtr GC virtual address.
* @param cb Number of bytes to read.
* @thread The Emulation Thread.
*/
/**
* Write to memory at GC virtual address translated using the current guest CR3.
*
* @returns VBox status.
* @param pVM VM handle.
* @param GCPtrDst GC virtual address.
* @param pvSrc The source address (HC of course).
* @param cb Number of bytes to read.
*/
/** @defgroup grp_mm_r3_hyper Hypervisor Memory Manager (HC R3 Portion)
* @ingroup grp_mm_r3
* @{ */
/**
* Allocates memory in the Hypervisor (GC VMM) area which never will
* be freed and don't have any offset based relation to other heap blocks.
*
* The latter means that two blocks allocated by this API will not have the
* same relative position to each other in GC and HC. In short, never use
* this API for allocating nodes for an offset based AVL tree!
*
* The returned memory is of course zeroed.
*
* @returns VBox status code.
* @param pVM The VM to operate on.
* @param cb Number of bytes to allocate.
* @param uAlignment Required memory alignment in bytes.
* Values are 0,8,16,32 and PAGE_SIZE.
* 0 -> default alignment, i.e. 8 bytes.
* @param enmTag The statistics tag.
* @param ppv Where to store the address to the allocated
* memory.
* @remark This is assumed not to be used at times when serialization is required.
*/
MMDECL(int) MMR3HyperAllocOnceNoRel(PVM pVM, size_t cb, uint32_t uAlignment, MMTAG enmTag, void **ppv);
/**
* Maps contiguous HC physical memory into the hypervisor region in the GC.
*
* @return VBox status code.
*
* @param pVM VM handle.
* @param pvHC Host context address of the memory. Must be page aligned!
* @param HCPhys Host context physical address of the memory to be mapped. Must be page aligned!
* @param cb Size of the memory. Will be rounded up to nearest page.
* @param pszDesc Description.
* @param pGCPtr Where to store the GC address.
* @thread The Emulation Thread.
*/
MMR3DECL(int) MMR3HyperMapHCPhys(PVM pVM, void *pvHC, RTHCPHYS HCPhys, size_t cb, const char *pszDesc, PRTGCPTR pGCPtr);
/**
* Maps contiguous GC physical memory into the hypervisor region in the GC.
*
* @return VBox status code.
*
* @param pVM VM handle.
* @param GCPhys Guest context physical address of the memory to be mapped. Must be page aligned!
* @param cb Size of the memory. Will be rounded up to nearest page.
* @param pszDesc Mapping description.
* @param pGCPtr Where to store the GC address.
* @thread The Emulation Thread.
*/
MMR3DECL(int) MMR3HyperMapGCPhys(PVM pVM, RTGCPHYS GCPhys, size_t cb, const char *pszDesc, PRTGCPTR pGCPtr);
/**
* Locks and Maps HC virtual memory into the hypervisor region in the GC.
*
* @return VBox status code.
*
* @param pVM VM handle.
* @param pvHC Host context address of the memory (may be not page aligned).
* @param cb Size of the memory. Will be rounded up to nearest page.
* @param fFree Set this if MM is responsible for freeing the memory using SUPPageFree.
* @param pszDesc Mapping description.
* @param pGCPtr Where to store the GC address corresponding to pvHC.
* @thread The Emulation Thread.
*/
MMR3DECL(int) MMR3HyperMapHCRam(PVM pVM, void *pvHC, size_t cb, bool fFree, const char *pszDesc, PRTGCPTR pGCPtr);
/**
* Maps locked R3 virtual memory into the hypervisor region in the GC.
*
* @return VBox status code.
*
* @param pVM VM handle.
* @param pvR3 The ring-3 address of the memory, must be page aligned.
* @param pvR0 The ring-0 address of the memory, must be page aligned. (optional)
* @param cPages The number of pages.
* @param paPages The page descriptors.
* @param pszDesc Mapping description.
* @param pGCPtr Where to store the GC address corresponding to pvHC.
*/
MMR3DECL(int) MMR3HyperMapPages(PVM pVM, void *pvR3, RTR0PTR pvR0, size_t cPages, PCSUPPAGE paPages, const char *pszDesc, PRTGCPTR pGCPtr);
/**
* Reserves a hypervisor memory area.
* Most frequent usage is fence pages and dynamically mappings like the guest PD and PDPTR.
*
* @return VBox status code.
*
* @param pVM VM handle.
* @param cb Size of the memory. Will be rounded up to nearest page.
* @param pszDesc Mapping description.
* @param pGCPtr Where to store the assigned GC address. Optional.
* @thread The Emulation Thread.
*/
/**
* Convert hypervisor HC virtual address to HC physical address.
*
* @returns HC physical address.
* @param pVM VM Handle
* @param pvHC Host context physical address.
* @thread The Emulation Thread.
*/
/**
* Convert hypervisor HC virtual address to HC physical address.
*
* @returns HC physical address.
* @param pVM VM Handle
* @param pvHC Host context physical address.
* @param pHCPhys Where to store the HC physical address.
* @thread The Emulation Thread.
*/
/**
* Convert hypervisor HC physical address to HC virtual address.
*
* @returns HC virtual address.
* @param pVM VM Handle
* @param HCPhys Host context physical address.
* @thread The Emulation Thread.
*/
/**
* Convert hypervisor HC physical address to HC virtual address.
*
* @returns VBox status.
* @param pVM VM Handle
* @param HCPhys Host context physical address.
* @param ppv Where to store the HC virtual address.
* @thread The Emulation Thread.
*/
/**
* Read hypervisor memory from GC virtual address.
*
* @returns VBox status.
* @param pVM VM handle.
* @param pvDst Destination address (HC of course).
* @param GCPtr GC virtual address.
* @param cb Number of bytes to read.
* @thread The Emulation Thread.
*/
/** @} */
/** @defgroup grp_mm_phys Guest Physical Memory Manager
* @ingroup grp_mm_r3
* @{ */
/**
* Register externally allocated RAM for the virtual machine.
*
* The memory registered with the VM thru this interface must not be freed
* before the virtual machine has been destroyed. Bad things may happen... :-)
*
* @return VBox status code.
* @param pVM VM handle.
* @param pvRam Virtual address of the guest's physical memory range Must be page aligned.
* @param GCPhys The physical address the ram shall be registered at.
* @param cb Size of the memory. Must be page aligend.
* @param fFlags Flags of the MM_RAM_FLAGS_* defines.
* @param pszDesc Description of the memory.
* @thread The Emulation Thread.
*/
MMR3DECL(int) MMR3PhysRegister(PVM pVM, void *pvRam, RTGCPHYS GCPhys, unsigned cb, unsigned fFlags, const char *pszDesc);
/**
* Register externally allocated RAM for the virtual machine.
*
* The memory registered with the VM thru this interface must not be freed
* before the virtual machine has been destroyed. Bad things may happen... :-)
*
* @return VBox status code.
* @param pVM VM handle.
* @param pvRam Virtual address of the guest's physical memory range Must be page aligned.
* @param GCPhys The physical address the ram shall be registered at.
* @param cb Size of the memory. Must be page aligend.
* @param fFlags Flags of the MM_RAM_FLAGS_* defines.
* @param enmType Physical range type (MM_PHYS_TYPE_*)
* @param pszDesc Description of the memory.
* @thread The Emulation Thread.
* @todo update this description.
*/
MMR3DECL(int) MMR3PhysRegisterEx(PVM pVM, void *pvRam, RTGCPHYS GCPhys, unsigned cb, unsigned fFlags, MMPHYSREG enmType, const char *pszDesc);
/**
* Register previously registered externally allocated RAM for the virtual machine.
*
* Use this only for MMIO ranges or the guest will become very confused.
* The memory registered with the VM thru this interface must not be freed
* before the virtual machine has been destroyed. Bad things may happen... :-)
*
* @return VBox status code.
* @param pVM VM handle.
* @param GCPhysOld The physical address the ram was registered at.
* @param GCPhysNew The physical address the ram shall be registered at.
* @param cb Size of the memory. Must be page aligend.
* @thread The Emulation Thread.
*/
/**
* Register a ROM (BIOS) region.
*
* It goes without saying that this is read-only memory. The memory region must be
* in unassigned memory. I.e. from the top of the address space or on the PC in
* the 0xa0000-0xfffff range.
*
* @returns VBox status.
* @param pVM VM Handle.
* @param pDevIns The device instance owning the ROM region.
* @param GCPhys First physical address in the range.
* Must be page aligned!
* @param cbRange The size of the range (in bytes).
* Must be page aligned!
* @param pvBinary Pointer to the binary data backing the ROM image.
* This must be cbRange bytes big.
* It will be copied and doesn't have to stick around.
* It will be copied and doesn't have to stick around if fShadow is clear.
* @param fShadow Whether to emulate ROM shadowing. This involves leaving
* the ROM writable for a while during the POST and refreshing
* it at reset. When this flag is set, the memory pointed to by
* pvBinary has to stick around for the lifespan of the VM.
* @param pszDesc Pointer to description string. This must not be freed.
* @remark There is no way to remove the rom, automatically on device cleanup or
* manually from the device yet. At present I doubt we need such features...
* @thread The Emulation Thread.
*/
MMR3DECL(int) MMR3PhysRomRegister(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const void *pvBinary, bool fShadow, const char *pszDesc);
/**
* Write-protects a shadow ROM range.
*
* This is called late in the POST for shadow ROM ranges.
*
* @returns VBox status code.
* @param pVM The VM handle.
* @param GCPhys Start of the registered shadow ROM range
* @param cbRange The length of the registered shadow ROM range.
* This can be NULL (not sure about the BIOS interface yet).
*/
/**
* Reserve physical address space for ROM and MMIO ranges.
*
* @returns VBox status code.
* @param pVM VM Handle.
* @param GCPhys Start physical address.
* @param cbRange The size of the range.
* @param pszDesc Description string.
* @thread The Emulation Thread.
*/
/**
* Get the size of the base RAM.
* This usually means the size of the first contigous block of physical memory.
*
* @returns
* @param pVM
* @thread Any.
*/
/** @} */
/** @defgroup grp_mm_page Physical Page Pool
* @ingroup grp_mm_r3
* @{ */
/**
* Allocates a page from the page pool.
*
* This function may returns pages which has physical addresses any
* where. If you require a page to be within the first 4GB of physical
* memory, use MMR3PageAllocLow().
*
* @returns Pointer to the allocated page page.
* @returns NULL on failure.
* @param pVM VM handle.
* @thread The Emulation Thread.
*/
/**
* Allocates a page from the page pool and return its physical address.
*
* This function may returns pages which has physical addresses any
* where. If you require a page to be within the first 4GB of physical
* memory, use MMR3PageAllocLow().
*
* @returns Pointer to the allocated page page.
* @returns NIL_RTHCPHYS on failure.
* @param pVM VM handle.
* @thread The Emulation Thread.
*/
/**
* Frees a page allocated from the page pool by MMR3PageAlloc() and MMR3PageAllocPhys().
*
* @param pVM VM handle.
* @param pvPage Pointer to the page.
* @thread The Emulation Thread.
*/
/**
* Allocates a page from the low page pool.
*
* @returns Pointer to the allocated page.
* @returns NULL on failure.
* @param pVM VM handle.
* @thread The Emulation Thread.
*/
/**
* Frees a page allocated from the page pool by MMR3PageAllocLow().
*
* @param pVM VM handle.
* @param pvPage Pointer to the page.
* @thread The Emulation Thread.
*/
/**
* Free a page allocated from the page pool by physical address.
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
* and MMR3PageAllocLow().
*
* @param pVM VM handle.
* @param HCPhysPage The physical address of the page to be freed.
* @thread The Emulation Thread.
*/
/**
* Gets the HC pointer to the dummy page.
*
* The dummy page is used as a place holder to prevent potential bugs
* from doing really bad things to the system.
*
* @returns Pointer to the dummy page.
* @param pVM VM handle.
* @thread The Emulation Thread.
*/
/**
* Gets the HC Phys to the dummy page.
*
* The dummy page is used as a place holder to prevent potential bugs
* from doing really bad things to the system.
*
* @returns Pointer to the dummy page.
* @param pVM VM handle.
* @thread The Emulation Thread.
*/
#if 1 /* these are temporary wrappers and will be removed soon */
/**
* Allocates a Page Table.
*
* @returns Pointer to page table.
* @returns NULL on failure.
* @param pVM VM handle.
* @deprecated Use MMR3PageAlloc().
*/
{
}
/**
* Free a Page Table.
*
* @param pVM VM handle.
* @param pPT Pointer to the page table as returned by MMR3PTAlloc().
* @deprecated Use MMR3PageFree().
*/
{
}
/**
* Free a Page Table by physical address.
*
* @param pVM VM handle.
* @param HCPhysPT The physical address of the page table to be freed.
* @deprecated Use MMR3PageFreeByPhys().
*/
{
}
/**
* Convert a Page Table address to a HC physical address.
*
* @returns Physical address for the specified page table.
* @param pVM VM handle.
* @param pPT Page table which physical address we query.
* @deprecated Use MMR3Page2Phys().
*/
{
}
/**
* Convert a physical address to a page table address
*
* @returns Pointer to the page table at that physical address.
* @param pVM VM handle.
* @param PhysPT Page table which physical address we query.
* @deprecated Use MMR3PagePhys2Page().
*/
{
}
/**
* Allocate a Page Directory.
*
* @returns Pointer to the page directory.
* @returns NULL on failure.
* @param pVM VM handle.
* @deprecated Use MMR3PageAlloc().
*/
{
}
/**
* Free a Page Directory.
*
* @param pVM VM handle.
* @param pPD Pointer to the page directory allocated by MMR3PDAlloc().
* @deprecated Use MMR3PageFree().
*/
{
}
/**
* Convert a Page Directory address to a physical address.
*
* @returns Physical address for the specified page directory.
* @param pVM VM handle.
* @param pPD Page directory which physical address we query.
* Allocated by MMR3PDAlloc().
* @deprecated Use MMR3Page2Phys().
*/
{
}
/**
* Convert a physical address to a page directory address
*
* @returns Pointer to the page directory at that physical address.
* @param pVM VM handle.
* @param PhysPD Physical address of page directory.
* Allocated by MMR3PDAlloc().
* @deprecated Use MMR3PageAlloc().
*/
{
}
/** @deprecated */
/** @deprecated */
#endif /* will be removed */
/** @} */
/** @defgroup grp_mm_heap Heap Manager
* @ingroup grp_mm_r3
* @{ */
/**
* Allocate memory associating it with the VM for collective cleanup.
*
* The memory will be allocated from the default heap but a header
* is added in which we keep track of which VM it belongs to and chain
* all the allocations together so they can be freed in a one go.
*
* This interface is typically used for memory block which will not be
* freed during the life of the VM.
*
* @returns Pointer to allocated memory.
* @param pVM VM handle.
* @param enmTag Statistics tag. Statistics are collected on a per tag
* basis in addition to a global one. Thus we can easily
* identify how memory is used by the VM.
* @param cbSize Size of the block.
* @thread Any thread.
*/
/**
* Same as MMR3HeapAlloc().
*
*
* @returns Pointer to allocated memory.
* @param pVM VM handle.
* @param enmTag Statistics tag. Statistics are collected on a per tag
* basis in addition to a global one. Thus we can easily
* identify how memory is used by the VM.
* @param cbSize Size of the block.
* @param ppv Where to store the pointer to the allocated memory on success.
* @thread Any thread.
*/
/**
* Same as MMR3HeapAlloc() only the memory is zeroed.
*
*
* @returns Pointer to allocated memory.
* @param pVM VM handle.
* @param enmTag Statistics tag. Statistics are collected on a per tag
* basis in addition to a global one. Thus we can easily
* identify how memory is used by the VM.
* @param cbSize Size of the block.
* @thread Any thread.
*/
/**
* Same as MMR3HeapAllocZ().
*
*
* @returns Pointer to allocated memory.
* @param pVM VM handle.
* @param enmTag Statistics tag. Statistics are collected on a per tag
* basis in addition to a global one. Thus we can easily
* identify how memory is used by the VM.
* @param cbSize Size of the block.
* @param ppv Where to store the pointer to the allocated memory on success.
* @thread Any thread.
*/
/**
* Reallocate memory allocated with MMR3HeapAlloc() or MMR3HeapRealloc().
*
* @returns Pointer to reallocated memory.
* @param pv Pointer to the memory block to reallocate.
* Must not be NULL!
* @param cbNewSize New block size.
* @thread Any thread.
*/
/**
* Duplicates the specified string.
*
* @returns Pointer to the duplicate.
* @returns NULL on failure or when input NULL.
* @param pVM The VM handle.
* @param enmTag Statistics tag. Statistics are collected on a per tag
* basis in addition to a global one. Thus we can easily
* identify how memory is used by the VM.
* @param psz The string to duplicate. NULL is allowed.
*/
/**
* Releases memory allocated with MMR3HeapAlloc() or MMR3HeapRealloc().
*
* @param pv Pointer to the memory block to free.
* @thread Any thread.
*/
/** @} */
/** @} */
#endif
#ifdef IN_GC
/** @defgroup grp_mm_gc The MM Guest Context API
* @ingroup grp_mm
* @{
*/
/**
* Install MMGCRam Hypervisor page fault handler for normal working
* of MMGCRamRead and MMGCRamWrite calls.
* This handler will be automatically removed at page fault.
* In other case it must be removed by MMGCRamDeregisterTrapHandler call.
*
* @param pVM VM handle.
*/
/**
* Remove MMGCRam Hypervisor page fault handler.
* See description of MMGCRamRegisterTrapHandler call.
*
* @param pVM VM handle.
*/
/**
* Read data in guest context with \#PF control.
* MMRamGC page fault handler must be installed prior this call for safe operation.
* Use MMGCRamRegisterTrapHandler() call for this task.
*
* @returns VBox status.
* @param pDst Where to store the readed data.
* @param pSrc Pointer to the data to read.
* @param cb Size of data to read, only 1/2/4/8 is valid.
*/
/**
* Write data in guest context with \#PF control.
* MMRamGC page fault handler must be installed prior this call for safe operation.
* Use MMGCRamRegisterTrapHandler() call for this task.
*
* @returns VBox status.
* @param pDst Where to write the data.
* @param pSrc Pointer to the data to write.
* @param cb Size of data to write, only 1/2/4 is valid.
*/
/**
* Read data in guest context with \#PF control.
*
* @returns VBox status.
* @param pVM The VM handle.
* @param pDst Where to store the readed data.
* @param pSrc Pointer to the data to read.
* @param cb Size of data to read, only 1/2/4/8 is valid.
*/
/**
* Write data in guest context with \#PF control.
*
* @returns VBox status.
* @param pVM The VM handle.
* @param pDst Where to write the data.
* @param pSrc Pointer to the data to write.
* @param cb Size of data to write, only 1/2/4 is valid.
*/
/** @} */
#endif
/** @} */
#endif