> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with the Microsoft GDK Game OS memory manager

> Working with the Microsoft GDK Game OS memory manager

Although the internals of the memory manager are very different in the Microsoft GDK Game OS, the APIs that are available to allocate and manage memory are very similar (though not identical) to the APIs that are available in the XBOX One ERA OS.

## Memory allocation API family

### VirtualAlloc/VirtualFree

`VirtualAlloc` and `VirtualFree` are now identical to the standard implementations of these APIs on Windows PC environments. This provides a high degree of compatibility with any existing code that uses these APIs to obtain memory. In the XBOX One ERA OS, `VirtualAlloc` was modified to allocate XBOX-specific memory types through the `MEM_TITLE`, `MEM_GRAPHICS`, and `MEM_TOOL` flags. These flags are no longer supported. Instead, use [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc).

### HeapAlloc/HeapFree (and similar)

The Win32 heap-related APIs are also identical to the standard implementation of these APIs on Windows PC environments. Like `VirtualAlloc`, this provides a high degree of compatibility with existing code. Importantly, `HeapAlloc` and `HeapFree` are the APIs that are used by the C runtime/VCRuntime libraries to implement `malloc`/`new`/`free`/`delete` and related C-standard memory APIs.

All standard Win32 heaps use large (2 MB) pages for back-end storage to provide optimum performance. The heap efficiently subdivides each 2 MB page to satisfy incoming allocations and results in almost no increase in memory footprint compared to a Win32 heap over 4 KB pages. This also reduces the frequency that the Win32 heap must make expensive API calls to `VirtualAlloc` as it expands.

<Note>In the XBOX One ERA OS, `HeapAlloc` was modified to accept the `HEAP_TOOL` flag to obtain debug/extended memory through a Win32 heap. This flag has been deprecated and, in a future update to the Microsoft Game Development Kit (GDK), a new API will be available to replace this functionality.</Note>

### XMemVirtualAlloc

[XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) is a new API that was created for the Microsoft Game Development Kit (GDK). This API replaces the use of `VirtualAlloc` calls that were made with the `MEM_TITLE`, `MEM_GRAPHICS`, and `MEM_TOOL` flags from the XBOX One ERA environment. The parameters and calling convention are closely matched to `VirtualAlloc` with the addition of a new `XMemFlags` field that enables the caller to add more (XBOX-specific) details about the type of memory that's required.

### XMemAllocatePhysicalPages/XMemMapPhysicalPages/XMemFreePhysicalPages

You can use the physical page mapping APIs to get indexes of physical pages in memory. Allocating pages in this way gives the game complete control over the ownership of RAM. The page numbers that are returned can be combined and mapped into the virtual address space of the game as needed.

Like the XBOX One ERA OS, each physical page number that's returned represents 64 KB of RAM. Individual pages or arbitrary groups of pages can be mapped into appropriate reservations that are created with `MEM_64K_PAGES`. Mapping into 2 MB reservations is also possible by providing 2-MB-aligned groups of 32 consecutive pages.

Pages can be mapped multiple times with different page protections. For example, one mapping can be `PAGE_READWRITE` while another is `PAGE_READONLY`. However, you can't map a page multiple times with differing cache attributes (`WRITEBACK`, `WRITECOMBINE`, or `UNCACHED`). Attempting to do so returns an error. This wasn't possible in XBOX One ERA either, although any attempt to do so would silently fail, giving the appearance that it worked.

<Note>Microsoft GDK Game OS virtual memory works like the Windows memory system. If you allocate two addresses using [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) that are adjacent in the virtual address space, and then try mapping those pages with one call to [XMemMapPhysicalPages](/reference/system/xmem/functions/xmemmapphysicalpages) the behavior is undefined and not expected to work. Even though they happen to be adjacent to each other in the virtual address space they are different allocations as far as the memory system is concerned. The same case applies when you unmap the pages.</Note>

### XMemVirtualQuery/XMemGetWorkingSetStatistics

[XMemVirtualQuery](/reference/system/xmem/functions/xmemvirtualquery) and [XMemGetWorkingSetStatistics](/reference/system/xmem/functions/xmemgetworkingsetstatistics) are additional diagnostics APIs that are available to investigate XBOX-specific memory use details. [XMemVirtualQuery](/reference/system/xmem/functions/xmemvirtualquery) is very similar to `VirtualQuery`. `XMemVirtualQuery` returns additional information that isn't available from `VirtualQuery`, including page size and ownership (system or game) of the memory. [XMemGetWorkingSetStatistics](/reference/system/xmem/functions/xmemgetworkingsetstatistics) returns information about the current in-use memory footprint.


## Related topics

- [XMemMakeTag](/reference/system/xmem/functions/xmemmaketag.md)
- [XMemFreePhysicalPages](/reference/system/xmem/functions/xmemfreephysicalpages.md)
- [XMemMapPhysicalPagesScatter](/reference/system/xmem/functions/xmemmapphysicalpagesscatter.md)
- [Memory system for XBOX GDK titles](/build/console-features/memory/index.md)
- [XMemGetWorkingSetStatistics](/reference/system/xmem/functions/xmemgetworkingsetstatistics.md)