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

Mapeia páginas alocadas por [XMemAllocatePhysicalPages](/pt-BR/reference/system/xmem/functions/xmemallocatephysicalpages) no espaço de endereço virtual.

## Sintaxe

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

### Parâmetros

*VirtualAddress*   \_In\_\
Tipo: PVOID

Endereço no qual as páginas devem ser mapeadas.

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

Número de entradas em *PageArray*.

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

Matriz de números de quadros de página que representam as páginas a serem mapeadas.

### Valor retornado

Tipo: PVOID

Endereço virtual no qual as páginas físicas foram mapeadas ou NULL se houver uma falha de mapeamento.

No caso de uma falha de mapeamento, chame <a href="https://msdn.microsoft.com/library/windows/desktop/ms679360(v=vs.85).aspx">GetLastError</a> para obter informações de erro estendidas.

## Comentários

O intervalo de endereços virtuais deve ser reservado anteriormente por uma chamada para [XMemVirtualAlloc](/pt-BR/reference/system/xmem/functions/xmemvirtualalloc) com **MEM\_RESERVE**, um tamanho de página de **MEM\_64K\_PAGES** ou **MEM\_2MB\_PAGES** e o sinalizador **XMEM\_MAPPABLE**. Reservas de endereço **MEM\_PHYSICAL** feitas por VirtualAlloc não poderão ser usadas para mapear essa memória.

Se o intervalo de endereços virtuais já tiver páginas mapeadas, elas serão desmapeadas. Além disso, NULL pode ser especificado para PageArray para descomprometer a região de memória.

**XMemMapPhysicalPages** pode ser usado para mapear as mesmas páginas físicas várias vezes no espaço de endereço virtual. Se as páginas forem mapeadas várias vezes, os vários mapeamentos deverão especificar atributos de cache idênticos (coerente com a CPU é implícito se nenhum atributo de cache for fornecido; caso contrário, a lista é **PAGE\_NOCACHE** ou **PAGE\_WRITECOMBINE**).

<Note>Ao mapear páginas físicas na memória reservada com MEM\_2MB\_PAGES, as páginas físicas devem ter sido alocadas com XMEM\_2MB\_CLUSTERS. O parâmetro PageArray deve conter apenas a primeira página física de cada cluster de 2 MB.</Note>

Exemplo:

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

## Requisitos

**Cabeçalho:** xmem.h

**Biblioteca:** xmem.lib

**Plataformas com suporte:** consoles da família XBOX One e consoles XBOX Series

## Confira também

[Referência de XMem](/pt-BR/reference/system/xmem/xmem_members)\
[XMemVirtualAlloc](/pt-BR/reference/system/xmem/functions/xmemvirtualalloc)\
<a href="https://learn.microsoft.com/en-us/windows/desktop/api/memoryapi/nf-memoryapi-virtualfree">VirtualFree</a>\
[XMemFreePhysicalPages](/pt-BR/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)