> ## 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.

# XMemMapPhysicalPages

> XMemMapPhysicalPages

# XMemMapPhysicalPages

Maps pages allocated by [XMemAllocatePhysicalPages](/reference/system/xmem/functions/xmemallocatephysicalpages) into the virtual address space.

## Syntax

```cpp theme={null}
PVOID XMemMapPhysicalPages(  
         PVOID VirtualAddress,  
         ULONG_PTR NumberOfPages,  
         PULONG_PTR PageArray  
)  
```

### Parameters

*VirtualAddress*   \_In\_\
Type: PVOID

Address at which the pages should be mapped.

*NumberOfPages*   \_In\_\
Type: ULONG\_PTR

Number of entries in the *PageArray*.

*PageArray*   \_In\_reads\_opt\_(NumberOfPages)\
Type: PULONG\_PTR

Array of page frame numbers representing the pages to map.

### Return value

Type: PVOID

Virtual address at which the physical pages have been mapped, or NULL if there was a mapping failure.

In the case of a mapping failure, call <a href="https://msdn.microsoft.com/library/windows/desktop/ms679360(v=vs.85).aspx">GetLastError</a> to get extended error information.

## Remarks

The virtual address range must be previously reserved by a call to [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) with **MEM\_RESERVE**, a page size of **MEM\_64K\_PAGES** or **MEM\_2MB\_PAGES** and the **XMEM\_MAPPABLE** flag. **MEM\_PHYSICAL** address reservations made by VirtualAlloc will not be usable for mapping this memory.

If the virtual address range already has mapped pages, they will be unmapped. Additionally, NULL may be specified for the PageArray in order to decommit the memory region.

**XMemMapPhysicalPages** may be used to map the same physical pages multiple times in the virtual address space. If pages are mapped multiple times, the multiple mappings must specify identical caching attributes (CPU coherent is implied if no cache attribute is provided, otherwise the list is **PAGE\_NOCACHE** or **PAGE\_WRITECOMBINE**).

<Note>When mapping physical pages into memory reserved with MEM\_2MB\_PAGES the physical pages must have been allocated with XMEM\_2MB\_CLUSTERS. The PageArray parameter should only contain the first physical page of each 2MB cluster.</Note>

Example:

```cpp theme={null}
ULONG_PTR PageArray[64];
ULONG_PTR PageCount = RTL_NUMBER_OF(PageArray);
XMemAllocatePhysicalPages(XMEM_2MB_CLUSTERS, &PageCount, PageArray);

// Allocate 4MB of reserved space as both 64KB page sizes and 2MB page sizes
PVOID RWAddress = XMemVirtualAlloc(NULL,
    4 * 1024 * 1024,
    MEM_64K_PAGES | MEM_RESERVE,
    XMEM_CPU | XMEM_MAPPABLE,
    PAGE_READWRITE);

PVOID ROAddress = XMemVirtualAlloc(NULL,
    4 * 1024 * 1024,
    MEM_2MB_PAGES | MEM_RESERVE,
    XMEM_CPU | XMEM_MAPPABLE,
    PAGE_READONLY);

// Map the physical pages into the 64k address reservation
XMemMapPhysicalPages(RWAddress, PageCount, PageArray);

// Map the physical pages into the 2MB address reservation
// Use only the first physical page of each 2MB run
ULONG_PTR PageArray2MB[2];
PageArray2MB[0] = PageArray[0];
PageArray2MB[1] = PageArray[32];
XMemMapPhysicalPages(ROAddress, 2, PageArray2MB);

memset(RWAddress, 0x17, 4 * 1024 * 1024);
assert (memcmp(RWAddress, ROAddress, 4 * 1024 * 1024)==0);

// Unmap the regions, the address reservation is preserved
XMemMapPhysicalPages(ROAddress, 2, NULL);
XMemMapPhysicalPages(RWAddress, 64, NULL);

// Release the physical pages back to the MM
XMemFreePhysicalPages(PageCount, PageArray);

// Release the two reserved address regions
VirtualFree(RWAddress, 0, MEM_RELEASE);
VirtualFree(ROAddress, 0, MEM_RELEASE);
```

## Requirements

**Header:** xmem.h

**Library:** xmem.lib

**Supported platforms:** XBOX One family consoles and XBOX Series consoles

## See also

[XMem reference](/reference/system/xmem/xmem_members)\
[XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc)\
<a href="https://learn.microsoft.com/en-us/windows/desktop/api/memoryapi/nf-memoryapi-virtualfree">VirtualFree</a>\
[XMemFreePhysicalPages](/reference/system/xmem/functions/xmemfreephysicalpages)


## Related topics

- [Working with the Microsoft GDK Game OS memory manager](/build/console-features/memory/system-memory-working.md)
- [XMemMapPhysicalPagesScatter](/reference/system/xmem/functions/xmemmapphysicalpagesscatter.md)
- [XMemFreePhysicalPages](/reference/system/xmem/functions/xmemfreephysicalpages.md)
- [Map](/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public.md)
- [PAGE 106 · Accessible web content and applications](/build/game-principles/accessibility/page/page-106-web-content-applications.md)