VirtualBox

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

Last change on this file since 6561 was 6546, checked in by vboxsync, 17 years ago

VBOX_WITH_NEW_PHYS_CODE changes mostly realted to REM. Killed a warning in cpu-exec.c.

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