2
* MM - The Memory Manager.
6
* Copyright (C) 2006-2007 innotek GmbH
8
* This file is part of VirtualBox Open Source Edition (OSE), as
9
* available from http://www.virtualbox.org. This file is free software;
10
* you can redistribute it and/or modify it under the terms of the GNU
11
* General Public License as published by the Free Software Foundation,
12
* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13
* distribution. VirtualBox OSE is distributed in the hope that it will
14
* be useful, but WITHOUT ANY WARRANTY of any kind.
20
#include <VBox/cdefs.h>
21
#include <VBox/types.h>
28
/** @defgroup grp_mm The Memory Manager API
32
/** @name RAM Page Flags
33
* Since internal ranges have a byte granularity it's possible for a
34
* page be flagged for several uses. The access virtualization in PGM
35
* will choose the most restricted one and use EM to emulate access to
36
* the less restricted areas of the page.
38
* Bits 0-11 only since they are fitted into the offset part of a physical memory address.
41
/** Reserved - Not RAM, ROM nor MMIO2.
42
* If this bit is cleared the memory is assumed to be some kind of RAM.
43
* Normal MMIO may set it but that depends on whether the RAM range was
44
* created specially for the MMIO or not.
46
* @remarks The current implementation will always reserve backing
47
* memory for reserved ranges to simplify things.
49
#define MM_RAM_FLAGS_RESERVED BIT(0)
50
/** ROM - Read Only Memory.
51
* The page have a HC physical address which contains the BIOS code. All write
52
* access is trapped and ignored.
54
* HACK: Writable shadow ROM is indicated by both ROM and MMIO2 being
55
* set. (We're out of bits.)
57
#define MM_RAM_FLAGS_ROM BIT(1)
58
/** MMIO - Memory Mapped I/O.
59
* All access is trapped and emulated. No physical backing is required, but
60
* might for various reasons be present.
62
#define MM_RAM_FLAGS_MMIO BIT(2)
63
/** MMIO2 - Memory Mapped I/O, variation 2.
64
* The virtualization is performed using real memory and only catching
65
* a few accesses for like keeping track for dirty pages.
66
* @remark Involved in the shadow ROM hack.
68
#define MM_RAM_FLAGS_MMIO2 BIT(3)
70
/** PGM has virtual page access handler(s) defined for pages with this flag. */
71
#define MM_RAM_FLAGS_VIRTUAL_HANDLER BIT(4)
72
/** PGM has virtual page access handler(s) for write access. */
73
#define MM_RAM_FLAGS_VIRTUAL_WRITE BIT(5)
74
/** PGM has virtual page access handler(s) for all access. */
75
#define MM_RAM_FLAGS_VIRTUAL_ALL BIT(6)
76
/** PGM has physical page access handler(s) defined for pages with this flag. */
77
#define MM_RAM_FLAGS_PHYSICAL_HANDLER BIT(7)
78
/** PGM has physical page access handler(s) for write access. */
79
#define MM_RAM_FLAGS_PHYSICAL_WRITE BIT(8)
80
/** PGM has physical page access handler(s) for all access. */
81
#define MM_RAM_FLAGS_PHYSICAL_ALL BIT(9)
82
/** PGM has physical page access handler(s) for this page and has temporarily disabled it. */
83
#define MM_RAM_FLAGS_PHYSICAL_TEMP_OFF BIT(10)
84
/** Physical backing memory is allocated dynamically. Not set implies a one time static allocation. */
85
#define MM_RAM_FLAGS_DYNAMIC_ALLOC BIT(11)
87
/** The shift used to get the reference count. */
88
#define MM_RAM_FLAGS_CREFS_SHIFT 62
89
/** The mask applied to the the page pool idx after using MM_RAM_FLAGS_CREFS_SHIFT to shift it down. */
90
#define MM_RAM_FLAGS_CREFS_MASK 0x3
91
/** The (shifted) cRef value used to indiciate that the idx is the head of a
92
* physical cross reference extent list. */
93
#define MM_RAM_FLAGS_CREFS_PHYSEXT MM_RAM_FLAGS_CREFS_MASK
94
/** The shift used to get the page pool idx. (Apply MM_RAM_FLAGS_IDX_MASK to the result when shifting down). */
95
#define MM_RAM_FLAGS_IDX_SHIFT 48
96
/** The mask applied to the the page pool idx after using MM_RAM_FLAGS_IDX_SHIFT to shift it down. */
97
#define MM_RAM_FLAGS_IDX_MASK 0x3fff
98
/** The idx value when we're out of of extents or there are simply too many mappings of this page. */
99
#define MM_RAM_FLAGS_IDX_OVERFLOWED MM_RAM_FLAGS_IDX_MASK
101
/** Mask for masking off any references to the page. */
102
#define MM_RAM_FLAGS_NO_REFS_MASK UINT64_C(0x0000ffffffffffff)
105
/** @name MMR3PhysRegisterEx registration type
110
/** Normal physical region (flags specify exact page type) */
111
MM_PHYS_TYPE_NORMAL = 0,
112
/** Allocate part of a dynamically allocated physical region */
113
MM_PHYS_TYPE_DYNALLOC_CHUNK,
115
MM_PHYS_TYPE_32BIT_HACK = 0x7fffffff
120
* Memory Allocation Tags.
121
* For use with MMHyperAlloc(), MMR3HeapAlloc(), MMR3HeapAllocEx(),
122
* MMR3HeapAllocZ() and MMR3HeapAllocZEx().
124
* @remark Don't forget to update the dump command in MMHeap.cpp!
141
MM_TAG_DBGF_LINE_DUP,
144
MM_TAG_DBGF_SYMBOL_DUP,
153
MM_TAG_MM_LOOKUP_GUEST,
154
MM_TAG_MM_LOOKUP_PHYS,
155
MM_TAG_MM_LOOKUP_VIRT,
163
MM_TAG_PDM_DEVICE_USER,
165
MM_TAG_PDM_DRIVER_USER,
193
MM_TAG_32BIT_HACK = 0x7fffffff
199
/** @defgroup grp_mm_hyper Hypervisor Memory Management
204
* Converts a ring-0 host context address in the Hypervisor memory region to a ring-3 host context address.
206
* @returns ring-3 host context address.
207
* @param pVM The VM to operate on.
208
* @param R0Ptr The ring-0 host context address.
209
* You'll be damned if this is not in the HMA! :-)
210
* @thread The Emulation Thread.
212
MMDECL(RTR3PTR) MMHyperR0ToR3(PVM pVM, RTR0PTR R0Ptr);
215
* Converts a ring-0 host context address in the Hypervisor memory region to a guest context address.
217
* @returns guest context address.
218
* @param pVM The VM to operate on.
219
* @param R0Ptr The ring-0 host context address.
220
* You'll be damned if this is not in the HMA! :-)
221
* @thread The Emulation Thread.
223
MMDECL(RTGCPTR) MMHyperR0ToGC(PVM pVM, RTR0PTR R0Ptr);
226
* Converts a ring-0 host context address in the Hypervisor memory region to a current context address.
228
* @returns current context address.
229
* @param pVM The VM to operate on.
230
* @param R0Ptr The ring-0 host context address.
231
* You'll be damned if this is not in the HMA! :-)
232
* @thread The Emulation Thread.
235
MMDECL(void *) MMHyperR0ToCC(PVM pVM, RTR0PTR R0Ptr);
240
* Converts a ring-3 host context address in the Hypervisor memory region to a ring-0 host context address.
242
* @returns ring-0 host context address.
243
* @param pVM The VM to operate on.
244
* @param R3Ptr The ring-3 host context address.
245
* You'll be damned if this is not in the HMA! :-)
246
* @thread The Emulation Thread.
248
MMDECL(RTR0PTR) MMHyperR3ToR0(PVM pVM, RTR3PTR R3Ptr);
251
* Converts a ring-3 host context address in the Hypervisor memory region to a guest context address.
253
* @returns guest context address.
254
* @param pVM The VM to operate on.
255
* @param R3Ptr The ring-3 host context address.
256
* You'll be damned if this is not in the HMA! :-)
257
* @thread The Emulation Thread.
259
MMDECL(RTGCPTR) MMHyperR3ToGC(PVM pVM, RTR3PTR R3Ptr);
262
* Converts a ring-3 host context address in the Hypervisor memory region to a current context address.
264
* @returns current context address.
265
* @param pVM The VM to operate on.
266
* @param R3Ptr The ring-3 host context address.
267
* You'll be damned if this is not in the HMA! :-)
268
* @thread The Emulation Thread.
271
MMDECL(void *) MMHyperR3ToCC(PVM pVM, RTR3PTR R3Ptr);
273
DECLINLINE(void *) MMHyperR3ToCC(PVM pVM, RTR3PTR R3Ptr)
282
* Converts a guest context address in the Hypervisor memory region to a ring-3 context address.
284
* @returns ring-3 host context address.
285
* @param pVM The VM to operate on.
286
* @param GCPtr The guest context address.
287
* You'll be damned if this is not in the HMA! :-)
288
* @thread The Emulation Thread.
290
MMDECL(RTR3PTR) MMHyperGCToR3(PVM pVM, RTGCPTR GCPtr);
293
* Converts a guest context address in the Hypervisor memory region to a ring-0 host context address.
295
* @returns ring-0 host context address.
296
* @param pVM The VM to operate on.
297
* @param GCPtr The guest context address.
298
* You'll be damned if this is not in the HMA! :-)
299
* @thread The Emulation Thread.
301
MMDECL(RTR0PTR) MMHyperGCToR0(PVM pVM, RTGCPTR GCPtr);
304
* Converts a guest context address in the Hypervisor memory region to a current context address.
306
* @returns current context address.
307
* @param pVM The VM to operate on.
308
* @param GCPtr The guest host context address.
309
* You'll be damned if this is not in the HMA! :-)
310
* @thread The Emulation Thread.
313
MMDECL(void *) MMHyperGCToCC(PVM pVM, RTGCPTR GCPtr);
315
DECLINLINE(void *) MMHyperGCToCC(PVM pVM, RTGCPTR GCPtr)
325
* Converts a current context address in the Hypervisor memory region to a ring-3 host context address.
327
* @returns ring-3 host context address.
328
* @param pVM The VM to operate on.
329
* @param pv The current context address.
330
* You'll be damned if this is not in the HMA! :-)
331
* @thread The Emulation Thread.
334
MMDECL(RTR3PTR) MMHyperCCToR3(PVM pVM, void *pv);
336
DECLINLINE(RTR3PTR) MMHyperCCToR3(PVM pVM, void *pv)
344
* Converts a current context address in the Hypervisor memory region to a ring-0 host context address.
346
* @returns ring-0 host context address.
347
* @param pVM The VM to operate on.
348
* @param pv The current context address.
349
* You'll be damned if this is not in the HMA! :-)
350
* @thread The Emulation Thread.
353
MMDECL(RTR0PTR) MMHyperCCToR0(PVM pVM, void *pv);
355
DECLINLINE(RTR0PTR) MMHyperCCToR0(PVM pVM, void *pv)
363
* Converts a current context address in the Hypervisor memory region to a guest context address.
365
* @returns guest context address.
366
* @param pVM The VM to operate on.
367
* @param pv The current context address.
368
* You'll be damned if this is not in the HMA! :-)
369
* @thread The Emulation Thread.
372
MMDECL(RTGCPTR) MMHyperCCToGC(PVM pVM, void *pv);
374
DECLINLINE(RTGCPTR) MMHyperCCToGC(PVM pVM, void *pv)
384
* Converts a current context address in the Hypervisor memory region to a HC address.
385
* The memory must have been allocated with MMHyperAlloc().
387
* @returns HC address.
388
* @param pVM The VM to operate on.
389
* @param Ptr The current context address.
390
* @thread The Emulation Thread.
394
MMDECL(RTHCPTR) MMHyper2HC(PVM pVM, uintptr_t Ptr);
396
DECLINLINE(RTHCPTR) MMHyper2HC(PVM pVM, uintptr_t Ptr)
404
* Converts a current context address in the Hypervisor memory region to a GC address.
405
* The memory must have been allocated with MMHyperAlloc().
407
* @returns HC address.
408
* @param pVM The VM to operate on.
409
* @param Ptr The current context address.
410
* @thread The Emulation Thread.
413
MMDECL(RTGCPTR) MMHyper2GC(PVM pVM, uintptr_t Ptr);
415
DECLINLINE(RTGCPTR) MMHyper2GC(PVM pVM, uintptr_t Ptr)
423
* Converts a HC address in the Hypervisor memory region to a GC address.
424
* The memory must have been allocated with MMGCHyperAlloc() or MMR3HyperAlloc().
426
* @returns GC address.
427
* @param pVM The VM to operate on.
428
* @param HCPtr The host context address.
429
* You'll be damned if this is not in the HMA! :-)
430
* @thread The Emulation Thread.
433
MMDECL(RTGCPTR) MMHyperHC2GC(PVM pVM, RTHCPTR HCPtr);
436
* Converts a GC address in the Hypervisor memory region to a HC address.
437
* The memory must have been allocated with MMGCHyperAlloc() or MMR3HyperAlloc().
439
* @returns HC address.
440
* @param pVM The VM to operate on.
441
* @param GCPtr The guest context address.
442
* You'll be damned if this is not in the HMA! :-)
443
* @thread The Emulation Thread.
446
MMDECL(RTHCPTR) MMHyperGC2HC(PVM pVM, RTGCPTR GCPtr);
450
* Allocates memory in the Hypervisor (GC VMM) area.
451
* The returned memory is of course zeroed.
453
* @returns VBox status code.
454
* @param pVM The VM to operate on.
455
* @param cb Number of bytes to allocate.
456
* @param uAlignment Required memory alignment in bytes.
457
* Values are 0,8,16,32 and PAGE_SIZE.
458
* 0 -> default alignment, i.e. 8 bytes.
459
* @param enmTag The statistics tag.
460
* @param ppv Where to store the address to the allocated
462
* @remark This is assumed not to be used at times when serialization is required.
464
MMDECL(int) MMHyperAlloc(PVM pVM, size_t cb, uint32_t uAlignment, MMTAG enmTag, void **ppv);
467
* Free memory allocated using MMHyperAlloc().
469
* It's not possible to free memory which is page aligned!
471
* @returns VBox status code.
472
* @param pVM The VM to operate on.
473
* @param pv The memory to free.
474
* @remark Try avoid freeing hyper memory.
475
* @thread The Emulation Thread.
477
MMDECL(int) MMHyperFree(PVM pVM, void *pv);
481
* Dumps the hypervisor heap to Log.
482
* @param pVM VM Handle.
483
* @thread The Emulation Thread.
485
MMDECL(void) MMHyperHeapDump(PVM pVM);
489
* Query the amount of free memory in the hypervisor heap.
491
* @returns Number of free bytes in the hypervisor heap.
494
MMDECL(size_t) MMHyperHeapGetFreeSize(PVM pVM);
497
* Query the size the hypervisor heap.
499
* @returns The size of the hypervisor heap in bytes.
502
MMDECL(size_t) MMHyperHeapGetSize(PVM pVM);
506
* Query the address and size the hypervisor memory area.
508
* @returns Base address of the hypervisor area.
509
* @param pVM VM Handle.
510
* @param pcb Where to store the size of the hypervisor area. (out)
513
MMDECL(RTGCPTR) MMHyperGetArea(PVM pVM, size_t *pcb);
516
* Checks if an address is within the hypervisor memory area.
518
* @returns true if inside.
519
* @returns false if outside.
520
* @param pVM VM handle.
521
* @param GCPtr The pointer to check.
522
* @thread The Emulation Thread.
524
MMDECL(bool) MMHyperIsInsideArea(PVM pVM, RTGCPTR GCPtr);
527
* Convert a page in the page pool to a HC physical address.
528
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
529
* and MMR3PageAllocLow().
531
* @returns Physical address for the specified page table.
532
* @param pVM VM handle.
533
* @param pvPage Page which physical address we query.
534
* @thread The Emulation Thread.
536
MMDECL(RTHCPHYS) MMPage2Phys(PVM pVM, void *pvPage);
539
* Convert physical address of a page to a HC virtual address.
540
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
541
* and MMR3PageAllocLow().
543
* @returns Pointer to the page at that physical address.
544
* @param pVM VM handle.
545
* @param HCPhysPage The physical address of a page.
546
* @thread The Emulation Thread.
548
MMDECL(void *) MMPagePhys2Page(PVM pVM, RTHCPHYS HCPhysPage);
552
* Convert physical address of a page to a HC virtual address.
553
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
554
* and MMR3PageAllocLow().
556
* @returns VBox status code.
557
* @param pVM VM handle.
558
* @param HCPhysPage The physical address of a page.
559
* @param ppvPage Where to store the address corresponding to HCPhysPage.
560
* @thread The Emulation Thread.
562
MMDECL(int) MMPagePhys2PageEx(PVM pVM, RTHCPHYS HCPhysPage, void **ppvPage);
566
* Try convert physical address of a page to a HC virtual address.
567
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
568
* and MMR3PageAllocLow().
570
* @returns VBox status code.
571
* @param pVM VM handle.
572
* @param HCPhysPage The physical address of a page.
573
* @param ppvPage Where to store the address corresponding to HCPhysPage.
574
* @thread The Emulation Thread.
576
MMDECL(int) MMPagePhys2PageTry(PVM pVM, RTHCPHYS HCPhysPage, void **ppvPage);
579
* Convert GC physical address to HC virtual address.
581
* @returns HC virtual address.
582
* @param pVM VM Handle
583
* @param GCPhys Guest context physical address.
584
* @param cbRange Physical range
585
* @thread The Emulation Thread.
588
MMDECL(void *) MMPhysGCPhys2HCVirt(PVM pVM, RTGCPHYS GCPhys, RTUINT cbRange);
591
* Convert GC virtual address to HC virtual address.
593
* This uses the current PD of the guest.
595
* @returns HC virtual address.
596
* @param pVM VM Handle
597
* @param GCPtr Guest context virtual address.
598
* @thread The Emulation Thread.
601
MMDECL(void *) MMPhysGCVirt2HCVirt(PVM pVM, RTGCPTR pvGC);
604
/** @def MMHYPER_GC_ASSERT_GCPTR
605
* Asserts that an address is either NULL or inside the hypervisor memory area.
606
* This assertion only works while IN_GC, it's a NOP everywhere else.
607
* @thread The Emulation Thread.
610
# define MMHYPER_GC_ASSERT_GCPTR(pVM, GCPtr) Assert(MMHyperIsInsideArea((pVM), (GCPtr)) || !(GCPtr))
612
# define MMHYPER_GC_ASSERT_GCPTR(pVM, GCPtr) do { } while (0)
619
/** @defgroup grp_mm_r3 The MM Host Context Ring-3 API
625
* Initialization of MM (save anything depending on PGM).
627
* @returns VBox status code.
628
* @param pVM The VM to operate on.
629
* @thread The Emulation Thread.
631
MMR3DECL(int) MMR3Init(PVM pVM);
634
* Initializes the MM parts which depends on PGM being initialized.
636
* @returns VBox status code.
637
* @param pVM The VM to operate on.
638
* @thread The Emulation Thread.
640
MMR3DECL(int) MMR3InitPaging(PVM pVM);
643
* Finalizes the HMA mapping.
645
* This is called later during init, most (all) HMA allocations should be done
646
* by the time this function is called.
648
* @returns VBox status.
650
MMR3DECL(int) MMR3HyperInitFinalize(PVM pVM);
655
* Termination means cleaning up and freeing all resources,
656
* the VM it self is at this point powered off or suspended.
658
* @returns VBox status code.
659
* @param pVM The VM to operate on.
660
* @thread The Emulation Thread.
662
MMR3DECL(int) MMR3Term(PVM pVM);
665
* Reset notification.
667
* MM will reload shadow ROMs into RAM at this point and make
670
* @param pVM The VM handle.
672
MMR3DECL(void) MMR3Reset(PVM pVM);
675
* Convert HC Physical address to HC Virtual address.
677
* @returns VBox status.
678
* @param pVM VM handle.
679
* @param HCPhys The host context virtual address.
680
* @param ppv Where to store the resulting address.
681
* @thread The Emulation Thread.
683
MMR3DECL(int) MMR3HCPhys2HCVirt(PVM pVM, RTHCPHYS HCPhys, void **ppv);
686
* Read memory from GC virtual address using the current guest CR3.
688
* @returns VBox status.
689
* @param pVM VM handle.
690
* @param pvDst Destination address (HC of course).
691
* @param GCPtr GC virtual address.
692
* @param cb Number of bytes to read.
693
* @thread The Emulation Thread.
695
MMR3DECL(int) MMR3ReadGCVirt(PVM pVM, void *pvDst, RTGCPTR GCPtr, size_t cb);
698
* Write to memory at GC virtual address translated using the current guest CR3.
700
* @returns VBox status.
701
* @param pVM VM handle.
702
* @param GCPtrDst GC virtual address.
703
* @param pvSrc The source address (HC of course).
704
* @param cb Number of bytes to read.
706
MMR3DECL(int) MMR3WriteGCVirt(PVM pVM, RTGCPTR GCPtrDst, const void *pvSrc, size_t cb);
709
/** @defgroup grp_mm_r3_hyper Hypervisor Memory Manager (HC R3 Portion)
713
* Allocates memory in the Hypervisor (GC VMM) area which never will
714
* be freed and don't have any offset based relation to other heap blocks.
716
* The latter means that two blocks allocated by this API will not have the
717
* same relative position to each other in GC and HC. In short, never use
718
* this API for allocating nodes for an offset based AVL tree!
720
* The returned memory is of course zeroed.
722
* @returns VBox status code.
723
* @param pVM The VM to operate on.
724
* @param cb Number of bytes to allocate.
725
* @param uAlignment Required memory alignment in bytes.
726
* Values are 0,8,16,32 and PAGE_SIZE.
727
* 0 -> default alignment, i.e. 8 bytes.
728
* @param enmTag The statistics tag.
729
* @param ppv Where to store the address to the allocated
731
* @remark This is assumed not to be used at times when serialization is required.
733
MMDECL(int) MMR3HyperAllocOnceNoRel(PVM pVM, size_t cb, uint32_t uAlignment, MMTAG enmTag, void **ppv);
736
* Maps contiguous HC physical memory into the hypervisor region in the GC.
738
* @return VBox status code.
740
* @param pVM VM handle.
741
* @param pvHC Host context address of the memory. Must be page aligned!
742
* @param HCPhys Host context physical address of the memory to be mapped. Must be page aligned!
743
* @param cb Size of the memory. Will be rounded up to nearest page.
744
* @param pszDesc Description.
745
* @param pGCPtr Where to store the GC address.
746
* @thread The Emulation Thread.
748
MMR3DECL(int) MMR3HyperMapHCPhys(PVM pVM, void *pvHC, RTHCPHYS HCPhys, size_t cb, const char *pszDesc, PRTGCPTR pGCPtr);
751
* Maps contiguous GC physical memory into the hypervisor region in the GC.
753
* @return VBox status code.
755
* @param pVM VM handle.
756
* @param GCPhys Guest context physical address of the memory to be mapped. Must be page aligned!
757
* @param cb Size of the memory. Will be rounded up to nearest page.
758
* @param pszDesc Mapping description.
759
* @param pGCPtr Where to store the GC address.
760
* @thread The Emulation Thread.
762
MMR3DECL(int) MMR3HyperMapGCPhys(PVM pVM, RTGCPHYS GCPhys, size_t cb, const char *pszDesc, PRTGCPTR pGCPtr);
765
* Locks and Maps HC virtual memory into the hypervisor region in the GC.
767
* @return VBox status code.
769
* @param pVM VM handle.
770
* @param pvHC Host context address of the memory (may be not page aligned).
771
* @param cb Size of the memory. Will be rounded up to nearest page.
772
* @param fFree Set this if MM is responsible for freeing the memory using SUPPageFree.
773
* @param pszDesc Mapping description.
774
* @param pGCPtr Where to store the GC address corresponding to pvHC.
775
* @thread The Emulation Thread.
777
MMR3DECL(int) MMR3HyperMapHCRam(PVM pVM, void *pvHC, size_t cb, bool fFree, const char *pszDesc, PRTGCPTR pGCPtr);
780
* Maps locked R3 virtual memory into the hypervisor region in the GC.
782
* @return VBox status code.
784
* @param pVM VM handle.
785
* @param pvR3 The ring-3 address of the memory, must be page aligned.
786
* @param pvR0 The ring-0 address of the memory, must be page aligned. (optional)
787
* @param cPages The number of pages.
788
* @param paPages The page descriptors.
789
* @param pszDesc Mapping description.
790
* @param pGCPtr Where to store the GC address corresponding to pvHC.
792
MMR3DECL(int) MMR3HyperMapPages(PVM pVM, void *pvR3, RTR0PTR pvR0, size_t cPages, PCSUPPAGE paPages, const char *pszDesc, PRTGCPTR pGCPtr);
795
* Reserves a hypervisor memory area.
796
* Most frequent usage is fence pages and dynamically mappings like the guest PD and PDPTR.
798
* @return VBox status code.
800
* @param pVM VM handle.
801
* @param cb Size of the memory. Will be rounded up to nearest page.
802
* @param pszDesc Mapping description.
803
* @param pGCPtr Where to store the assigned GC address. Optional.
804
* @thread The Emulation Thread.
806
MMR3DECL(int) MMR3HyperReserve(PVM pVM, unsigned cb, const char *pszDesc, PRTGCPTR pGCPtr);
810
* Convert hypervisor HC virtual address to HC physical address.
812
* @returns HC physical address.
813
* @param pVM VM Handle
814
* @param pvHC Host context physical address.
815
* @thread The Emulation Thread.
817
MMR3DECL(RTHCPHYS) MMR3HyperHCVirt2HCPhys(PVM pVM, void *pvHC);
819
* Convert hypervisor HC virtual address to HC physical address.
821
* @returns HC physical address.
822
* @param pVM VM Handle
823
* @param pvHC Host context physical address.
824
* @param pHCPhys Where to store the HC physical address.
825
* @thread The Emulation Thread.
827
MMR3DECL(int) MMR3HyperHCVirt2HCPhysEx(PVM pVM, void *pvHC, PRTHCPHYS pHCPhys);
829
* Convert hypervisor HC physical address to HC virtual address.
831
* @returns HC virtual address.
832
* @param pVM VM Handle
833
* @param HCPhys Host context physical address.
834
* @thread The Emulation Thread.
836
MMR3DECL(void *) MMR3HyperHCPhys2HCVirt(PVM pVM, RTHCPHYS HCPhys);
838
* Convert hypervisor HC physical address to HC virtual address.
840
* @returns VBox status.
841
* @param pVM VM Handle
842
* @param HCPhys Host context physical address.
843
* @param ppv Where to store the HC virtual address.
844
* @thread The Emulation Thread.
846
MMR3DECL(int) MMR3HyperHCPhys2HCVirtEx(PVM pVM, RTHCPHYS HCPhys, void **ppv);
849
* Read hypervisor memory from GC virtual address.
851
* @returns VBox status.
852
* @param pVM VM handle.
853
* @param pvDst Destination address (HC of course).
854
* @param GCPtr GC virtual address.
855
* @param cb Number of bytes to read.
856
* @thread The Emulation Thread.
858
MMR3DECL(int) MMR3HyperReadGCVirt(PVM pVM, void *pvDst, RTGCPTR GCPtr, size_t cb);
863
/** @defgroup grp_mm_phys Guest Physical Memory Manager
868
* Register externally allocated RAM for the virtual machine.
870
* The memory registered with the VM thru this interface must not be freed
871
* before the virtual machine has been destroyed. Bad things may happen... :-)
873
* @return VBox status code.
874
* @param pVM VM handle.
875
* @param pvRam Virtual address of the guest's physical memory range Must be page aligned.
876
* @param GCPhys The physical address the ram shall be registered at.
877
* @param cb Size of the memory. Must be page aligend.
878
* @param fFlags Flags of the MM_RAM_FLAGS_* defines.
879
* @param pszDesc Description of the memory.
880
* @thread The Emulation Thread.
882
MMR3DECL(int) MMR3PhysRegister(PVM pVM, void *pvRam, RTGCPHYS GCPhys, unsigned cb, unsigned fFlags, const char *pszDesc);
885
* Register externally allocated RAM for the virtual machine.
887
* The memory registered with the VM thru this interface must not be freed
888
* before the virtual machine has been destroyed. Bad things may happen... :-)
890
* @return VBox status code.
891
* @param pVM VM handle.
892
* @param pvRam Virtual address of the guest's physical memory range Must be page aligned.
893
* @param GCPhys The physical address the ram shall be registered at.
894
* @param cb Size of the memory. Must be page aligend.
895
* @param fFlags Flags of the MM_RAM_FLAGS_* defines.
896
* @param enmType Physical range type (MM_PHYS_TYPE_*)
897
* @param pszDesc Description of the memory.
898
* @thread The Emulation Thread.
899
* @todo update this description.
901
MMR3DECL(int) MMR3PhysRegisterEx(PVM pVM, void *pvRam, RTGCPHYS GCPhys, unsigned cb, unsigned fFlags, MMPHYSREG enmType, const char *pszDesc);
904
* Register previously registered externally allocated RAM for the virtual machine.
906
* Use this only for MMIO ranges or the guest will become very confused.
907
* The memory registered with the VM thru this interface must not be freed
908
* before the virtual machine has been destroyed. Bad things may happen... :-)
910
* @return VBox status code.
911
* @param pVM VM handle.
912
* @param GCPhysOld The physical address the ram was registered at.
913
* @param GCPhysNew The physical address the ram shall be registered at.
914
* @param cb Size of the memory. Must be page aligend.
915
* @thread The Emulation Thread.
917
MMR3DECL(int) MMR3PhysRelocate(PVM pVM, RTGCPHYS GCPhysOld, RTGCPHYS GCPhysNew, unsigned cb);
920
* Register a ROM (BIOS) region.
922
* It goes without saying that this is read-only memory. The memory region must be
923
* in unassigned memory. I.e. from the top of the address space or on the PC in
924
* the 0xa0000-0xfffff range.
926
* @returns VBox status.
927
* @param pVM VM Handle.
928
* @param pDevIns The device instance owning the ROM region.
929
* @param GCPhys First physical address in the range.
930
* Must be page aligned!
931
* @param cbRange The size of the range (in bytes).
932
* Must be page aligned!
933
* @param pvBinary Pointer to the binary data backing the ROM image.
934
* This must be cbRange bytes big.
935
* It will be copied and doesn't have to stick around.
936
* It will be copied and doesn't have to stick around if fShadow is clear.
937
* @param fShadow Whether to emulate ROM shadowing. This involves leaving
938
* the ROM writable for a while during the POST and refreshing
939
* it at reset. When this flag is set, the memory pointed to by
940
* pvBinary has to stick around for the lifespan of the VM.
941
* @param pszDesc Pointer to description string. This must not be freed.
942
* @remark There is no way to remove the rom, automatically on device cleanup or
943
* manually from the device yet. At present I doubt we need such features...
944
* @thread The Emulation Thread.
946
MMR3DECL(int) MMR3PhysRomRegister(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const void *pvBinary, bool fShadow, const char *pszDesc);
949
* Write-protects a shadow ROM range.
951
* This is called late in the POST for shadow ROM ranges.
953
* @returns VBox status code.
954
* @param pVM The VM handle.
955
* @param GCPhys Start of the registered shadow ROM range
956
* @param cbRange The length of the registered shadow ROM range.
957
* This can be NULL (not sure about the BIOS interface yet).
959
MMR3DECL(int) MMR3PhysRomProtect(PVM pVM, RTGCPHYS GCPhys, RTUINT cbRange);
962
* Reserve physical address space for ROM and MMIO ranges.
964
* @returns VBox status code.
965
* @param pVM VM Handle.
966
* @param GCPhys Start physical address.
967
* @param cbRange The size of the range.
968
* @param pszDesc Description string.
969
* @thread The Emulation Thread.
971
MMR3DECL(int) MMR3PhysReserve(PVM pVM, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc);
974
* Get the size of the base RAM.
975
* This usually means the size of the first contigous block of physical memory.
981
MMR3DECL(uint64_t) MMR3PhysGetRamSize(PVM pVM);
987
/** @defgroup grp_mm_page Physical Page Pool
991
* Allocates a page from the page pool.
993
* This function may returns pages which has physical addresses any
994
* where. If you require a page to be within the first 4GB of physical
995
* memory, use MMR3PageAllocLow().
997
* @returns Pointer to the allocated page page.
998
* @returns NULL on failure.
999
* @param pVM VM handle.
1000
* @thread The Emulation Thread.
1002
MMR3DECL(void *) MMR3PageAlloc(PVM pVM);
1005
* Allocates a page from the page pool and return its physical address.
1007
* This function may returns pages which has physical addresses any
1008
* where. If you require a page to be within the first 4GB of physical
1009
* memory, use MMR3PageAllocLow().
1011
* @returns Pointer to the allocated page page.
1012
* @returns NIL_RTHCPHYS on failure.
1013
* @param pVM VM handle.
1014
* @thread The Emulation Thread.
1016
MMR3DECL(RTHCPHYS) MMR3PageAllocPhys(PVM pVM);
1019
* Frees a page allocated from the page pool by MMR3PageAlloc() and MMR3PageAllocPhys().
1021
* @param pVM VM handle.
1022
* @param pvPage Pointer to the page.
1023
* @thread The Emulation Thread.
1025
MMR3DECL(void) MMR3PageFree(PVM pVM, void *pvPage);
1028
* Allocates a page from the low page pool.
1030
* @returns Pointer to the allocated page.
1031
* @returns NULL on failure.
1032
* @param pVM VM handle.
1033
* @thread The Emulation Thread.
1035
MMR3DECL(void *) MMR3PageAllocLow(PVM pVM);
1038
* Frees a page allocated from the page pool by MMR3PageAllocLow().
1040
* @param pVM VM handle.
1041
* @param pvPage Pointer to the page.
1042
* @thread The Emulation Thread.
1044
MMR3DECL(void) MMR3PageFreeLow(PVM pVM, void *pvPage);
1047
* Free a page allocated from the page pool by physical address.
1048
* This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
1049
* and MMR3PageAllocLow().
1051
* @param pVM VM handle.
1052
* @param HCPhysPage The physical address of the page to be freed.
1053
* @thread The Emulation Thread.
1055
MMR3DECL(void) MMR3PageFreeByPhys(PVM pVM, RTHCPHYS HCPhysPage);
1058
* Gets the HC pointer to the dummy page.
1060
* The dummy page is used as a place holder to prevent potential bugs
1061
* from doing really bad things to the system.
1063
* @returns Pointer to the dummy page.
1064
* @param pVM VM handle.
1065
* @thread The Emulation Thread.
1067
MMR3DECL(void *) MMR3PageDummyHCPtr(PVM pVM);
1070
* Gets the HC Phys to the dummy page.
1072
* The dummy page is used as a place holder to prevent potential bugs
1073
* from doing really bad things to the system.
1075
* @returns Pointer to the dummy page.
1076
* @param pVM VM handle.
1077
* @thread The Emulation Thread.
1079
MMR3DECL(RTHCPHYS) MMR3PageDummyHCPhys(PVM pVM);
1082
#if 1 /* these are temporary wrappers and will be removed soon */
1084
* Allocates a Page Table.
1086
* @returns Pointer to page table.
1087
* @returns NULL on failure.
1088
* @param pVM VM handle.
1089
* @deprecated Use MMR3PageAlloc().
1091
DECLINLINE(PVBOXPT) MMR3PTAlloc(PVM pVM)
1093
return (PVBOXPT)MMR3PageAlloc(pVM);
1097
* Free a Page Table.
1099
* @param pVM VM handle.
1100
* @param pPT Pointer to the page table as returned by MMR3PTAlloc().
1101
* @deprecated Use MMR3PageFree().
1103
DECLINLINE(void) MMR3PTFree(PVM pVM, PVBOXPT pPT)
1105
MMR3PageFree(pVM, pPT);
1109
* Free a Page Table by physical address.
1111
* @param pVM VM handle.
1112
* @param HCPhysPT The physical address of the page table to be freed.
1113
* @deprecated Use MMR3PageFreeByPhys().
1115
DECLINLINE(void) MMR3PTFreeByPhys(PVM pVM, RTHCPHYS HCPhysPT)
1117
MMR3PageFreeByPhys(pVM, HCPhysPT);
1121
* Convert a Page Table address to a HC physical address.
1123
* @returns Physical address for the specified page table.
1124
* @param pVM VM handle.
1125
* @param pPT Page table which physical address we query.
1126
* @deprecated Use MMR3Page2Phys().
1128
DECLINLINE(RTHCPHYS) MMR3PT2Phys(PVM pVM, PVBOXPT pPT)
1130
return MMPage2Phys(pVM, pPT);
1134
* Convert a physical address to a page table address
1136
* @returns Pointer to the page table at that physical address.
1137
* @param pVM VM handle.
1138
* @param PhysPT Page table which physical address we query.
1139
* @deprecated Use MMR3PagePhys2Page().
1141
DECLINLINE(PVBOXPT) MMR3Phys2PT(PVM pVM, RTHCPHYS PhysPT)
1143
return (PVBOXPT)MMPagePhys2Page(pVM, PhysPT);
1147
* Allocate a Page Directory.
1149
* @returns Pointer to the page directory.
1150
* @returns NULL on failure.
1151
* @param pVM VM handle.
1152
* @deprecated Use MMR3PageAlloc().
1154
DECLINLINE(PVBOXPD) MMR3PDAlloc(PVM pVM)
1156
return (PVBOXPD)MMR3PageAlloc(pVM);
1160
* Free a Page Directory.
1162
* @param pVM VM handle.
1163
* @param pPD Pointer to the page directory allocated by MMR3PDAlloc().
1164
* @deprecated Use MMR3PageFree().
1166
DECLINLINE(void) MMR3PDFree(PVM pVM, PVBOXPD pPD)
1168
MMR3PageFree(pVM, pPD);
1172
* Convert a Page Directory address to a physical address.
1174
* @returns Physical address for the specified page directory.
1175
* @param pVM VM handle.
1176
* @param pPD Page directory which physical address we query.
1177
* Allocated by MMR3PDAlloc().
1178
* @deprecated Use MMR3Page2Phys().
1180
DECLINLINE(RTHCPHYS) MMR3PD2Phys(PVM pVM, PVBOXPD pPD)
1182
return MMPage2Phys(pVM, pPD);
1186
* Convert a physical address to a page directory address
1188
* @returns Pointer to the page directory at that physical address.
1189
* @param pVM VM handle.
1190
* @param PhysPD Physical address of page directory.
1191
* Allocated by MMR3PDAlloc().
1192
* @deprecated Use MMR3PageAlloc().
1194
DECLINLINE(PVBOXPD) MMR3Phys2PD(PVM pVM, RTHCPHYS PhysPD)
1196
return (PVBOXPD)MMPagePhys2Page(pVM, PhysPD);
1200
DECLINLINE(void *) MMR3DummyPageHCPtr(PVM pVM) { return MMR3PageDummyHCPtr(pVM); }
1202
DECLINLINE(RTHCPHYS) MMR3DummyPageHCPhys(PVM pVM) { return MMR3PageDummyHCPhys(pVM); }
1204
#endif /* will be removed */
1209
/** @defgroup grp_mm_heap Heap Manager
1210
* @ingroup grp_mm_r3
1214
* Allocate memory associating it with the VM for collective cleanup.
1216
* The memory will be allocated from the default heap but a header
1217
* is added in which we keep track of which VM it belongs to and chain
1218
* all the allocations together so they can be freed in a one go.
1220
* This interface is typically used for memory block which will not be
1221
* freed during the life of the VM.
1223
* @returns Pointer to allocated memory.
1224
* @param pVM VM handle.
1225
* @param enmTag Statistics tag. Statistics are collected on a per tag
1226
* basis in addition to a global one. Thus we can easily
1227
* identify how memory is used by the VM.
1228
* @param cbSize Size of the block.
1229
* @thread Any thread.
1231
MMR3DECL(void *) MMR3HeapAlloc(PVM pVM, MMTAG enmTag, size_t cbSize);
1234
* Same as MMR3HeapAlloc().
1237
* @returns Pointer to allocated memory.
1238
* @param pVM VM handle.
1239
* @param enmTag Statistics tag. Statistics are collected on a per tag
1240
* basis in addition to a global one. Thus we can easily
1241
* identify how memory is used by the VM.
1242
* @param cbSize Size of the block.
1243
* @param ppv Where to store the pointer to the allocated memory on success.
1244
* @thread Any thread.
1246
MMR3DECL(int) MMR3HeapAllocEx(PVM pVM, MMTAG enmTag, size_t cbSize, void **ppv);
1249
* Same as MMR3HeapAlloc() only the memory is zeroed.
1252
* @returns Pointer to allocated memory.
1253
* @param pVM VM handle.
1254
* @param enmTag Statistics tag. Statistics are collected on a per tag
1255
* basis in addition to a global one. Thus we can easily
1256
* identify how memory is used by the VM.
1257
* @param cbSize Size of the block.
1258
* @thread Any thread.
1260
MMR3DECL(void *) MMR3HeapAllocZ(PVM pVM, MMTAG enmTag, size_t cbSize);
1263
* Same as MMR3HeapAllocZ().
1266
* @returns Pointer to allocated memory.
1267
* @param pVM VM handle.
1268
* @param enmTag Statistics tag. Statistics are collected on a per tag
1269
* basis in addition to a global one. Thus we can easily
1270
* identify how memory is used by the VM.
1271
* @param cbSize Size of the block.
1272
* @param ppv Where to store the pointer to the allocated memory on success.
1273
* @thread Any thread.
1275
MMR3DECL(int) MMR3HeapAllocZEx(PVM pVM, MMTAG enmTag, size_t cbSize, void **ppv);
1278
* Reallocate memory allocated with MMR3HeapAlloc() or MMR3HeapRealloc().
1280
* @returns Pointer to reallocated memory.
1281
* @param pv Pointer to the memory block to reallocate.
1283
* @param cbNewSize New block size.
1284
* @thread Any thread.
1286
MMR3DECL(void *) MMR3HeapRealloc(void *pv, size_t cbNewSize);
1289
* Duplicates the specified string.
1291
* @returns Pointer to the duplicate.
1292
* @returns NULL on failure or when input NULL.
1293
* @param pVM The VM handle.
1294
* @param enmTag Statistics tag. Statistics are collected on a per tag
1295
* basis in addition to a global one. Thus we can easily
1296
* identify how memory is used by the VM.
1297
* @param psz The string to duplicate. NULL is allowed.
1299
MMR3DECL(char *) MMR3HeapStrDup(PVM pVM, MMTAG enmTag, const char *psz);
1302
* Releases memory allocated with MMR3HeapAlloc() or MMR3HeapRealloc().
1304
* @param pv Pointer to the memory block to free.
1305
* @thread Any thread.
1307
MMR3DECL(void) MMR3HeapFree(void *pv);
1317
/** @defgroup grp_mm_gc The MM Guest Context API
1323
* Install MMGCRam Hypervisor page fault handler for normal working
1324
* of MMGCRamRead and MMGCRamWrite calls.
1325
* This handler will be automatically removed at page fault.
1326
* In other case it must be removed by MMGCRamDeregisterTrapHandler call.
1328
* @param pVM VM handle.
1330
MMGCDECL(void) MMGCRamRegisterTrapHandler(PVM pVM);
1333
* Remove MMGCRam Hypervisor page fault handler.
1334
* See description of MMGCRamRegisterTrapHandler call.
1336
* @param pVM VM handle.
1338
MMGCDECL(void) MMGCRamDeregisterTrapHandler(PVM pVM);
1341
* Read data in guest context with \#PF control.
1342
* MMRamGC page fault handler must be installed prior this call for safe operation.
1343
* Use MMGCRamRegisterTrapHandler() call for this task.
1345
* @returns VBox status.
1346
* @param pDst Where to store the readed data.
1347
* @param pSrc Pointer to the data to read.
1348
* @param cb Size of data to read, only 1/2/4/8 is valid.
1350
MMGCDECL(int) MMGCRamReadNoTrapHandler(void *pDst, void *pSrc, size_t cb);
1353
* Write data in guest context with \#PF control.
1354
* MMRamGC page fault handler must be installed prior this call for safe operation.
1355
* Use MMGCRamRegisterTrapHandler() call for this task.
1357
* @returns VBox status.
1358
* @param pDst Where to write the data.
1359
* @param pSrc Pointer to the data to write.
1360
* @param cb Size of data to write, only 1/2/4 is valid.
1362
MMGCDECL(int) MMGCRamWriteNoTrapHandler(void *pDst, void *pSrc, size_t cb);
1365
* Read data in guest context with \#PF control.
1367
* @returns VBox status.
1368
* @param pVM The VM handle.
1369
* @param pDst Where to store the readed data.
1370
* @param pSrc Pointer to the data to read.
1371
* @param cb Size of data to read, only 1/2/4/8 is valid.
1373
MMGCDECL(int) MMGCRamRead(PVM pVM, void *pDst, void *pSrc, size_t cb);
1376
* Write data in guest context with \#PF control.
1378
* @returns VBox status.
1379
* @param pVM The VM handle.
1380
* @param pDst Where to write the data.
1381
* @param pSrc Pointer to the data to write.
1382
* @param cb Size of data to write, only 1/2/4 is valid.
1384
MMGCDECL(int) MMGCRamWrite(PVM pVM, void *pDst, void *pSrc, size_t cb);
added
removed
include/VBox/mm.h
