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

# XMemAllocatePhysicalPages

> XMemAllocatePhysicalPages 會在 XBOX GDK 上為主體處理序配置連續的實體頁面，並提供頁面大小和快取能力的旗標。

# XMemAllocatePhysicalPages

為指定的主體處理序配置連續的實體頁面。

## 語法

```cpp theme={null}
BOOL XMemAllocatePhysicalPages(  
         ULONGLONG XMemFlags,  
         PULONG_PTR NumberOfPages,  
         PULONG_PTR PageArray  
)  
```

### 參數

*XMemFlags*   \_In\_<br />類型：ULONGLONG

指定已配置頁面的需求。

| 類型 | 詳細資料 |
| - | - |
| **XMEM\_2MB\_CLUSTERS**<br />0x20000000 | 要求已配置的頁面以 32 個連續頁面 (2MB) 為一組傳回。每個 32 頁的叢集都會從 2MB 實體對齊開始。使用此旗標時，NumberOfPages 必須是 32 的倍數。 |

在 Anaconda 裝置和模擬 Anaconda 的 Dante 裝置上，使用進階遊戲記憶體模式時，也可以套用下列參數。在所有其他情況下，這些參數都會被忽略。

| 值 | 意義 |
| - | - |
| **XMEM\_STD\_BW\_REQ** 或 <br />**XMEM\_STANDARD\_BANDWIDTH\_REQUIRED**<br />0x00000080 | 指定配置必須使用標準頻寬記憶體來滿足。 |
| **XMEM\_STD\_BW\_PREF** 或 <br />**XMEM\_STANDARD\_BANDWIDTH\_PREFERRED**<br />0x00000180 | 指定配置應優先使用標準頻寬記憶體，只有在標準頻寬記憶體耗盡時才使用 GPU 最佳頻寬記憶體。 |
| **XMEM\_GPU\_OPTBW\_REQ** 或 <br />**XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_REQUIRED**<br />0x00000280 | 指定配置必須使用 GPU 最佳頻寬記憶體來滿足。 |
| **XMEM\_GPU\_OPTBW\_PREF** 或 <br />**XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_PREFERRED**<br />0x00000380 | 指定配置應優先使用 GPU 最佳頻寬記憶體，只有在 GPU 最佳頻寬記憶體耗盡時才使用標準頻寬記憶體。 |

*NumberOfPages*   \_Inout\_<br />類型：PULONG\_PTR

變數的指標，該變數包含要配置的 64KB 頁面數目。完成時，會傳回\_實際\_配置的 64 KB 頁面數目。

*PageArray*   \_Out\_writes\_to\_(\*NumberOfPages,\*NumberOfPages)<br />類型：PULONG\_PTR

用來儲存已配置之 64KB 頁碼的使用者記憶體指標。用來儲存已配置記憶體之頁框編號的陣列指標。

所配置之陣列的大小至少應為 *NumberOfPages* 乘以 **ULONG\_PTR** 資料類型的大小。

請勿嘗試修改此緩衝區。其中包含作業系統資料，損毀可能會造成災難性的後果。緩衝區中的資訊對應用程式沒有用處。

### 傳回值

類型：BOOL

如果函式成功，傳回值為 **TRUE**。

配置的頁面可能少於要求的數量。呼叫端必須在傳回時檢查 *NumberOfPages* 參數的值，以查看配置了多少頁面。所有已配置的頁框編號會依序放入 *PageArray* 參數所指向的記憶體中。

如果函式失敗，傳回值為 **FALSE**，而且不會配置任何頁框。若要取得延伸錯誤資訊，請呼叫 <a href="https://msdn.microsoft.com/library/windows/desktop/ms679360(v=vs.85).aspx">GetLastError</a>。

## 備註

此 API 會配置實體記憶體頁面，以對應至指定處理序的區域內。

當應用程式可能想要預先配置許多段實體連續的頁面，並根據執行階段動態判斷的變動條件，將其細分為個別的 64KB 頁面時，**XMemAllocatePhysicalPages** 就很有用。**XMemAllocatePhysicalPages** 可配置實體頁面，而不將其放入虛擬位址空間。

**XMemAllocatePhysicalPages** 會以實體頁面配置要求的記憶體數量。無論是否使用 **XMEM\_2MB\_CLUSTERS**，傳回陣列中的頁碼都是指個別的 64KB 頁面。對應至使用 **MEM\_64K\_PAGES** 建立的保留區時，可以自由使用這些頁面。不過，對應至使用 **MEM\_2MB\_PAGES** 建立的保留區時，需要指定 **XMEM\_2MB\_CLUSTERS** 時所傳回的連續 2MB 叢集。對應至使用 **MEM\_2MB\_PAGES** 建立的保留區時，只會使用每個 2MB 叢集的第一個實體頁面。

傳回時，*NumberOfPages* 傳回的數目可能少於要求的頁面數目。

若要釋放以 **XMemAllocatePhysicalPages** 配置的頁面，請呼叫 [XMemFreePhysicalPages](/zh-TW/reference/system/xmem/functions/xmemfreephysicalpages)。

範例：

```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)<br />[XMemVirtualAlloc](/zh-TW/reference/system/xmem/functions/xmemvirtualalloc)<br />[XMemMapPhysicalPages](/zh-TW/reference/system/xmem/functions/xmemmapphysicalpages)<br />[XMemFreePhysicalPages](/zh-TW/reference/system/xmem/functions/xmemfreephysicalpages)


## Related topics

- [XMemFreePhysicalPages](/reference/system/xmem/functions/xmemfreephysicalpages.md)
- [XMemMapPhysicalPages](/reference/system/xmem/functions/xmemmapphysicalpages.md)