> ## 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](/zh-TW/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](/zh-TW/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 參考](/zh-TW/reference/system/xmem/xmem_members)\
[XMemVirtualAlloc](/zh-TW/reference/system/xmem/functions/xmemvirtualalloc)\
<a href="https://learn.microsoft.com/en-us/windows/desktop/api/memoryapi/nf-memoryapi-virtualfree">VirtualFree</a>\
[XMemFreePhysicalPages](/zh-TW/reference/system/xmem/functions/xmemfreephysicalpages)


## Related topics

- [XMemMapPhysicalPages](/reference/system/xmem/functions/xmemmapphysicalpages.md)
- [Working with the Microsoft GDK Game OS memory manager](/build/console-features/memory/system-memory-working.md)
- [Trabajo con el administrador de memoria del sistema operativo de juego del Microsoft GDK](/es/build/console-features/memory/system-memory-working.md)
- [使用 Microsoft GDK 游戏 OS 内存管理器](/zh-CN/build/console-features/memory/system-memory-working.md)
- [Microsoft GDK Game OS 메모리 관리자 사용](/ko/build/console-features/memory/system-memory-working.md)