VirtualBox

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

Last change on this file since 2889 was 2610, checked in by vboxsync, 18 years ago

spelling

  • 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 InnoTek Systemberatung 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
169 MM_TAG_PGM,
170 MM_TAG_PGM_HANDLERS,
171 MM_TAG_PGM_POOL,
172
173 MM_TAG_REM,
174
175 MM_TAG_SELM,
176
177 MM_TAG_SSM,
178
179 MM_TAG_STAM,
180
181 MM_TAG_TM,
182
183 MM_TAG_TRPM,
184
185 MM_TAG_VM,
186 MM_TAG_VM_REQ,
187
188 MM_TAG_VMM,
189
190 MM_TAG_HWACCM,
191
192 MM_TAG_32BIT_HACK = 0x7fffffff
193} MMTAG;
194
195
196
197
198/** @defgroup grp_mm_hyper Hypervisor Memory Management
199 * @ingroup grp_mm
200 * @{ */
201
202/**
203 * Converts a ring-0 host context address in the Hypervisor memory region to a ring-3 host context address.
204 *
205 * @returns ring-3 host context address.
206 * @param pVM The VM to operate on.
207 * @param R0Ptr The ring-0 host context address.
208 * You'll be damned if this is not in the HMA! :-)
209 * @thread The Emulation Thread.
210 */
211MMDECL(RTR3PTR) MMHyperR0ToR3(PVM pVM, RTR0PTR R0Ptr);
212
213/**
214 * Converts a ring-0 host context address in the Hypervisor memory region to a guest context address.
215 *
216 * @returns guest context address.
217 * @param pVM The VM to operate on.
218 * @param R0Ptr The ring-0 host context address.
219 * You'll be damned if this is not in the HMA! :-)
220 * @thread The Emulation Thread.
221 */
222MMDECL(RTGCPTR) MMHyperR0ToGC(PVM pVM, RTR0PTR R0Ptr);
223
224/**
225 * Converts a ring-0 host context address in the Hypervisor memory region to a current context address.
226 *
227 * @returns current context address.
228 * @param pVM The VM to operate on.
229 * @param R0Ptr The ring-0 host context address.
230 * You'll be damned if this is not in the HMA! :-)
231 * @thread The Emulation Thread.
232 */
233#ifndef IN_RING0
234MMDECL(void *) MMHyperR0ToCC(PVM pVM, RTR0PTR R0Ptr);
235#endif
236
237
238/**
239 * Converts a ring-3 host context address in the Hypervisor memory region to a ring-0 host context address.
240 *
241 * @returns ring-0 host context address.
242 * @param pVM The VM to operate on.
243 * @param R3Ptr The ring-3 host context address.
244 * You'll be damned if this is not in the HMA! :-)
245 * @thread The Emulation Thread.
246 */
247MMDECL(RTR0PTR) MMHyperR3ToR0(PVM pVM, RTR3PTR R3Ptr);
248
249/**
250 * Converts a ring-3 host context address in the Hypervisor memory region to a guest context address.
251 *
252 * @returns guest context address.
253 * @param pVM The VM to operate on.
254 * @param R3Ptr The ring-3 host context address.
255 * You'll be damned if this is not in the HMA! :-)
256 * @thread The Emulation Thread.
257 */
258MMDECL(RTGCPTR) MMHyperR3ToGC(PVM pVM, RTR3PTR R3Ptr);
259
260/**
261 * Converts a ring-3 host context address in the Hypervisor memory region to a current context address.
262 *
263 * @returns current context address.
264 * @param pVM The VM to operate on.
265 * @param R3Ptr The ring-3 host context address.
266 * You'll be damned if this is not in the HMA! :-)
267 * @thread The Emulation Thread.
268 */
269#ifndef IN_RING3
270MMDECL(void *) MMHyperR3ToCC(PVM pVM, RTR3PTR R3Ptr);
271#else
272DECLINLINE(void *) MMHyperR3ToCC(PVM pVM, RTR3PTR R3Ptr)
273{
274 NOREF(pVM);
275 return R3Ptr;
276}
277#endif
278
279
280/**
281 * Converts a guest context address in the Hypervisor memory region to a ring-3 context address.
282 *
283 * @returns ring-3 host context address.
284 * @param pVM The VM to operate on.
285 * @param GCPtr The guest context address.
286 * You'll be damned if this is not in the HMA! :-)
287 * @thread The Emulation Thread.
288 */
289MMDECL(RTR3PTR) MMHyperGCToR3(PVM pVM, RTGCPTR GCPtr);
290
291/**
292 * Converts a guest context address in the Hypervisor memory region to a ring-0 host context address.
293 *
294 * @returns ring-0 host context address.
295 * @param pVM The VM to operate on.
296 * @param GCPtr The guest context address.
297 * You'll be damned if this is not in the HMA! :-)
298 * @thread The Emulation Thread.
299 */
300MMDECL(RTR0PTR) MMHyperGCToR0(PVM pVM, RTGCPTR GCPtr);
301
302/**
303 * Converts a guest context address in the Hypervisor memory region to a current context address.
304 *
305 * @returns current context address.
306 * @param pVM The VM to operate on.
307 * @param GCPtr The guest host context address.
308 * You'll be damned if this is not in the HMA! :-)
309 * @thread The Emulation Thread.
310 */
311#ifndef IN_GC
312MMDECL(void *) MMHyperGCToCC(PVM pVM, RTGCPTR GCPtr);
313#else
314DECLINLINE(void *) MMHyperGCToCC(PVM pVM, RTGCPTR GCPtr)
315{
316 NOREF(pVM);
317 return GCPtr;
318}
319#endif
320
321
322
323/**
324 * Converts a current context address in the Hypervisor memory region to a ring-3 host context address.
325 *
326 * @returns ring-3 host context address.
327 * @param pVM The VM to operate on.
328 * @param pv The current context address.
329 * You'll be damned if this is not in the HMA! :-)
330 * @thread The Emulation Thread.
331 */
332#ifndef IN_RING3
333MMDECL(RTR3PTR) MMHyperCCToR3(PVM pVM, void *pv);
334#else
335DECLINLINE(RTR3PTR) MMHyperCCToR3(PVM pVM, void *pv)
336{
337 NOREF(pVM);
338 return pv;
339}
340#endif
341
342/**
343 * Converts a current context address in the Hypervisor memory region to a ring-0 host context address.
344 *
345 * @returns ring-0 host context address.
346 * @param pVM The VM to operate on.
347 * @param pv The current context address.
348 * You'll be damned if this is not in the HMA! :-)
349 * @thread The Emulation Thread.
350 */
351#ifndef IN_RING0
352MMDECL(RTR0PTR) MMHyperCCToR0(PVM pVM, void *pv);
353#else
354DECLINLINE(RTR0PTR) MMHyperCCToR0(PVM pVM, void *pv)
355{
356 NOREF(pVM);
357 return pv;
358}
359#endif
360
361/**
362 * Converts a current context address in the Hypervisor memory region to a guest context address.
363 *
364 * @returns guest context address.
365 * @param pVM The VM to operate on.
366 * @param pv The current context address.
367 * You'll be damned if this is not in the HMA! :-)
368 * @thread The Emulation Thread.
369 */
370#ifndef IN_GC
371MMDECL(RTGCPTR) MMHyperCCToGC(PVM pVM, void *pv);
372#else
373DECLINLINE(RTGCPTR) MMHyperCCToGC(PVM pVM, void *pv)
374{
375 NOREF(pVM);
376 return pv;
377}
378#endif
379
380
381
382/**
383 * Converts a current context address in the Hypervisor memory region to a HC address.
384 * The memory must have been allocated with MMHyperAlloc().
385 *
386 * @returns HC address.
387 * @param pVM The VM to operate on.
388 * @param Ptr The current context address.
389 * @thread The Emulation Thread.
390 * @deprecated
391 */
392#ifdef IN_GC
393MMDECL(RTHCPTR) MMHyper2HC(PVM pVM, uintptr_t Ptr);
394#else
395DECLINLINE(RTHCPTR) MMHyper2HC(PVM pVM, uintptr_t Ptr)
396{
397 NOREF(pVM);
398 return (RTHCPTR)Ptr;
399}
400#endif
401
402/**
403 * Converts a current context address in the Hypervisor memory region to a GC address.
404 * The memory must have been allocated with MMHyperAlloc().
405 *
406 * @returns HC address.
407 * @param pVM The VM to operate on.
408 * @param Ptr The current context address.
409 * @thread The Emulation Thread.
410 */
411#ifndef IN_GC
412MMDECL(RTGCPTR) MMHyper2GC(PVM pVM, uintptr_t Ptr);
413#else
414DECLINLINE(RTGCPTR) MMHyper2GC(PVM pVM, uintptr_t Ptr)
415{
416 NOREF(pVM);
417 return (RTGCPTR)Ptr;
418}
419#endif
420
421/**
422 * Converts a HC address in the Hypervisor memory region to a GC address.
423 * The memory must have been allocated with MMGCHyperAlloc() or MMR3HyperAlloc().
424 *
425 * @returns GC address.
426 * @param pVM The VM to operate on.
427 * @param HCPtr The host context address.
428 * You'll be damned if this is not in the HMA! :-)
429 * @thread The Emulation Thread.
430 * @deprecated
431 */
432MMDECL(RTGCPTR) MMHyperHC2GC(PVM pVM, RTHCPTR HCPtr);
433
434/**
435 * Converts a GC address in the Hypervisor memory region to a HC address.
436 * The memory must have been allocated with MMGCHyperAlloc() or MMR3HyperAlloc().
437 *
438 * @returns HC address.
439 * @param pVM The VM to operate on.
440 * @param GCPtr The guest context address.
441 * You'll be damned if this is not in the HMA! :-)
442 * @thread The Emulation Thread.
443 * @deprecated
444 */
445MMDECL(RTHCPTR) MMHyperGC2HC(PVM pVM, RTGCPTR GCPtr);
446
447
448/**
449 * Allocates memory in the Hypervisor (GC VMM) area.
450 * The returned memory is of course zeroed.
451 *
452 * @returns VBox status code.
453 * @param pVM The VM to operate on.
454 * @param cb Number of bytes to allocate.
455 * @param uAlignment Required memory alignment in bytes.
456 * Values are 0,8,16,32 and PAGE_SIZE.
457 * 0 -> default alignment, i.e. 8 bytes.
458 * @param enmTag The statistics tag.
459 * @param ppv Where to store the address to the allocated
460 * memory.
461 * @remark This is assumed not to be used at times when serialization is required.
462 */
463MMDECL(int) MMHyperAlloc(PVM pVM, size_t cb, uint32_t uAlignment, MMTAG enmTag, void **ppv);
464
465/**
466 * Free memory allocated using MMHyperAlloc().
467 *
468 * It's not possible to free memory which is page aligned!
469 *
470 * @returns VBox status code.
471 * @param pVM The VM to operate on.
472 * @param pv The memory to free.
473 * @remark Try avoid freeing hyper memory.
474 * @thread The Emulation Thread.
475 */
476MMDECL(int) MMHyperFree(PVM pVM, void *pv);
477
478#ifdef DEBUG
479/**
480 * Dumps the hypervisor heap to Log.
481 * @param pVM VM Handle.
482 * @thread The Emulation Thread.
483 */
484MMDECL(void) MMHyperHeapDump(PVM pVM);
485#endif
486
487/**
488 * Query the amount of free memory in the hypervisor heap.
489 *
490 * @returns Number of free bytes in the hypervisor heap.
491 * @thread Any.
492 */
493MMDECL(size_t) MMHyperHeapGetFreeSize(PVM pVM);
494
495/**
496 * Query the size the hypervisor heap.
497 *
498 * @returns The size of the hypervisor heap in bytes.
499 * @thread Any.
500 */
501MMDECL(size_t) MMHyperHeapGetSize(PVM pVM);
502
503
504/**
505 * Query the address and size the hypervisor memory area.
506 *
507 * @returns Base address of the hypervisor area.
508 * @param pVM VM Handle.
509 * @param pcb Where to store the size of the hypervisor area. (out)
510 * @thread Any.
511 */
512MMDECL(RTGCPTR) MMHyperGetArea(PVM pVM, size_t *pcb);
513
514/**
515 * Checks if an address is within the hypervisor memory area.
516 *
517 * @returns true if inside.
518 * @returns false if outside.
519 * @param pVM VM handle.
520 * @param GCPtr The pointer to check.
521 * @thread The Emulation Thread.
522 */
523MMDECL(bool) MMHyperIsInsideArea(PVM pVM, RTGCPTR GCPtr);
524
525/**
526 * Convert a page in the page pool to a HC physical address.
527 * This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
528 * and MMR3PageAllocLow().
529 *
530 * @returns Physical address for the specified page table.
531 * @param pVM VM handle.
532 * @param pvPage Page which physical address we query.
533 * @thread The Emulation Thread.
534 */
535MMDECL(RTHCPHYS) MMPage2Phys(PVM pVM, void *pvPage);
536
537/**
538 * Convert physical address of a page to a HC virtual address.
539 * This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
540 * and MMR3PageAllocLow().
541 *
542 * @returns Pointer to the page at that physical address.
543 * @param pVM VM handle.
544 * @param HCPhysPage The physical address of a page.
545 * @thread The Emulation Thread.
546 */
547MMDECL(void *) MMPagePhys2Page(PVM pVM, RTHCPHYS HCPhysPage);
548
549
550/**
551 * Convert physical address of a page to a HC virtual address.
552 * This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
553 * and MMR3PageAllocLow().
554 *
555 * @returns VBox status code.
556 * @param pVM VM handle.
557 * @param HCPhysPage The physical address of a page.
558 * @param ppvPage Where to store the address corresponding to HCPhysPage.
559 * @thread The Emulation Thread.
560 */
561MMDECL(int) MMPagePhys2PageEx(PVM pVM, RTHCPHYS HCPhysPage, void **ppvPage);
562
563
564/**
565 * Try convert physical address of a page to a HC virtual address.
566 * This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
567 * and MMR3PageAllocLow().
568 *
569 * @returns VBox status code.
570 * @param pVM VM handle.
571 * @param HCPhysPage The physical address of a page.
572 * @param ppvPage Where to store the address corresponding to HCPhysPage.
573 * @thread The Emulation Thread.
574 */
575MMDECL(int) MMPagePhys2PageTry(PVM pVM, RTHCPHYS HCPhysPage, void **ppvPage);
576
577/**
578 * Convert GC physical address to HC virtual address.
579 *
580 * @returns HC virtual address.
581 * @param pVM VM Handle
582 * @param GCPhys Guest context physical address.
583 * @param cbRange Physical range
584 * @thread The Emulation Thread.
585 * @deprecated
586 */
587MMDECL(void *) MMPhysGCPhys2HCVirt(PVM pVM, RTGCPHYS GCPhys, RTUINT cbRange);
588
589/**
590 * Convert GC virtual address to HC virtual address.
591 *
592 * This uses the current PD of the guest.
593 *
594 * @returns HC virtual address.
595 * @param pVM VM Handle
596 * @param GCPtr Guest context virtual address.
597 * @thread The Emulation Thread.
598 * @deprecated
599 */
600MMDECL(void *) MMPhysGCVirt2HCVirt(PVM pVM, RTGCPTR pvGC);
601
602
603/** @def MMHYPER_GC_ASSERT_GCPTR
604 * Asserts that an address is either NULL or inside the hypervisor memory area.
605 * This assertion only works while IN_GC, it's a NOP everywhere else.
606 * @thread The Emulation Thread.
607 */
608#ifdef IN_GC
609# define MMHYPER_GC_ASSERT_GCPTR(pVM, GCPtr) Assert(MMHyperIsInsideArea((pVM), (GCPtr)) || !(GCPtr))
610#else
611# define MMHYPER_GC_ASSERT_GCPTR(pVM, GCPtr) do { } while (0)
612#endif
613
614/** @} */
615
616
617#ifdef IN_RING3
618/** @defgroup grp_mm_r3 The MM Host Context Ring-3 API
619 * @ingroup grp_mm
620 * @{
621 */
622
623/**
624 * Initialization of MM (save anything depending on PGM).
625 *
626 * @returns VBox status code.
627 * @param pVM The VM to operate on.
628 * @thread The Emulation Thread.
629 */
630MMR3DECL(int) MMR3Init(PVM pVM);
631
632/**
633 * Initializes the MM parts which depends on PGM being initialized.
634 *
635 * @returns VBox status code.
636 * @param pVM The VM to operate on.
637 * @thread The Emulation Thread.
638 */
639MMR3DECL(int) MMR3InitPaging(PVM pVM);
640
641/**
642 * Finalizes the HMA mapping.
643 *
644 * This is called later during init, most (all) HMA allocations should be done
645 * by the time this function is called.
646 *
647 * @returns VBox status.
648 */
649MMR3DECL(int) MMR3HyperInitFinalize(PVM pVM);
650
651/**
652 * Terminates the MM.
653 *
654 * Termination means cleaning up and freeing all resources,
655 * the VM it self is at this point powered off or suspended.
656 *
657 * @returns VBox status code.
658 * @param pVM The VM to operate on.
659 * @thread The Emulation Thread.
660 */
661MMR3DECL(int) MMR3Term(PVM pVM);
662
663/**
664 * Convert HC Physical address to HC Virtual address.
665 *
666 * @returns VBox status.
667 * @param pVM VM handle.
668 * @param HCPhys The host context virtual address.
669 * @param ppv Where to store the resulting address.
670 * @thread The Emulation Thread.
671 */
672MMR3DECL(int) MMR3HCPhys2HCVirt(PVM pVM, RTHCPHYS HCPhys, void **ppv);
673
674/**
675 * Read memory from GC virtual address using the current guest CR3.
676 *
677 * @returns VBox status.
678 * @param pVM VM handle.
679 * @param pvDst Destination address (HC of course).
680 * @param GCPtr GC virtual address.
681 * @param cb Number of bytes to read.
682 * @thread The Emulation Thread.
683 */
684MMR3DECL(int) MMR3ReadGCVirt(PVM pVM, void *pvDst, RTGCPTR GCPtr, size_t cb);
685
686/**
687 * Write to memory at GC virtual address translated using the current guest CR3.
688 *
689 * @returns VBox status.
690 * @param pVM VM handle.
691 * @param GCPtrDst GC virtual address.
692 * @param pvSrc The source address (HC of course).
693 * @param cb Number of bytes to read.
694 */
695MMR3DECL(int) MMR3WriteGCVirt(PVM pVM, RTGCPTR GCPtrDst, const void *pvSrc, size_t cb);
696
697
698/** @defgroup grp_mm_r3_hyper Hypervisor Memory Manager (HC R3 Portion)
699 * @ingroup grp_mm_r3
700 * @{ */
701/**
702 * Allocates memory in the Hypervisor (GC VMM) area which never will
703 * be freed and don't have any offset based relation to other heap blocks.
704 *
705 * The latter means that two blocks allocated by this API will not have the
706 * same relative position to each other in GC and HC. In short, never use
707 * this API for allocating nodes for an offset based AVL tree!
708 *
709 * The returned memory is of course zeroed.
710 *
711 * @returns VBox status code.
712 * @param pVM The VM to operate on.
713 * @param cb Number of bytes to allocate.
714 * @param uAlignment Required memory alignment in bytes.
715 * Values are 0,8,16,32 and PAGE_SIZE.
716 * 0 -> default alignment, i.e. 8 bytes.
717 * @param enmTag The statistics tag.
718 * @param ppv Where to store the address to the allocated
719 * memory.
720 * @remark This is assumed not to be used at times when serialization is required.
721 */
722MMDECL(int) MMR3HyperAllocOnceNoRel(PVM pVM, size_t cb, uint32_t uAlignment, MMTAG enmTag, void **ppv);
723
724/**
725 * Maps contiguous HC physical memory into the hypervisor region in the GC.
726 *
727 * @return VBox status code.
728 *
729 * @param pVM VM handle.
730 * @param pvHC Host context address of the memory. Must be page aligned!
731 * @param HCPhys Host context physical address of the memory to be mapped. Must be page aligned!
732 * @param cb Size of the memory. Will be rounded up to nearest page.
733 * @param pszDesc Description.
734 * @param pGCPtr Where to store the GC address.
735 * @thread The Emulation Thread.
736 */
737MMR3DECL(int) MMR3HyperMapHCPhys(PVM pVM, void *pvHC, RTHCPHYS HCPhys, size_t cb, const char *pszDesc, PRTGCPTR pGCPtr);
738
739/**
740 * Maps contiguous GC physical memory into the hypervisor region in the GC.
741 *
742 * @return VBox status code.
743 *
744 * @param pVM VM handle.
745 * @param GCPhys Guest context physical address of the memory to be mapped. Must be page aligned!
746 * @param cb Size of the memory. Will be rounded up to nearest page.
747 * @param pszDesc Mapping description.
748 * @param pGCPtr Where to store the GC address.
749 * @thread The Emulation Thread.
750 */
751MMR3DECL(int) MMR3HyperMapGCPhys(PVM pVM, RTGCPHYS GCPhys, size_t cb, const char *pszDesc, PRTGCPTR pGCPtr);
752
753/**
754 * Locks and Maps HC virtual memory into the hypervisor region in the GC.
755 *
756 * @return VBox status code.
757 *
758 * @param pVM VM handle.
759 * @param pvHC Host context address of the memory (may be not page aligned).
760 * @param cb Size of the memory. Will be rounded up to nearest page.
761 * @param fFree Set this if MM is responsible for freeing the memory using SUPPageFree.
762 * @param pszDesc Mapping description.
763 * @param pGCPtr Where to store the GC address corresponding to pvHC.
764 * @thread The Emulation Thread.
765 */
766MMR3DECL(int) MMR3HyperMapHCRam(PVM pVM, void *pvHC, size_t cb, bool fFree, const char *pszDesc, PRTGCPTR pGCPtr);
767
768/**
769 * Maps locked R3 virtual memory into the hypervisor region in the GC.
770 *
771 * @return VBox status code.
772 *
773 * @param pVM VM handle.
774 * @param pvR3 The ring-3 address of the memory, must be page aligned.
775 * @param pvR0 The ring-0 address of the memory, must be page aligned. (optional)
776 * @param cPages The number of pages.
777 * @param paPages The page descriptors.
778 * @param pszDesc Mapping description.
779 * @param pGCPtr Where to store the GC address corresponding to pvHC.
780 */
781MMR3DECL(int) MMR3HyperMapPages(PVM pVM, void *pvR3, RTR0PTR pvR0, size_t cPages, PCSUPPAGE paPages, const char *pszDesc, PRTGCPTR pGCPtr);
782
783/**
784 * Reserves a hypervisor memory area.
785 * Most frequent usage is fence pages and dynamically mappings like the guest PD and PDPTR.
786 *
787 * @return VBox status code.
788 *
789 * @param pVM VM handle.
790 * @param cb Size of the memory. Will be rounded up to nearest page.
791 * @param pszDesc Mapping description.
792 * @param pGCPtr Where to store the assigned GC address. Optional.
793 * @thread The Emulation Thread.
794 */
795MMR3DECL(int) MMR3HyperReserve(PVM pVM, unsigned cb, const char *pszDesc, PRTGCPTR pGCPtr);
796
797
798/**
799 * Convert hypervisor HC virtual address to HC physical address.
800 *
801 * @returns HC physical address.
802 * @param pVM VM Handle
803 * @param pvHC Host context physical address.
804 * @thread The Emulation Thread.
805 */
806MMR3DECL(RTHCPHYS) MMR3HyperHCVirt2HCPhys(PVM pVM, void *pvHC);
807/**
808 * Convert hypervisor HC virtual address to HC physical address.
809 *
810 * @returns HC physical address.
811 * @param pVM VM Handle
812 * @param pvHC Host context physical address.
813 * @param pHCPhys Where to store the HC physical address.
814 * @thread The Emulation Thread.
815 */
816MMR3DECL(int) MMR3HyperHCVirt2HCPhysEx(PVM pVM, void *pvHC, PRTHCPHYS pHCPhys);
817/**
818 * Convert hypervisor HC physical address to HC virtual address.
819 *
820 * @returns HC virtual address.
821 * @param pVM VM Handle
822 * @param HCPhys Host context physical address.
823 * @thread The Emulation Thread.
824 */
825MMR3DECL(void *) MMR3HyperHCPhys2HCVirt(PVM pVM, RTHCPHYS HCPhys);
826/**
827 * Convert hypervisor HC physical address to HC virtual address.
828 *
829 * @returns VBox status.
830 * @param pVM VM Handle
831 * @param HCPhys Host context physical address.
832 * @param ppv Where to store the HC virtual address.
833 * @thread The Emulation Thread.
834 */
835MMR3DECL(int) MMR3HyperHCPhys2HCVirtEx(PVM pVM, RTHCPHYS HCPhys, void **ppv);
836
837/**
838 * Read hypervisor memory from GC virtual address.
839 *
840 * @returns VBox status.
841 * @param pVM VM handle.
842 * @param pvDst Destination address (HC of course).
843 * @param GCPtr GC virtual address.
844 * @param cb Number of bytes to read.
845 * @thread The Emulation Thread.
846 */
847MMR3DECL(int) MMR3HyperReadGCVirt(PVM pVM, void *pvDst, RTGCPTR GCPtr, size_t cb);
848
849/** @} */
850
851
852/** @defgroup grp_mm_phys Guest Physical Memory Manager
853 * @ingroup grp_mm_r3
854 * @{ */
855
856/**
857 * Register externally allocated RAM for the virtual machine.
858 *
859 * The memory registered with the VM thru this interface must not be freed
860 * before the virtual machine has been destroyed. Bad things may happen... :-)
861 *
862 * @return VBox status code.
863 * @param pVM VM handle.
864 * @param pvRam Virtual address of the guest's physical memory range Must be page aligned.
865 * @param GCPhys The physical address the ram shall be registered at.
866 * @param cb Size of the memory. Must be page aligend.
867 * @param fFlags Flags of the MM_RAM_FLAGS_* defines.
868 * @param pszDesc Description of the memory.
869 * @thread The Emulation Thread.
870 */
871MMR3DECL(int) MMR3PhysRegister(PVM pVM, void *pvRam, RTGCPHYS GCPhys, unsigned cb, unsigned fFlags, const char *pszDesc);
872
873/**
874 * Register externally allocated RAM for the virtual machine.
875 *
876 * The memory registered with the VM thru this interface must not be freed
877 * before the virtual machine has been destroyed. Bad things may happen... :-)
878 *
879 * @return VBox status code.
880 * @param pVM VM handle.
881 * @param pvRam Virtual address of the guest's physical memory range Must be page aligned.
882 * @param GCPhys The physical address the ram shall be registered at.
883 * @param cb Size of the memory. Must be page aligend.
884 * @param fFlags Flags of the MM_RAM_FLAGS_* defines.
885 * @param enmType Physical range type (MM_PHYS_TYPE_*)
886 * @param pszDesc Description of the memory.
887 * @thread The Emulation Thread.
888 * @todo update this description.
889 */
890MMR3DECL(int) MMR3PhysRegisterEx(PVM pVM, void *pvRam, RTGCPHYS GCPhys, unsigned cb, unsigned fFlags, MMPHYSREG enmType, const char *pszDesc);
891
892/**
893 * Register previously registered externally allocated RAM for the virtual machine.
894 *
895 * Use this only for MMIO ranges or the guest will become very confused.
896 * The memory registered with the VM thru this interface must not be freed
897 * before the virtual machine has been destroyed. Bad things may happen... :-)
898 *
899 * @return VBox status code.
900 * @param pVM VM handle.
901 * @param GCPhysOld The physical address the ram was registered at.
902 * @param GCPhysNew The physical address the ram shall be registered at.
903 * @param cb Size of the memory. Must be page aligend.
904 * @thread The Emulation Thread.
905 */
906MMR3DECL(int) MMR3PhysRelocate(PVM pVM, RTGCPHYS GCPhysOld, RTGCPHYS GCPhysNew, unsigned cb);
907
908/**
909 * Register a ROM (BIOS) region.
910 *
911 * It goes without saying that this is read-only memory. The memory region must be
912 * in unassigned memory. I.e. from the top of the address space or on the PC in
913 * the 0xa0000-0xfffff range.
914 *
915 * @returns VBox status.
916 * @param pVM VM Handle.
917 * @param pDevIns The device instance owning the ROM region.
918 * @param GCPhys First physical address in the range.
919 * Must be page aligned!
920 * @param cbRange The size of the range (in bytes).
921 * Must be page aligned!
922 * @param pvBinary Pointer to the binary data backing the ROM image.
923 * This must be cbRange bytes big.
924 * It will be copied and doesn't have to stick around.
925 * @param pszDesc Pointer to description string. This must not be freed.
926 * @remark There is no way to remove the rom, automatically on device cleanup or
927 * manually from the device yet. At present I doubt we need such features...
928 * @thread The Emulation Thread.
929 */
930MMR3DECL(int) MMR3PhysRomRegister(PVM pVM, PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const void *pvBinary, const char *pszDesc);
931
932/**
933 * Reserve physical address space for ROM and MMIO ranges.
934 *
935 * @returns VBox status code.
936 * @param pVM VM Handle.
937 * @param GCPhys Start physical address.
938 * @param cbRange The size of the range.
939 * @param pszDesc Description string.
940 * @thread The Emulation Thread.
941 */
942MMR3DECL(int) MMR3PhysReserve(PVM pVM, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc);
943
944/**
945 * Get the size of the base RAM.
946 * This usually means the size of the first contigous block of physical memory.
947 *
948 * @returns
949 * @param pVM
950 * @thread Any.
951 */
952MMR3DECL(uint64_t) MMR3PhysGetRamSize(PVM pVM);
953
954
955/** @} */
956
957
958/** @defgroup grp_mm_page Physical Page Pool
959 * @ingroup grp_mm_r3
960 * @{ */
961/**
962 * Allocates a page from the page pool.
963 *
964 * This function may returns pages which has physical addresses any
965 * where. If you require a page to be within the first 4GB of physical
966 * memory, use MMR3PageAllocLow().
967 *
968 * @returns Pointer to the allocated page page.
969 * @returns NULL on failure.
970 * @param pVM VM handle.
971 * @thread The Emulation Thread.
972 */
973MMR3DECL(void *) MMR3PageAlloc(PVM pVM);
974
975/**
976 * Allocates a page from the page pool and return its physical address.
977 *
978 * This function may returns pages which has physical addresses any
979 * where. If you require a page to be within the first 4GB of physical
980 * memory, use MMR3PageAllocLow().
981 *
982 * @returns Pointer to the allocated page page.
983 * @returns NIL_RTHCPHYS on failure.
984 * @param pVM VM handle.
985 * @thread The Emulation Thread.
986 */
987MMR3DECL(RTHCPHYS) MMR3PageAllocPhys(PVM pVM);
988
989/**
990 * Frees a page allocated from the page pool by MMR3PageAlloc() and MMR3PageAllocPhys().
991 *
992 * @param pVM VM handle.
993 * @param pvPage Pointer to the page.
994 * @thread The Emulation Thread.
995 */
996MMR3DECL(void) MMR3PageFree(PVM pVM, void *pvPage);
997
998/**
999 * Allocates a page from the low page pool.
1000 *
1001 * @returns Pointer to the allocated page.
1002 * @returns NULL on failure.
1003 * @param pVM VM handle.
1004 * @thread The Emulation Thread.
1005 */
1006MMR3DECL(void *) MMR3PageAllocLow(PVM pVM);
1007
1008/**
1009 * Frees a page allocated from the page pool by MMR3PageAllocLow().
1010 *
1011 * @param pVM VM handle.
1012 * @param pvPage Pointer to the page.
1013 * @thread The Emulation Thread.
1014 */
1015MMR3DECL(void) MMR3PageFreeLow(PVM pVM, void *pvPage);
1016
1017/**
1018 * Free a page allocated from the page pool by physical address.
1019 * This works for pages allocated by MMR3PageAlloc(), MMR3PageAllocPhys()
1020 * and MMR3PageAllocLow().
1021 *
1022 * @param pVM VM handle.
1023 * @param HCPhysPage The physical address of the page to be freed.
1024 * @thread The Emulation Thread.
1025 */
1026MMR3DECL(void) MMR3PageFreeByPhys(PVM pVM, RTHCPHYS HCPhysPage);
1027
1028/**
1029 * Gets the HC pointer to the dummy page.
1030 *
1031 * The dummy page is used as a place holder to prevent potential bugs
1032 * from doing really bad things to the system.
1033 *
1034 * @returns Pointer to the dummy page.
1035 * @param pVM VM handle.
1036 * @thread The Emulation Thread.
1037 */
1038MMR3DECL(void *) MMR3PageDummyHCPtr(PVM pVM);
1039
1040/**
1041 * Gets the HC Phys to the dummy page.
1042 *
1043 * The dummy page is used as a place holder to prevent potential bugs
1044 * from doing really bad things to the system.
1045 *
1046 * @returns Pointer to the dummy page.
1047 * @param pVM VM handle.
1048 * @thread The Emulation Thread.
1049 */
1050MMR3DECL(RTHCPHYS) MMR3PageDummyHCPhys(PVM pVM);
1051
1052
1053#if 1 /* these are temporary wrappers and will be removed soon */
1054/**
1055 * Allocates a Page Table.
1056 *
1057 * @returns Pointer to page table.
1058 * @returns NULL on failure.
1059 * @param pVM VM handle.
1060 * @deprecated Use MMR3PageAlloc().
1061 */
1062DECLINLINE(PVBOXPT) MMR3PTAlloc(PVM pVM)
1063{
1064 return (PVBOXPT)MMR3PageAlloc(pVM);
1065}
1066
1067/**
1068 * Free a Page Table.
1069 *
1070 * @param pVM VM handle.
1071 * @param pPT Pointer to the page table as returned by MMR3PTAlloc().
1072 * @deprecated Use MMR3PageFree().
1073 */
1074DECLINLINE(void) MMR3PTFree(PVM pVM, PVBOXPT pPT)
1075{
1076 MMR3PageFree(pVM, pPT);
1077}
1078
1079/**
1080 * Free a Page Table by physical address.
1081 *
1082 * @param pVM VM handle.
1083 * @param HCPhysPT The physical address of the page table to be freed.
1084 * @deprecated Use MMR3PageFreeByPhys().
1085 */
1086DECLINLINE(void) MMR3PTFreeByPhys(PVM pVM, RTHCPHYS HCPhysPT)
1087{
1088 MMR3PageFreeByPhys(pVM, HCPhysPT);
1089}
1090
1091/**
1092 * Convert a Page Table address to a HC physical address.
1093 *
1094 * @returns Physical address for the specified page table.
1095 * @param pVM VM handle.
1096 * @param pPT Page table which physical address we query.
1097 * @deprecated Use MMR3Page2Phys().
1098 */
1099DECLINLINE(RTHCPHYS) MMR3PT2Phys(PVM pVM, PVBOXPT pPT)
1100{
1101 return MMPage2Phys(pVM, pPT);
1102}
1103
1104/**
1105 * Convert a physical address to a page table address
1106 *
1107 * @returns Pointer to the page table at that physical address.
1108 * @param pVM VM handle.
1109 * @param PhysPT Page table which physical address we query.
1110 * @deprecated Use MMR3PagePhys2Page().
1111 */
1112DECLINLINE(PVBOXPT) MMR3Phys2PT(PVM pVM, RTHCPHYS PhysPT)
1113{
1114 return (PVBOXPT)MMPagePhys2Page(pVM, PhysPT);
1115}
1116
1117/**
1118 * Allocate a Page Directory.
1119 *
1120 * @returns Pointer to the page directory.
1121 * @returns NULL on failure.
1122 * @param pVM VM handle.
1123 * @deprecated Use MMR3PageAlloc().
1124 */
1125DECLINLINE(PVBOXPD) MMR3PDAlloc(PVM pVM)
1126{
1127 return (PVBOXPD)MMR3PageAlloc(pVM);
1128}
1129
1130/**
1131 * Free a Page Directory.
1132 *
1133 * @param pVM VM handle.
1134 * @param pPD Pointer to the page directory allocated by MMR3PDAlloc().
1135 * @deprecated Use MMR3PageFree().
1136 */
1137DECLINLINE(void) MMR3PDFree(PVM pVM, PVBOXPD pPD)
1138{
1139 MMR3PageFree(pVM, pPD);
1140}
1141
1142/**
1143 * Convert a Page Directory address to a physical address.
1144 *
1145 * @returns Physical address for the specified page directory.
1146 * @param pVM VM handle.
1147 * @param pPD Page directory which physical address we query.
1148 * Allocated by MMR3PDAlloc().
1149 * @deprecated Use MMR3Page2Phys().
1150 */
1151DECLINLINE(RTHCPHYS) MMR3PD2Phys(PVM pVM, PVBOXPD pPD)
1152{
1153 return MMPage2Phys(pVM, pPD);
1154}
1155
1156/**
1157 * Convert a physical address to a page directory address
1158 *
1159 * @returns Pointer to the page directory at that physical address.
1160 * @param pVM VM handle.
1161 * @param PhysPD Physical address of page directory.
1162 * Allocated by MMR3PDAlloc().
1163 * @deprecated Use MMR3PageAlloc().
1164 */
1165DECLINLINE(PVBOXPD) MMR3Phys2PD(PVM pVM, RTHCPHYS PhysPD)
1166{
1167 return (PVBOXPD)MMPagePhys2Page(pVM, PhysPD);
1168}
1169
1170/** @deprecated */
1171DECLINLINE(void *) MMR3DummyPageHCPtr(PVM pVM) { return MMR3PageDummyHCPtr(pVM); }
1172/** @deprecated */
1173DECLINLINE(RTHCPHYS) MMR3DummyPageHCPhys(PVM pVM) { return MMR3PageDummyHCPhys(pVM); }
1174
1175#endif /* will be removed */
1176
1177/** @} */
1178
1179
1180/** @defgroup grp_mm_heap Heap Manager
1181 * @ingroup grp_mm_r3
1182 * @{ */
1183
1184/**
1185 * Allocate memory associating it with the VM for collective cleanup.
1186 *
1187 * The memory will be allocated from the default heap but a header
1188 * is added in which we keep track of which VM it belongs to and chain
1189 * all the allocations together so they can be freed in a one go.
1190 *
1191 * This interface is typically used for memory block which will not be
1192 * freed during the life of the VM.
1193 *
1194 * @returns Pointer to allocated memory.
1195 * @param pVM VM handle.
1196 * @param enmTag Statistics tag. Statistics are collected on a per tag
1197 * basis in addition to a global one. Thus we can easily
1198 * identify how memory is used by the VM.
1199 * @param cbSize Size of the block.
1200 * @thread Any thread.
1201 */
1202MMR3DECL(void *) MMR3HeapAlloc(PVM pVM, MMTAG enmTag, size_t cbSize);
1203
1204/**
1205 * Same as MMR3HeapAlloc().
1206 *
1207 *
1208 * @returns Pointer to allocated memory.
1209 * @param pVM VM handle.
1210 * @param enmTag Statistics tag. Statistics are collected on a per tag
1211 * basis in addition to a global one. Thus we can easily
1212 * identify how memory is used by the VM.
1213 * @param cbSize Size of the block.
1214 * @param ppv Where to store the pointer to the allocated memory on success.
1215 * @thread Any thread.
1216 */
1217MMR3DECL(int) MMR3HeapAllocEx(PVM pVM, MMTAG enmTag, size_t cbSize, void **ppv);
1218
1219/**
1220 * Same as MMR3HeapAlloc() only the memory is zeroed.
1221 *
1222 *
1223 * @returns Pointer to allocated memory.
1224 * @param pVM VM handle.
1225 * @param enmTag Statistics tag. Statistics are collected on a per tag
1226 * basis in addition to a global one. Thus we can easily
1227 * identify how memory is used by the VM.
1228 * @param cbSize Size of the block.
1229 * @thread Any thread.
1230 */
1231MMR3DECL(void *) MMR3HeapAllocZ(PVM pVM, MMTAG enmTag, size_t cbSize);
1232
1233/**
1234 * Same as MMR3HeapAllocZ().
1235 *
1236 *
1237 * @returns Pointer to allocated memory.
1238 * @param pVM VM handle.
1239 * @param enmTag Statistics tag. Statistics are collected on a per tag
1240 * basis in addition to a global one. Thus we can easily
1241 * identify how memory is used by the VM.
1242 * @param cbSize Size of the block.
1243 * @param ppv Where to store the pointer to the allocated memory on success.
1244 * @thread Any thread.
1245 */
1246MMR3DECL(int) MMR3HeapAllocZEx(PVM pVM, MMTAG enmTag, size_t cbSize, void **ppv);
1247
1248/**
1249 * Reallocate memory allocated with MMR3HeapAlloc() or MMR3HeapRealloc().
1250 *
1251 * @returns Pointer to reallocated memory.
1252 * @param pv Pointer to the memory block to reallocate.
1253 * Must not be NULL!
1254 * @param cbNewSize New block size.
1255 * @thread Any thread.
1256 */
1257MMR3DECL(void *) MMR3HeapRealloc(void *pv, size_t cbNewSize);
1258
1259/**
1260 * Duplicates the specified string.
1261 *
1262 * @returns Pointer to the duplicate.
1263 * @returns NULL on failure or when input NULL.
1264 * @param pVM The VM handle.
1265 * @param enmTag Statistics tag. Statistics are collected on a per tag
1266 * basis in addition to a global one. Thus we can easily
1267 * identify how memory is used by the VM.
1268 * @param psz The string to duplicate. NULL is allowed.
1269 */
1270MMR3DECL(char *) MMR3HeapStrDup(PVM pVM, MMTAG enmTag, const char *psz);
1271
1272/**
1273 * Releases memory allocated with MMR3HeapAlloc() or MMR3HeapRealloc().
1274 *
1275 * @param pv Pointer to the memory block to free.
1276 * @thread Any thread.
1277 */
1278MMR3DECL(void) MMR3HeapFree(void *pv);
1279
1280/** @} */
1281
1282/** @} */
1283#endif
1284
1285
1286
1287#ifdef IN_GC
1288/** @defgroup grp_mm_gc The MM Guest Context API
1289 * @ingroup grp_mm
1290 * @{
1291 */
1292
1293/**
1294 * Install MMGCRam Hypervisor page fault handler for normal working
1295 * of MMGCRamRead and MMGCRamWrite calls.
1296 * This handler will be automatically removed at page fault.
1297 * In other case it must be removed by MMGCRamDeregisterTrapHandler call.
1298 *
1299 * @param pVM VM handle.
1300 */
1301MMGCDECL(void) MMGCRamRegisterTrapHandler(PVM pVM);
1302
1303/**
1304 * Remove MMGCRam Hypervisor page fault handler.
1305 * See description of MMGCRamRegisterTrapHandler call.
1306 *
1307 * @param pVM VM handle.
1308 */
1309MMGCDECL(void) MMGCRamDeregisterTrapHandler(PVM pVM);
1310
1311/**
1312 * Read data in guest context with \#PF control.
1313 * MMRamGC page fault handler must be installed prior this call for safe operation.
1314 * Use MMGCRamRegisterTrapHandler() call for this task.
1315 *
1316 * @returns VBox status.
1317 * @param pDst Where to store the readed data.
1318 * @param pSrc Pointer to the data to read.
1319 * @param cb Size of data to read, only 1/2/4/8 is valid.
1320 */
1321MMGCDECL(int) MMGCRamReadNoTrapHandler(void *pDst, void *pSrc, size_t cb);
1322
1323/**
1324 * Write data in guest context with \#PF control.
1325 * MMRamGC page fault handler must be installed prior this call for safe operation.
1326 * Use MMGCRamRegisterTrapHandler() call for this task.
1327 *
1328 * @returns VBox status.
1329 * @param pDst Where to write the data.
1330 * @param pSrc Pointer to the data to write.
1331 * @param cb Size of data to write, only 1/2/4 is valid.
1332 */
1333MMGCDECL(int) MMGCRamWriteNoTrapHandler(void *pDst, void *pSrc, size_t cb);
1334
1335/**
1336 * Read data in guest context with \#PF control.
1337 *
1338 * @returns VBox status.
1339 * @param pVM The VM handle.
1340 * @param pDst Where to store the readed data.
1341 * @param pSrc Pointer to the data to read.
1342 * @param cb Size of data to read, only 1/2/4/8 is valid.
1343 */
1344MMGCDECL(int) MMGCRamRead(PVM pVM, void *pDst, void *pSrc, size_t cb);
1345
1346/**
1347 * Write data in guest context with \#PF control.
1348 *
1349 * @returns VBox status.
1350 * @param pVM The VM handle.
1351 * @param pDst Where to write the data.
1352 * @param pSrc Pointer to the data to write.
1353 * @param cb Size of data to write, only 1/2/4 is valid.
1354 */
1355MMGCDECL(int) MMGCRamWrite(PVM pVM, void *pDst, void *pSrc, size_t cb);
1356
1357/** @} */
1358#endif
1359
1360/** @} */
1361__END_DECLS
1362
1363
1364#endif
1365
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