VirtualBox

source: vbox/trunk/include/VBox/mm.h@ 3643

Last change on this file since 3643 was 3632, checked in by vboxsync, 17 years ago

VBox_hdr_h -> _VBox_hdr_h

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 42.8 KB
Line 
1/** @file
2 * MM - The Memory Manager.
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
7 *
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.
15 *
16 * If you received this file as part of a commercial VirtualBox
17 * distribution, then only the terms of your commercial VirtualBox
18 * license agreement apply instead of the previous paragraph.
19 */
20
21#ifndef ___VBox_mm_h
22#define ___VBox_mm_h
23
24#include <VBox/cdefs.h>
25#include <VBox/types.h>
26#include <VBox/x86.h>
27#include <VBox/sup.h>
28
29
30__BEGIN_DECLS
31
32/** @defgroup grp_mm The Memory Manager API
33 * @{
34 */
35
36/** @name RAM Page Flags
37 * Since internal ranges have a byte granularity it's possible for a
38 * page be flagged for several uses. The access virtualization in PGM
39 * will choose the most restricted one and use EM to emulate access to
40 * the less restricted areas of the page.
41 *
42 * Bits 0-11 only since they are fitted into the offset part of a physical memory address.
43 * @{
44 */
45/** Reserved - No RAM, but can be used for MMIO or ROM.
46 * If this bit is cleared the memory is assumed to be some kind of RAM.
47 * MMIO2 will for instance not set this flag, neither will ROM (wrong it's set :/). Normal MMIO
48 * may set it but that depends on whether the RAM range was created specially
49 * for the MMIO or not.
50 * N.B. The current implementation will always reserve backing memory for reserved
51 * ranges to simplify things.
52 */
53#define MM_RAM_FLAGS_RESERVED BIT(0)
54/** ROM - Read Only Memory.
55 * The page have a HC physical address which contains the BIOS code. All write
56 * access is trapped and ignored.
57 */
58#define MM_RAM_FLAGS_ROM BIT(1)
59/** MMIO - Memory Mapped I/O.
60 * All access is trapped and emulated. No physical backing is required, but
61 * might for various reasons be present.
62 */
63#define MM_RAM_FLAGS_MMIO BIT(2)
64/** MMIO2 - Memory Mapped I/O, variation 2.
65 * The virtualization is performed using real memory and only catching
66 * a few accesses for like keeping track for dirty pages.
67 */
68#define MM_RAM_FLAGS_MMIO2 BIT(3)
69
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)
86
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
100
101/** Mask for masking off any references to the page. */
102#define MM_RAM_FLAGS_NO_REFS_MASK UINT64_C(0x0000ffffffffffff)
103/** @} */
104
105/** @name MMR3PhysRegisterEx registration type
106 * @{
107 */
108typedef enum
109{
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,
114
115 MM_PHYS_TYPE_32BIT_HACK = 0x7fffffff
116} MMPHYSREG;
117/** @} */
118
119/**
120 * Memory Allocation Tags.
121 * For use with MMHyperAlloc(), MMR3HeapAlloc(), MMR3HeapAllocEx(),
122 * MMR3HeapAllocZ() and MMR3HeapAllocZEx().
123 *
124 * @remark Don't forget to update the dump command in MMHeap.cpp!
125 */
126typedef enum MMTAG
127{
128 MM_TAG_INVALID = 0,
129
130 MM_TAG_CFGM,
131 MM_TAG_CFGM_BYTES,
132 MM_TAG_CFGM_STRING,
133 MM_TAG_CFGM_USER,
134
135 MM_TAG_CSAM,
136 MM_TAG_CSAM_PATCH,
137
138 MM_TAG_DBGF,
139 MM_TAG_DBGF_INFO,
140 MM_TAG_DBGF_LINE,
141 MM_TAG_DBGF_LINE_DUP,
142 MM_TAG_DBGF_STACK,
143 MM_TAG_DBGF_SYMBOL,
144 MM_TAG_DBGF_SYMBOL_DUP,
145 MM_TAG_DBGF_MODULE,
146
147 MM_TAG_EM,
148
149 MM_TAG_IOM,
150 MM_TAG_IOM_STATS,
151
152 MM_TAG_MM,
153 MM_TAG_MM_LOOKUP_GUEST,
154 MM_TAG_MM_LOOKUP_PHYS,
155 MM_TAG_MM_LOOKUP_VIRT,
156 MM_TAG_MM_PAGE,
157
158 MM_TAG_PATM,
159 MM_TAG_PATM_PATCH,
160
161 MM_TAG_PDM,
162 MM_TAG_PDM_DEVICE,
163 MM_TAG_PDM_DEVICE_USER,
164 MM_TAG_PDM_DRIVER,
165 MM_TAG_PDM_DRIVER_USER,
166 MM_TAG_PDM_LUN,
167 MM_TAG_PDM_QUEUE,
168 MM_TAG_PDM_THREAD,
169
170 MM_TAG_PGM,
171 MM_TAG_PGM_HANDLERS,
172 MM_TAG_PGM_POOL,
173
174 MM_TAG_REM,
175
176 MM_TAG_SELM,
177
178 MM_TAG_SSM,
179
180 MM_TAG_STAM,
181
182 MM_TAG_TM,
183
184 MM_TAG_TRPM,
185
186 MM_TAG_VM,
187 MM_TAG_VM_REQ,
188
189 MM_TAG_VMM,
190
191 MM_TAG_HWACCM,
192
193 MM_TAG_32BIT_HACK = 0x7fffffff
194} MMTAG;
195
196
197
198
199/** @defgroup grp_mm_hyper Hypervisor Memory Management
200 * @ingroup grp_mm
201 * @{ */
202
203/**
204 * Converts a ring-0 host context address in the Hypervisor memory region to a ring-3 host context address.
205 *
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.
211 */
212MMDECL(RTR3PTR) MMHyperR0ToR3(PVM pVM, RTR0PTR R0Ptr);
213
214/**
215 * Converts a ring-0 host context address in the Hypervisor memory region to a guest context address.
216 *
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.
222 */
223MMDECL(RTGCPTR) MMHyperR0ToGC(PVM pVM, RTR0PTR R0Ptr);
224
225/**
226 * Converts a ring-0 host context address in the Hypervisor memory region to a current context address.
227 *
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.
233 */
234#ifndef IN_RING0
235MMDECL(void *) MMHyperR0ToCC(PVM pVM, RTR0PTR R0Ptr);
236#endif
237
238
239/**
240 * Converts a ring-3 host context address in the Hypervisor memory region to a ring-0 host context address.
241 *
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.
247 */
248MMDECL(RTR0PTR) MMHyperR3ToR0(PVM pVM, RTR3PTR R3Ptr);
249
250/**
251 * Converts a ring-3 host context address in the Hypervisor memory region to a guest context address.
252 *
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.
258 */
259MMDECL(RTGCPTR) MMHyperR3ToGC(PVM pVM, RTR3PTR R3Ptr);
260
261/**
262 * Converts a ring-3 host context address in the Hypervisor memory region to a current context address.
263 *
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.
269 */
270#ifndef IN_RING3
271MMDECL(void *) MMHyperR3ToCC(PVM pVM, RTR3PTR R3Ptr);
272#else
273DECLINLINE(void *) MMHyperR3ToCC(PVM pVM, RTR3PTR R3Ptr)
274{
275 NOREF(pVM);
276 return R3Ptr;
277}
278#endif
279
280
281/**
282 * Converts a guest context address in the Hypervisor memory region to a ring-3 context address.
283 *
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.
289 */
290MMDECL(RTR3PTR) MMHyperGCToR3(PVM pVM, RTGCPTR GCPtr);
291
292/**
293 * Converts a guest context address in the Hypervisor memory region to a ring-0 host context address.
294 *
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.
300 */
301MMDECL(RTR0PTR) MMHyperGCToR0(PVM pVM, RTGCPTR GCPtr);
302
303/**
304 * Converts a guest context address in the Hypervisor memory region to a current context address.
305 *
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.
311 */
312#ifndef IN_GC
313MMDECL(void *) MMHyperGCToCC(PVM pVM, RTGCPTR GCPtr);
314#else
315DECLINLINE(void *) MMHyperGCToCC(PVM pVM, RTGCPTR GCPtr)
316{
317 NOREF(pVM);
318 return GCPtr;
319}
320#endif
321
322
323
324/**
325 * Converts a current context address in the Hypervisor memory region to a ring-3 host context address.
326 *
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.
332 */
333#ifndef IN_RING3
334MMDECL(RTR3PTR) MMHyperCCToR3(PVM pVM, void *pv);
335#else
336DECLINLINE(RTR3PTR) MMHyperCCToR3(PVM pVM, void *pv)
337{
338 NOREF(pVM);
339 return pv;
340}
341#endif
342
343/**
344 * Converts a current context address in the Hypervisor memory region to a ring-0 host context address.
345 *
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.
351 */
352#ifndef IN_RING0
353MMDECL(RTR0PTR) MMHyperCCToR0(PVM pVM, void *pv);
354#else
355DECLINLINE(RTR0PTR) MMHyperCCToR0(PVM pVM, void *pv)
356{
357 NOREF(pVM);
358 return pv;
359}
360#endif
361
362/**
363 * Converts a current context address in the Hypervisor memory region to a guest context address.
364 *
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.
370 */
371#ifndef IN_GC
372MMDECL(RTGCPTR) MMHyperCCToGC(PVM pVM, void *pv);
373#else
374DECLINLINE(RTGCPTR) MMHyperCCToGC(PVM pVM, void *pv)
375{
376 NOREF(pVM);
377 return pv;
378}
379#endif
380
381
382
383/**
384 * Converts a current context address in the Hypervisor memory region to a HC address.
385 * The memory must have been allocated with MMHyperAlloc().
386 *
387 * @returns HC address.
388 * @param pVM The VM to operate on.
389 * @param Ptr The current context address.
390 * @thread The Emulation Thread.
391 * @deprecated
392 */
393#ifdef IN_GC
394MMDECL(RTHCPTR) MMHyper2HC(PVM pVM, uintptr_t Ptr);
395#else
396DECLINLINE(RTHCPTR) MMHyper2HC(PVM pVM, uintptr_t Ptr)
397{
398 NOREF(pVM);
399 return (RTHCPTR)Ptr;
400}
401#endif
402
403/**
404 * Converts a current context address in the Hypervisor memory region to a GC address.
405 * The memory must have been allocated with MMHyperAlloc().
406 *
407 * @returns HC address.
408 * @param pVM The VM to operate on.
409 * @param Ptr The current context address.
410 * @thread The Emulation Thread.
411 */
412#ifndef IN_GC
413MMDECL(RTGCPTR) MMHyper2GC(PVM pVM, uintptr_t Ptr);
414#else
415DECLINLINE(RTGCPTR) MMHyper2GC(PVM pVM, uintptr_t Ptr)
416{
417 NOREF(pVM);
418 return (RTGCPTR)Ptr;
419}
420#endif
421
422/**
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().
425 *
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.
431 * @deprecated
432 */
433MMDECL(RTGCPTR) MMHyperHC2GC(PVM pVM, RTHCPTR HCPtr);
434
435/**
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().
438 *
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.
444 * @deprecated
445 */
446MMDECL(RTHCPTR) MMHyperGC2HC(PVM pVM, RTGCPTR GCPtr);
447
448
449/**
450 * Allocates memory in the Hypervisor (GC VMM) area.
451 * The returned memory is of course zeroed.
452 *
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
461 * memory.
462 * @remark This is assumed not to be used at times when serialization is required.
463 */
464MMDECL(int) MMHyperAlloc(PVM pVM, size_t cb, uint32_t uAlignment, MMTAG enmTag, void **ppv);
465
466/**
467 * Free memory allocated using MMHyperAlloc().
468 *
469 * It's not possible to free memory which is page aligned!
470 *
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.
476 */
477MMDECL(int) MMHyperFree(PVM pVM, void *pv);
478
479#ifdef DEBUG
480/**
481 * Dumps the hypervisor heap to Log.
482 * @param pVM VM Handle.
483 * @thread The Emulation Thread.
484 */
485MMDECL(void) MMHyperHeapDump(PVM pVM);
486#endif
487
488/**
489 * Query the amount of free memory in the hypervisor heap.
490 *
491 * @returns Number of free bytes in the hypervisor heap.
492 * @thread Any.
493 */
494MMDECL(size_t) MMHyperHeapGetFreeSize(PVM pVM);
495
496/**
497 * Query the size the hypervisor heap.
498 *
499 * @returns The size of the hypervisor heap in bytes.
500 * @thread Any.
501 */
502MMDECL(size_t) MMHyperHeapGetSize(PVM pVM);
503
504
505/**
506 * Query the address and size the hypervisor memory area.
507 *
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)
511 * @thread Any.
512 */
513MMDECL(RTGCPTR) MMHyperGetArea(PVM pVM, size_t *pcb);
514
515/**
516 * Checks if an address is within the hypervisor memory area.
517 *
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.
523 */
524MMDECL(bool) MMHyperIsInsideArea(PVM pVM, RTGCPTR GCPtr);
525
526/**
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().
530 *
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.
535 */
536MMDECL(RTHCPHYS) MMPage2Phys(PVM pVM, void *pvPage);
537
538/**
539 * Convert physical address of a page to a HC virtual address.
540 * This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
541 * and MMR3PageAllocLow().
542 *
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.
547 */
548MMDECL(void *) MMPagePhys2Page(PVM pVM, RTHCPHYS HCPhysPage);
549
550
551/**
552 * Convert physical address of a page to a HC virtual address.
553 * This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
554 * and MMR3PageAllocLow().
555 *
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.
561 */
562MMDECL(int) MMPagePhys2PageEx(PVM pVM, RTHCPHYS HCPhysPage, void **ppvPage);
563
564
565/**
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().
569 *
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.
575 */
576MMDECL(int) MMPagePhys2PageTry(PVM pVM, RTHCPHYS HCPhysPage, void **ppvPage);
577
578/**
579 * Convert GC physical address to HC virtual address.
580 *
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.
586 * @deprecated
587 */
588MMDECL(void *) MMPhysGCPhys2HCVirt(PVM pVM, RTGCPHYS GCPhys, RTUINT cbRange);
589
590/**
591 * Convert GC virtual address to HC virtual address.
592 *
593 * This uses the current PD of the guest.
594 *
595 * @returns HC virtual address.
596 * @param pVM VM Handle
597 * @param GCPtr Guest context virtual address.
598 * @thread The Emulation Thread.
599 * @deprecated
600 */
601MMDECL(void *) MMPhysGCVirt2HCVirt(PVM pVM, RTGCPTR pvGC);
602
603
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.
608 */
609#ifdef IN_GC
610# define MMHYPER_GC_ASSERT_GCPTR(pVM, GCPtr) Assert(MMHyperIsInsideArea((pVM), (GCPtr)) || !(GCPtr))
611#else
612# define MMHYPER_GC_ASSERT_GCPTR(pVM, GCPtr) do { } while (0)
613#endif
614
615/** @} */
616
617
618#ifdef IN_RING3
619/** @defgroup grp_mm_r3 The MM Host Context Ring-3 API
620 * @ingroup grp_mm
621 * @{
622 */
623
624/**
625 * Initialization of MM (save anything depending on PGM).
626 *
627 * @returns VBox status code.
628 * @param pVM The VM to operate on.
629 * @thread The Emulation Thread.
630 */
631MMR3DECL(int) MMR3Init(PVM pVM);
632
633/**
634 * Initializes the MM parts which depends on PGM being initialized.
635 *
636 * @returns VBox status code.
637 * @param pVM The VM to operate on.
638 * @thread The Emulation Thread.
639 */
640MMR3DECL(int) MMR3InitPaging(PVM pVM);
641
642/**
643 * Finalizes the HMA mapping.
644 *
645 * This is called later during init, most (all) HMA allocations should be done
646 * by the time this function is called.
647 *
648 * @returns VBox status.
649 */
650MMR3DECL(int) MMR3HyperInitFinalize(PVM pVM);
651
652/**
653 * Terminates the MM.
654 *
655 * Termination means cleaning up and freeing all resources,
656 * the VM it self is at this point powered off or suspended.
657 *
658 * @returns VBox status code.
659 * @param pVM The VM to operate on.
660 * @thread The Emulation Thread.
661 */
662MMR3DECL(int) MMR3Term(PVM pVM);
663
664/**
665 * Convert HC Physical address to HC Virtual address.
666 *
667 * @returns VBox status.
668 * @param pVM VM handle.
669 * @param HCPhys The host context virtual address.
670 * @param ppv Where to store the resulting address.
671 * @thread The Emulation Thread.
672 */
673MMR3DECL(int) MMR3HCPhys2HCVirt(PVM pVM, RTHCPHYS HCPhys, void **ppv);
674
675/**
676 * Read memory from GC virtual address using the current guest CR3.
677 *
678 * @returns VBox status.
679 * @param pVM VM handle.
680 * @param pvDst Destination address (HC of course).
681 * @param GCPtr GC virtual address.
682 * @param cb Number of bytes to read.
683 * @thread The Emulation Thread.
684 */
685MMR3DECL(int) MMR3ReadGCVirt(PVM pVM, void *pvDst, RTGCPTR GCPtr, size_t cb);
686
687/**
688 * Write to memory at GC virtual address translated using the current guest CR3.
689 *
690 * @returns VBox status.
691 * @param pVM VM handle.
692 * @param GCPtrDst GC virtual address.
693 * @param pvSrc The source address (HC of course).
694 * @param cb Number of bytes to read.
695 */
696MMR3DECL(int) MMR3WriteGCVirt(PVM pVM, RTGCPTR GCPtrDst, const void *pvSrc, size_t cb);
697
698
699/** @defgroup grp_mm_r3_hyper Hypervisor Memory Manager (HC R3 Portion)
700 * @ingroup grp_mm_r3
701 * @{ */
702/**
703 * Allocates memory in the Hypervisor (GC VMM) area which never will
704 * be freed and don't have any offset based relation to other heap blocks.
705 *
706 * The latter means that two blocks allocated by this API will not have the
707 * same relative position to each other in GC and HC. In short, never use
708 * this API for allocating nodes for an offset based AVL tree!
709 *
710 * The returned memory is of course zeroed.
711 *
712 * @returns VBox status code.
713 * @param pVM The VM to operate on.
714 * @param cb Number of bytes to allocate.
715 * @param uAlignment Required memory alignment in bytes.
716 * Values are 0,8,16,32 and PAGE_SIZE.
717 * 0 -> default alignment, i.e. 8 bytes.
718 * @param enmTag The statistics tag.
719 * @param ppv Where to store the address to the allocated
720 * memory.
721 * @remark This is assumed not to be used at times when serialization is required.
722 */
723MMDECL(int) MMR3HyperAllocOnceNoRel(PVM pVM, size_t cb, uint32_t uAlignment, MMTAG enmTag, void **ppv);
724
725/**
726 * Maps contiguous HC physical memory into the hypervisor region in the GC.
727 *
728 * @return VBox status code.
729 *
730 * @param pVM VM handle.
731 * @param pvHC Host context address of the memory. Must be page aligned!
732 * @param HCPhys Host context physical address of the memory to be mapped. Must be page aligned!
733 * @param cb Size of the memory. Will be rounded up to nearest page.
734 * @param pszDesc Description.
735 * @param pGCPtr Where to store the GC address.
736 * @thread The Emulation Thread.
737 */
738MMR3DECL(int) MMR3HyperMapHCPhys(PVM pVM, void *pvHC, RTHCPHYS HCPhys, size_t cb, const char *pszDesc, PRTGCPTR pGCPtr);
739
740/**
741 * Maps contiguous GC physical memory into the hypervisor region in the GC.
742 *
743 * @return VBox status code.
744 *
745 * @param pVM VM handle.
746 * @param GCPhys Guest context physical address of the memory to be mapped. Must be page aligned!
747 * @param cb Size of the memory. Will be rounded up to nearest page.
748 * @param pszDesc Mapping description.
749 * @param pGCPtr Where to store the GC address.
750 * @thread The Emulation Thread.
751 */
752MMR3DECL(int) MMR3HyperMapGCPhys(PVM pVM, RTGCPHYS GCPhys, size_t cb, const char *pszDesc, PRTGCPTR pGCPtr);
753
754/**
755 * Locks and Maps HC virtual memory into the hypervisor region in the GC.
756 *
757 * @return VBox status code.
758 *
759 * @param pVM VM handle.
760 * @param pvHC Host context address of the memory (may be not page aligned).
761 * @param cb Size of the memory. Will be rounded up to nearest page.
762 * @param fFree Set this if MM is responsible for freeing the memory using SUPPageFree.
763 * @param pszDesc Mapping description.
764 * @param pGCPtr Where to store the GC address corresponding to pvHC.
765 * @thread The Emulation Thread.
766 */
767MMR3DECL(int) MMR3HyperMapHCRam(PVM pVM, void *pvHC, size_t cb, bool fFree, const char *pszDesc, PRTGCPTR pGCPtr);
768
769/**
770 * Maps locked R3 virtual memory into the hypervisor region in the GC.
771 *
772 * @return VBox status code.
773 *
774 * @param pVM VM handle.
775 * @param pvR3 The ring-3 address of the memory, must be page aligned.
776 * @param pvR0 The ring-0 address of the memory, must be page aligned. (optional)
777 * @param cPages The number of pages.
778 * @param paPages The page descriptors.
779 * @param pszDesc Mapping description.
780 * @param pGCPtr Where to store the GC address corresponding to pvHC.
781 */
782MMR3DECL(int) MMR3HyperMapPages(PVM pVM, void *pvR3, RTR0PTR pvR0, size_t cPages, PCSUPPAGE paPages, const char *pszDesc, PRTGCPTR pGCPtr);
783
784/**
785 * Reserves a hypervisor memory area.
786 * Most frequent usage is fence pages and dynamically mappings like the guest PD and PDPTR.
787 *
788 * @return VBox status code.
789 *
790 * @param pVM VM handle.
791 * @param cb Size of the memory. Will be rounded up to nearest page.
792 * @param pszDesc Mapping description.
793 * @param pGCPtr Where to store the assigned GC address. Optional.
794 * @thread The Emulation Thread.
795 */
796MMR3DECL(int) MMR3HyperReserve(PVM pVM, unsigned cb, const char *pszDesc, PRTGCPTR pGCPtr);
797
798
799/**
800 * Convert hypervisor HC virtual address to HC physical address.
801 *
802 * @returns HC physical address.
803 * @param pVM VM Handle
804 * @param pvHC Host context physical address.
805 * @thread The Emulation Thread.
806 */
807MMR3DECL(RTHCPHYS) MMR3HyperHCVirt2HCPhys(PVM pVM, void *pvHC);
808/**
809 * Convert hypervisor HC virtual address to HC physical address.
810 *
811 * @returns HC physical address.
812 * @param pVM VM Handle
813 * @param pvHC Host context physical address.
814 * @param pHCPhys Where to store the HC physical address.
815 * @thread The Emulation Thread.
816 */
817MMR3DECL(int) MMR3HyperHCVirt2HCPhysEx(PVM pVM, void *pvHC, PRTHCPHYS pHCPhys);
818/**
819 * Convert hypervisor HC physical address to HC virtual address.
820 *
821 * @returns HC virtual address.
822 * @param pVM VM Handle
823 * @param HCPhys Host context physical address.
824 * @thread The Emulation Thread.
825 */
826MMR3DECL(void *) MMR3HyperHCPhys2HCVirt(PVM pVM, RTHCPHYS HCPhys);
827/**
828 * Convert hypervisor HC physical address to HC virtual address.
829 *
830 * @returns VBox status.
831 * @param pVM VM Handle
832 * @param HCPhys Host context physical address.
833 * @param ppv Where to store the HC virtual address.
834 * @thread The Emulation Thread.
835 */
836MMR3DECL(int) MMR3HyperHCPhys2HCVirtEx(PVM pVM, RTHCPHYS HCPhys, void **ppv);
837
838/**
839 * Read hypervisor memory from GC virtual address.
840 *
841 * @returns VBox status.
842 * @param pVM VM handle.
843 * @param pvDst Destination address (HC of course).
844 * @param GCPtr GC virtual address.
845 * @param cb Number of bytes to read.
846 * @thread The Emulation Thread.
847 */
848MMR3DECL(int) MMR3HyperReadGCVirt(PVM pVM, void *pvDst, RTGCPTR GCPtr, size_t cb);
849
850/** @} */
851
852
853/** @defgroup grp_mm_phys Guest Physical Memory Manager
854 * @ingroup grp_mm_r3
855 * @{ */
856
857/**
858 * Register externally allocated RAM for the virtual machine.
859 *
860 * The memory registered with the VM thru this interface must not be freed
861 * before the virtual machine has been destroyed. Bad things may happen... :-)
862 *
863 * @return VBox status code.
864 * @param pVM VM handle.
865 * @param pvRam Virtual address of the guest's physical memory range Must be page aligned.
866 * @param GCPhys The physical address the ram shall be registered at.
867 * @param cb Size of the memory. Must be page aligend.
868 * @param fFlags Flags of the MM_RAM_FLAGS_* defines.
869 * @param pszDesc Description of the memory.
870 * @thread The Emulation Thread.
871 */
872MMR3DECL(int) MMR3PhysRegister(PVM pVM, void *pvRam, RTGCPHYS GCPhys, unsigned cb, unsigned fFlags, const char *pszDesc);
873
874/**
875 * Register externally allocated RAM for the virtual machine.
876 *
877 * The memory registered with the VM thru this interface must not be freed
878 * before the virtual machine has been destroyed. Bad things may happen... :-)
879 *
880 * @return VBox status code.
881 * @param pVM VM handle.
882 * @param pvRam Virtual address of the guest's physical memory range Must be page aligned.
883 * @param GCPhys The physical address the ram shall be registered at.
884 * @param cb Size of the memory. Must be page aligend.
885 * @param fFlags Flags of the MM_RAM_FLAGS_* defines.
886 * @param enmType Physical range type (MM_PHYS_TYPE_*)
887 * @param pszDesc Description of the memory.
888 * @thread The Emulation Thread.
889 * @todo update this description.
890 */
891MMR3DECL(int) MMR3PhysRegisterEx(PVM pVM, void *pvRam, RTGCPHYS GCPhys, unsigned cb, unsigned fFlags, MMPHYSREG enmType, const char *pszDesc);
892
893/**
894 * Register previously registered externally allocated RAM for the virtual machine.
895 *
896 * Use this only for MMIO ranges or the guest will become very confused.
897 * The memory registered with the VM thru this interface must not be freed
898 * before the virtual machine has been destroyed. Bad things may happen... :-)
899 *
900 * @return VBox status code.
901 * @param pVM VM handle.
902 * @param GCPhysOld The physical address the ram was registered at.
903 * @param GCPhysNew The physical address the ram shall be registered at.
904 * @param cb Size of the memory. Must be page aligend.
905 * @thread The Emulation Thread.
906 */
907MMR3DECL(int) MMR3PhysRelocate(PVM pVM, RTGCPHYS GCPhysOld, RTGCPHYS GCPhysNew, unsigned cb);
908
909/**
910 * Register a ROM (BIOS) region.
911 *
912 * It goes without saying that this is read-only memory. The memory region must be
913 * in unassigned memory. I.e. from the top of the address space or on the PC in
914 * the 0xa0000-0xfffff range.
915 *
916 * @returns VBox status.
917 * @param pVM VM Handle.
918 * @param pDevIns The device instance owning the ROM region.
919 * @param GCPhys First physical address in the range.
920 * Must be page aligned!
921 * @param cbRange The size of the range (in bytes).
922 * Must be page aligned!
923 * @param pvBinary Pointer to the binary data backing the ROM image.
924 * This must be cbRange bytes big.
925 * It will be copied and doesn't have to stick around.
926 * @param pszDesc Pointer to description string. This must not be freed.
927 * @remark There is no way to remove the rom, automatically on device cleanup or
928 * manually from the device yet. At present I doubt we need such features...
929 * @thread The Emulation Thread.
930 */
931MMR3DECL(int) MMR3PhysRomRegister(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const void *pvBinary, const char *pszDesc);
932
933/**
934 * Reserve physical address space for ROM and MMIO ranges.
935 *
936 * @returns VBox status code.
937 * @param pVM VM Handle.
938 * @param GCPhys Start physical address.
939 * @param cbRange The size of the range.
940 * @param pszDesc Description string.
941 * @thread The Emulation Thread.
942 */
943MMR3DECL(int) MMR3PhysReserve(PVM pVM, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc);
944
945/**
946 * Get the size of the base RAM.
947 * This usually means the size of the first contigous block of physical memory.
948 *
949 * @returns
950 * @param pVM
951 * @thread Any.
952 */
953MMR3DECL(uint64_t) MMR3PhysGetRamSize(PVM pVM);
954
955
956/** @} */
957
958
959/** @defgroup grp_mm_page Physical Page Pool
960 * @ingroup grp_mm_r3
961 * @{ */
962/**
963 * Allocates a page from the page pool.
964 *
965 * This function may returns pages which has physical addresses any
966 * where. If you require a page to be within the first 4GB of physical
967 * memory, use MMR3PageAllocLow().
968 *
969 * @returns Pointer to the allocated page page.
970 * @returns NULL on failure.
971 * @param pVM VM handle.
972 * @thread The Emulation Thread.
973 */
974MMR3DECL(void *) MMR3PageAlloc(PVM pVM);
975
976/**
977 * Allocates a page from the page pool and return its physical address.
978 *
979 * This function may returns pages which has physical addresses any
980 * where. If you require a page to be within the first 4GB of physical
981 * memory, use MMR3PageAllocLow().
982 *
983 * @returns Pointer to the allocated page page.
984 * @returns NIL_RTHCPHYS on failure.
985 * @param pVM VM handle.
986 * @thread The Emulation Thread.
987 */
988MMR3DECL(RTHCPHYS) MMR3PageAllocPhys(PVM pVM);
989
990/**
991 * Frees a page allocated from the page pool by MMR3PageAlloc() and MMR3PageAllocPhys().
992 *
993 * @param pVM VM handle.
994 * @param pvPage Pointer to the page.
995 * @thread The Emulation Thread.
996 */
997MMR3DECL(void) MMR3PageFree(PVM pVM, void *pvPage);
998
999/**
1000 * Allocates a page from the low page pool.
1001 *
1002 * @returns Pointer to the allocated page.
1003 * @returns NULL on failure.
1004 * @param pVM VM handle.
1005 * @thread The Emulation Thread.
1006 */
1007MMR3DECL(void *) MMR3PageAllocLow(PVM pVM);
1008
1009/**
1010 * Frees a page allocated from the page pool by MMR3PageAllocLow().
1011 *
1012 * @param pVM VM handle.
1013 * @param pvPage Pointer to the page.
1014 * @thread The Emulation Thread.
1015 */
1016MMR3DECL(void) MMR3PageFreeLow(PVM pVM, void *pvPage);
1017
1018/**
1019 * Free a page allocated from the page pool by physical address.
1020 * This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
1021 * and MMR3PageAllocLow().
1022 *
1023 * @param pVM VM handle.
1024 * @param HCPhysPage The physical address of the page to be freed.
1025 * @thread The Emulation Thread.
1026 */
1027MMR3DECL(void) MMR3PageFreeByPhys(PVM pVM, RTHCPHYS HCPhysPage);
1028
1029/**
1030 * Gets the HC pointer to the dummy page.
1031 *
1032 * The dummy page is used as a place holder to prevent potential bugs
1033 * from doing really bad things to the system.
1034 *
1035 * @returns Pointer to the dummy page.
1036 * @param pVM VM handle.
1037 * @thread The Emulation Thread.
1038 */
1039MMR3DECL(void *) MMR3PageDummyHCPtr(PVM pVM);
1040
1041/**
1042 * Gets the HC Phys to the dummy page.
1043 *
1044 * The dummy page is used as a place holder to prevent potential bugs
1045 * from doing really bad things to the system.
1046 *
1047 * @returns Pointer to the dummy page.
1048 * @param pVM VM handle.
1049 * @thread The Emulation Thread.
1050 */
1051MMR3DECL(RTHCPHYS) MMR3PageDummyHCPhys(PVM pVM);
1052
1053
1054#if 1 /* these are temporary wrappers and will be removed soon */
1055/**
1056 * Allocates a Page Table.
1057 *
1058 * @returns Pointer to page table.
1059 * @returns NULL on failure.
1060 * @param pVM VM handle.
1061 * @deprecated Use MMR3PageAlloc().
1062 */
1063DECLINLINE(PVBOXPT) MMR3PTAlloc(PVM pVM)
1064{
1065 return (PVBOXPT)MMR3PageAlloc(pVM);
1066}
1067
1068/**
1069 * Free a Page Table.
1070 *
1071 * @param pVM VM handle.
1072 * @param pPT Pointer to the page table as returned by MMR3PTAlloc().
1073 * @deprecated Use MMR3PageFree().
1074 */
1075DECLINLINE(void) MMR3PTFree(PVM pVM, PVBOXPT pPT)
1076{
1077 MMR3PageFree(pVM, pPT);
1078}
1079
1080/**
1081 * Free a Page Table by physical address.
1082 *
1083 * @param pVM VM handle.
1084 * @param HCPhysPT The physical address of the page table to be freed.
1085 * @deprecated Use MMR3PageFreeByPhys().
1086 */
1087DECLINLINE(void) MMR3PTFreeByPhys(PVM pVM, RTHCPHYS HCPhysPT)
1088{
1089 MMR3PageFreeByPhys(pVM, HCPhysPT);
1090}
1091
1092/**
1093 * Convert a Page Table address to a HC physical address.
1094 *
1095 * @returns Physical address for the specified page table.
1096 * @param pVM VM handle.
1097 * @param pPT Page table which physical address we query.
1098 * @deprecated Use MMR3Page2Phys().
1099 */
1100DECLINLINE(RTHCPHYS) MMR3PT2Phys(PVM pVM, PVBOXPT pPT)
1101{
1102 return MMPage2Phys(pVM, pPT);
1103}
1104
1105/**
1106 * Convert a physical address to a page table address
1107 *
1108 * @returns Pointer to the page table at that physical address.
1109 * @param pVM VM handle.
1110 * @param PhysPT Page table which physical address we query.
1111 * @deprecated Use MMR3PagePhys2Page().
1112 */
1113DECLINLINE(PVBOXPT) MMR3Phys2PT(PVM pVM, RTHCPHYS PhysPT)
1114{
1115 return (PVBOXPT)MMPagePhys2Page(pVM, PhysPT);
1116}
1117
1118/**
1119 * Allocate a Page Directory.
1120 *
1121 * @returns Pointer to the page directory.
1122 * @returns NULL on failure.
1123 * @param pVM VM handle.
1124 * @deprecated Use MMR3PageAlloc().
1125 */
1126DECLINLINE(PVBOXPD) MMR3PDAlloc(PVM pVM)
1127{
1128 return (PVBOXPD)MMR3PageAlloc(pVM);
1129}
1130
1131/**
1132 * Free a Page Directory.
1133 *
1134 * @param pVM VM handle.
1135 * @param pPD Pointer to the page directory allocated by MMR3PDAlloc().
1136 * @deprecated Use MMR3PageFree().
1137 */
1138DECLINLINE(void) MMR3PDFree(PVM pVM, PVBOXPD pPD)
1139{
1140 MMR3PageFree(pVM, pPD);
1141}
1142
1143/**
1144 * Convert a Page Directory address to a physical address.
1145 *
1146 * @returns Physical address for the specified page directory.
1147 * @param pVM VM handle.
1148 * @param pPD Page directory which physical address we query.
1149 * Allocated by MMR3PDAlloc().
1150 * @deprecated Use MMR3Page2Phys().
1151 */
1152DECLINLINE(RTHCPHYS) MMR3PD2Phys(PVM pVM, PVBOXPD pPD)
1153{
1154 return MMPage2Phys(pVM, pPD);
1155}
1156
1157/**
1158 * Convert a physical address to a page directory address
1159 *
1160 * @returns Pointer to the page directory at that physical address.
1161 * @param pVM VM handle.
1162 * @param PhysPD Physical address of page directory.
1163 * Allocated by MMR3PDAlloc().
1164 * @deprecated Use MMR3PageAlloc().
1165 */
1166DECLINLINE(PVBOXPD) MMR3Phys2PD(PVM pVM, RTHCPHYS PhysPD)
1167{
1168 return (PVBOXPD)MMPagePhys2Page(pVM, PhysPD);
1169}
1170
1171/** @deprecated */
1172DECLINLINE(void *) MMR3DummyPageHCPtr(PVM pVM) { return MMR3PageDummyHCPtr(pVM); }
1173/** @deprecated */
1174DECLINLINE(RTHCPHYS) MMR3DummyPageHCPhys(PVM pVM) { return MMR3PageDummyHCPhys(pVM); }
1175
1176#endif /* will be removed */
1177
1178/** @} */
1179
1180
1181/** @defgroup grp_mm_heap Heap Manager
1182 * @ingroup grp_mm_r3
1183 * @{ */
1184
1185/**
1186 * Allocate memory associating it with the VM for collective cleanup.
1187 *
1188 * The memory will be allocated from the default heap but a header
1189 * is added in which we keep track of which VM it belongs to and chain
1190 * all the allocations together so they can be freed in a one go.
1191 *
1192 * This interface is typically used for memory block which will not be
1193 * freed during the life of the VM.
1194 *
1195 * @returns Pointer to allocated memory.
1196 * @param pVM VM handle.
1197 * @param enmTag Statistics tag. Statistics are collected on a per tag
1198 * basis in addition to a global one. Thus we can easily
1199 * identify how memory is used by the VM.
1200 * @param cbSize Size of the block.
1201 * @thread Any thread.
1202 */
1203MMR3DECL(void *) MMR3HeapAlloc(PVM pVM, MMTAG enmTag, size_t cbSize);
1204
1205/**
1206 * Same as MMR3HeapAlloc().
1207 *
1208 *
1209 * @returns Pointer to allocated memory.
1210 * @param pVM VM handle.
1211 * @param enmTag Statistics tag. Statistics are collected on a per tag
1212 * basis in addition to a global one. Thus we can easily
1213 * identify how memory is used by the VM.
1214 * @param cbSize Size of the block.
1215 * @param ppv Where to store the pointer to the allocated memory on success.
1216 * @thread Any thread.
1217 */
1218MMR3DECL(int) MMR3HeapAllocEx(PVM pVM, MMTAG enmTag, size_t cbSize, void **ppv);
1219
1220/**
1221 * Same as MMR3HeapAlloc() only the memory is zeroed.
1222 *
1223 *
1224 * @returns Pointer to allocated memory.
1225 * @param pVM VM handle.
1226 * @param enmTag Statistics tag. Statistics are collected on a per tag
1227 * basis in addition to a global one. Thus we can easily
1228 * identify how memory is used by the VM.
1229 * @param cbSize Size of the block.
1230 * @thread Any thread.
1231 */
1232MMR3DECL(void *) MMR3HeapAllocZ(PVM pVM, MMTAG enmTag, size_t cbSize);
1233
1234/**
1235 * Same as MMR3HeapAllocZ().
1236 *
1237 *
1238 * @returns Pointer to allocated memory.
1239 * @param pVM VM handle.
1240 * @param enmTag Statistics tag. Statistics are collected on a per tag
1241 * basis in addition to a global one. Thus we can easily
1242 * identify how memory is used by the VM.
1243 * @param cbSize Size of the block.
1244 * @param ppv Where to store the pointer to the allocated memory on success.
1245 * @thread Any thread.
1246 */
1247MMR3DECL(int) MMR3HeapAllocZEx(PVM pVM, MMTAG enmTag, size_t cbSize, void **ppv);
1248
1249/**
1250 * Reallocate memory allocated with MMR3HeapAlloc() or MMR3HeapRealloc().
1251 *
1252 * @returns Pointer to reallocated memory.
1253 * @param pv Pointer to the memory block to reallocate.
1254 * Must not be NULL!
1255 * @param cbNewSize New block size.
1256 * @thread Any thread.
1257 */
1258MMR3DECL(void *) MMR3HeapRealloc(void *pv, size_t cbNewSize);
1259
1260/**
1261 * Duplicates the specified string.
1262 *
1263 * @returns Pointer to the duplicate.
1264 * @returns NULL on failure or when input NULL.
1265 * @param pVM The VM handle.
1266 * @param enmTag Statistics tag. Statistics are collected on a per tag
1267 * basis in addition to a global one. Thus we can easily
1268 * identify how memory is used by the VM.
1269 * @param psz The string to duplicate. NULL is allowed.
1270 */
1271MMR3DECL(char *) MMR3HeapStrDup(PVM pVM, MMTAG enmTag, const char *psz);
1272
1273/**
1274 * Releases memory allocated with MMR3HeapAlloc() or MMR3HeapRealloc().
1275 *
1276 * @param pv Pointer to the memory block to free.
1277 * @thread Any thread.
1278 */
1279MMR3DECL(void) MMR3HeapFree(void *pv);
1280
1281/** @} */
1282
1283/** @} */
1284#endif
1285
1286
1287
1288#ifdef IN_GC
1289/** @defgroup grp_mm_gc The MM Guest Context API
1290 * @ingroup grp_mm
1291 * @{
1292 */
1293
1294/**
1295 * Install MMGCRam Hypervisor page fault handler for normal working
1296 * of MMGCRamRead and MMGCRamWrite calls.
1297 * This handler will be automatically removed at page fault.
1298 * In other case it must be removed by MMGCRamDeregisterTrapHandler call.
1299 *
1300 * @param pVM VM handle.
1301 */
1302MMGCDECL(void) MMGCRamRegisterTrapHandler(PVM pVM);
1303
1304/**
1305 * Remove MMGCRam Hypervisor page fault handler.
1306 * See description of MMGCRamRegisterTrapHandler call.
1307 *
1308 * @param pVM VM handle.
1309 */
1310MMGCDECL(void) MMGCRamDeregisterTrapHandler(PVM pVM);
1311
1312/**
1313 * Read data in guest context with \#PF control.
1314 * MMRamGC page fault handler must be installed prior this call for safe operation.
1315 * Use MMGCRamRegisterTrapHandler() call for this task.
1316 *
1317 * @returns VBox status.
1318 * @param pDst Where to store the readed data.
1319 * @param pSrc Pointer to the data to read.
1320 * @param cb Size of data to read, only 1/2/4/8 is valid.
1321 */
1322MMGCDECL(int) MMGCRamReadNoTrapHandler(void *pDst, void *pSrc, size_t cb);
1323
1324/**
1325 * Write data in guest context with \#PF control.
1326 * MMRamGC page fault handler must be installed prior this call for safe operation.
1327 * Use MMGCRamRegisterTrapHandler() call for this task.
1328 *
1329 * @returns VBox status.
1330 * @param pDst Where to write the data.
1331 * @param pSrc Pointer to the data to write.
1332 * @param cb Size of data to write, only 1/2/4 is valid.
1333 */
1334MMGCDECL(int) MMGCRamWriteNoTrapHandler(void *pDst, void *pSrc, size_t cb);
1335
1336/**
1337 * Read data in guest context with \#PF control.
1338 *
1339 * @returns VBox status.
1340 * @param pVM The VM handle.
1341 * @param pDst Where to store the readed data.
1342 * @param pSrc Pointer to the data to read.
1343 * @param cb Size of data to read, only 1/2/4/8 is valid.
1344 */
1345MMGCDECL(int) MMGCRamRead(PVM pVM, void *pDst, void *pSrc, size_t cb);
1346
1347/**
1348 * Write data in guest context with \#PF control.
1349 *
1350 * @returns VBox status.
1351 * @param pVM The VM handle.
1352 * @param pDst Where to write the data.
1353 * @param pSrc Pointer to the data to write.
1354 * @param cb Size of data to write, only 1/2/4 is valid.
1355 */
1356MMGCDECL(int) MMGCRamWrite(PVM pVM, void *pDst, void *pSrc, size_t cb);
1357
1358/** @} */
1359#endif
1360
1361/** @} */
1362__END_DECLS
1363
1364
1365#endif
1366
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette