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

将由 [XMemAllocatePhysicalPages](/reference/system/xmem/functions/xmemallocatephysicalpages) 分配的页映射到虚拟地址空间中。

## 语法

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

### 参数

*VirtualAddress*   \_In\_\
类型：PVOID

页应被映射到的地址。

*NumberOfPages*   \_In\_\
类型：ULONG\_PTR

*PageArray* 中的条目数。

*PageArray*   \_In\_reads\_opt\_(NumberOfPages)\
类型：PULONG\_PTR

表示要映射的页的页帧编号数组。

### 返回值

类型：PVOID

物理页已被映射到的虚拟地址；如果发生映射失败，则返回 NULL。

如果发生映射失败，请调用 <a href="https://msdn.microsoft.com/library/windows/desktop/ms679360(v=vs.85).aspx">GetLastError</a> 以获取扩展错误信息。

## 备注

必须先通过调用 [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) 并使用 **MEM\_RESERVE**、页大小为 **MEM\_64K\_PAGES** 或 **MEM\_2MB\_PAGES**，以及 **XMEM\_MAPPABLE** 标志来预留虚拟地址范围。由 VirtualAlloc 进行的 **MEM\_PHYSICAL** 地址预留不能用于映射此内存。

如果虚拟地址范围已经映射了页，它们将被取消映射。此外，可以为 PageArray 指定 NULL 以便取消提交该内存区域。

**XMemMapPhysicalPages** 可用于在虚拟地址空间中多次映射同一物理页。如果多次映射同一页，则多个映射必须指定相同的缓存属性（如果未提供缓存属性，则隐式为 CPU 一致；否则可选 **PAGE\_NOCACHE** 或 **PAGE\_WRITECOMBINE**）。

<Note>将物理页映射到用 MEM\_2MB\_PAGES 预留的内存中时，物理页必须使用 XMEM\_2MB\_CLUSTERS 进行分配。PageArray 参数只应包含每个 2MB 群集的第一个物理页。</Note>

示例：

```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);
```

## 要求

**头文件：** xmem.h

**库：** xmem.lib

**支持的平台：** XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[XMem 参考](/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

- [使用 Microsoft GDK 游戏 OS 内存管理器](/zh-CN/build/console-features/memory/system-memory-working.md)
- [XMemMapPhysicalPagesScatter](/zh-CN/reference/system/xmem/functions/xmemmapphysicalpagesscatter.md)
- [XMemFreePhysicalPages](/zh-CN/reference/system/xmem/functions/xmemfreephysicalpages.md)
- [Map](/zh-CN/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public.md)
- [DSTORAGE_REQUEST_OPTIONS](/zh-CN/reference/system/dstorage/structs/dstorage_request_options.md)