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.
HeapAlloc/HeapFree (and similar)
The Win32 heap-related APIs are also identical to the standard implementation of these APIs on Windows PC environments. LikeVirtualAlloc, 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.
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.XMemVirtualAlloc
XMemVirtualAlloc is a new API that was created for the Microsoft Game Development Kit (GDK). This API replaces the use ofVirtualAlloc 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 withMEM_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.
Microsoft GDK Game OS virtual memory works like the Windows memory system. If you allocate two addresses using XMemVirtualAlloc that are adjacent in the virtual address space, and then try mapping those pages with one call to 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.
XMemVirtualQuery/XMemGetWorkingSetStatistics
XMemVirtualQuery and XMemGetWorkingSetStatistics are additional diagnostics APIs that are available to investigate XBOX-specific memory use details. XMemVirtualQuery is very similar toVirtualQuery. XMemVirtualQuery returns additional information that isn’t available from VirtualQuery, including page size and ownership (system or game) of the memory. XMemGetWorkingSetStatistics returns information about the current in-use memory footprint.