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

# XMemMapPhysicalPages

> XMemMapPhysicalPages

# XMemMapPhysicalPages

將 [XMemAllocatePhysicalPages](https://docs.xbox.com/zh-TW/reference/system/xmem/functions/xmemallocatephysicalpages.md) 所配置的頁面對應至虛擬位址空間。

## 語法

```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。

如果對應失敗，請呼叫 [GetLastError](https://msdn.microsoft.com/library/windows/desktop/ms679360\(v=vs.85\).aspx) 以取得延伸錯誤資訊。

## 備註

虛擬位址範圍必須先前已透過呼叫 [XMemVirtualAlloc](https://docs.xbox.com/zh-TW/reference/system/xmem/functions/xmemvirtualalloc.md) 保留，並搭配 **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 叢集的第一個實體頁面。

範例：

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


## Related topics

- [使用 Microsoft GDK Game OS 記憶體管理員](https://docs.xbox.com/zh-TW/build/console-features/memory/system-memory-working.md)
- [XMemMapPhysicalPagesScatter](https://docs.xbox.com/zh-TW/reference/system/xmem/functions/xmemmapphysicalpagesscatter.md)
- [XMemFreePhysicalPages](https://docs.xbox.com/zh-TW/reference/system/xmem/functions/xmemfreephysicalpages.md)
- [Map](https://docs.xbox.com/zh-TW/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public.md)
- [ApuMapApuAddress](https://docs.xbox.com/zh-TW/reference/audio/apu/functions/apumapapuaddress.md)