> ## 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. # XMemVirtualAlloc > XMemVirtualAlloc # XMemVirtualAlloc Reserva, confirma ou altera o estado de uma região de páginas no espaço de endereço virtual do processo de chamada. Ao contrário do VirtualAlloc padrão do Win32, *não* há garantia de que a memória alocada por essa função seja inicializada automaticamente com zero. ## Sintaxe ```cpp theme={null} PVOID XMemVirtualAlloc( PVOID BaseAddress, SIZE_T Size, DWORD AllocationType, ULONGLONG XMemFlags, DWORD PageProtection ) ``` ### Parâmetros *BaseAddress* \_In\_opt\_
Tipo: PVOID O endereço inicial da região a ser alocada. Se a memória estiver sendo reservada, o endereço especificado será arredondado para baixo até o múltiplo mais próximo da granularidade de alocação (4K, 64K ou 2MB no XBOX). Se a memória já estiver reservada e estiver sendo confirmada, o endereço será arredondado para baixo até o próximo limite de página. Se esse parâmetro for NULL, o sistema determinará onde alocar a região.
*Size* \_In\_
Tipo: SIZE\_T O tamanho da região, em bytes. Se o parâmetro *BaseAddress* for NULL, esse valor será arredondado para cima até o próximo limite de página. Caso contrário, as páginas alocadas incluirão todas as páginas que contêm um ou mais bytes no intervalo de *BaseAddress* até *BaseAddress*+*Size*. Isso significa que um intervalo de 2 bytes que ultrapassa um limite de página faz com que ambas as páginas sejam incluídas na região alocada.
*AllocationType* \_In\_
Tipo: DWORD O tipo de alocação de memória. Esse parâmetro deve conter um dos valores a seguir. | Valor | Significado | | | - | - | - | | **MEM\_COMMIT**
0x00001000 | Aloca encargos de memória (do tamanho total da memória) para as páginas de memória reservadas especificadas. Para reservar e confirmar páginas em uma única etapa, chame **XMemVirtualAlloc** com \`MEM\_COMMIT | MEM\_RESERVE\`.
A tentativa de confirmar um intervalo de endereços específico especificando **MEM\_COMMIT** sem **MEM\_RESERVE** e um *BaseAddress* não NULL falha, a menos que todo o intervalo já tenha sido reservado. O código de erro resultante é **ERROR\_INVALID\_ADDRESS**.
Uma tentativa de confirmar uma página que já está confirmada não faz a função falhar. Isso significa que você pode confirmar páginas sem primeiro determinar o estado de confirmação atual de cada página. | | **MEM\_RESERVE**
0x00002000 | Reserva um intervalo do espaço de endereço virtual do processo sem alocar nenhum armazenamento físico real na memória. Você pode confirmar páginas reservadas em chamadas subsequentes para a função **XMemVirtualAlloc** ou mapear páginas físicas diretamente usando **XMemMapPhysicalPages**.
Outras funções de alocação de memória, como **malloc** e **new**, não podem usar um intervalo de memória reservado até que ele seja liberado.

Observe que o novo gerenciador de memória do *Microsoft Game Development Kit (GDK)* no XBOX exige configurações de proteção de página e de coerência de cache no momento da reserva, o que é uma mudança em relação à versão anterior do sistema operacional do XBOX. | | | **MEM\_RESERVE\_PLACEHOLDER**
0x00040000 | Um espaço reservado reserva endereços virtuais, mas não vincula o VA a um tamanho de página ou a uma proteção de página. O tamanho de página e a proteção de página são selecionados ao substituir o espaço reservado por uma reserva ou confirmação real usando **MEM\_REPLACE\_PLACEHOLDER**. Para criar um espaço reservado, chame **XMemVirtualAlloc** com **MEM\_RESERVE \| MEM\_RESERVE\_PLACEHOLDER** e PageProtection definido como **PAGE\_NOACCESS**. Usar **MEM\_RESERVE\_PLACEHOLDER** sempre retornará um endereço alinhado a 2MB para garantir que ele possa ser usado com **MEM\_2MB\_PAGES** no futuro. No entanto, depois de reservado, o espaço reservado pode ser dividido em qualquer granularidade (4K, 64K ou 2MB) usando VirtualFree com **MEM\_RELEASE \| MEM\_PRESERVE\_PLACEHOLDER**. | | | **MEM\_REPLACE\_PLACEHOLDER**
0x00004000 | Substitui um espaço reservado por uma alocação privada normal. Ao substituir um espaço reservado, BaseAddress e Size devem corresponder exatamente aos do espaço reservado. Depois de substituir um espaço reservado por uma alocação privada, para liberar essa alocação de volta para um espaço reservado, consulte o parâmetro **dwFreeType** de **VirtualFree** e **VirtualFreeEx**. | | Esse parâmetro também pode especificar os valores a seguir, conforme indicado. | Valor | Significado | | - | - | | **MEM\_2MB\_PAGES**
0x20000000 | Especifica um tamanho de página de 2MB. | | **MEM\_64K\_PAGES**
0x20400000 | Especifica um tamanho de página de 64K. | Para títulos ERA, **MEM\_LARGE\_PAGES** representava páginas de 64K e, no Windows desktop, representa páginas de 2MB. Devido à ambiguidade, ele foi removido do *Microsoft Game Development Kit (GDK)*.
*XMemFlags* \_In\_
Tipo: ULONGLONG Usado no XBOX para obter determinados tipos de memória especializados. Esse parâmetro deve conter um dos valores a seguir. | Valor | Significado | | - | - | | **XMEM\_CPU**
0x00000001 | Aloca memória acessível somente pela CPU. | | **XMEM\_GRAPHICS**
0x00000003 | Aloca memória acessível tanto pela CPU quanto pela GPU. Qualquer memória confirmada com **XMEM\_GRAPHICS** será mapeada nas tabelas de páginas da GPU. | | **XMEM\_GRAPHICS\_32BIT\_ADDRESS**
0x00000007 | Especifica que o endereço atribuído automaticamente está nos 4GB inferiores do espaço de endereço. A memória confirmada usando esse sinalizador também é acessível pela GPU. | No XBOX, é possível alocar memória com um endereço de memória virtual restrito que garante que os bits superiores não sejam usados. Usar qualquer um dos valores a seguir restringirá o endereço ao uso do número de bits indicado. **XMEM\_40BIT\_ADDRESS** (0x00007000ULL), **XMEM\_41BIT\_ADDRESS** (0x00006000ULL), **XMEM\_42BIT\_ADDRESS** (0x00005000ULL), **XMEM\_43BIT\_ADDRESS** (0x00004000ULL), **XMEM\_44BIT\_ADDRESS** (0x00003000ULL), **XMEM\_45BIT\_ADDRESS** (0x00002000ULL), **XMEM\_46BIT\_ADDRESS** (0x00001000ULL). A memória gráfica não pode ser alocada antes que o D3D12Device tenha sido criado ou que D3DConfigureVirtualMemory tenha sido chamado. Se for solicitada memória que será visível para a GPU, os títulos são *obrigados* a especificar também sinalizadores explícitos de proteção de página gráfica; não há mais um padrão baseado nas configurações de proteção de página da CPU. Essa é uma mudança em relação às versões anteriores do sistema operacional do XBOX. Esse parâmetro também pode especificar os valores a seguir, conforme indicado. | Valor | Significado | | - | - | | **XMEM\_TOOL**
0x00000010 | Especifica que as alocações são cobradas da partição de ferramentas em vez da partição do título. Esse sinalizador exige que **MEM\_2MB\_PAGES** ou **MEM\_64K\_PAGES** seja especificado no parâmetro *AllocationType*. | | **XMEM\_MAPPABLE**
0x00000020 | Especifica que a alocação é uma reserva de endereço a ser usada para mapeamentos de páginas físicas por meio de [XMemMapPhysicalPages](/pt-BR/reference/system/xmem/functions/xmemmapphysicalpages). Esse sinalizador exige que **MEM\_RESERVE** e **MEM\_2MB\_PAGES** ou **MEM\_64K\_PAGES** sejam especificados no parâmetro *AllocationType*. | Em dispositivos Anaconda e dispositivos Dante emulando Anaconda, ao usar o modo de memória de título Avançado, os parâmetros a seguir também podem ser aplicados. Esses parâmetros são ignorados em todos os outros casos. Esses sinalizadores são opcionais. Se não forem especificados, todas as alocações gráficas usarão por padrão XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_PREFERRED e todas as outras alocações usarão por padrão XMEM\_STANDARD\_BANDWIDTH\_PREFERRED. | Valor | Significado | | - | - | | **XMEM\_STD\_BW\_REQ** ou
**XMEM\_STANDARD\_BANDWIDTH\_REQUIRED**
0x00000080 | Especifica que as alocações devem ser atendidas usando memória de largura de banda padrão. | | **XMEM\_STD\_BW\_PREF** ou
**XMEM\_STANDARD\_BANDWIDTH\_PREFERRED**
0x00000180 | Especifica que as alocações devem preferir memória de largura de banda padrão e só usar memória de largura de banda ideal para GPU se a memória de largura de banda padrão estiver esgotada. | | **XMEM\_GPU\_OPTBW\_REQ** ou
**XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_REQUIRED**
0x00000280 | Especifica que as alocações devem ser atendidas usando memória de largura de banda ideal para GPU. | | **XMEM\_GPU\_OPTBW\_PREF** ou
**XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_PREFERRED**
0x00000380 | Especifica que as alocações devem preferir memória de largura de banda ideal para GPU e só usar memória de largura de banda padrão se a memória de largura de banda ideal para GPU estiver esgotada. | O parâmetro *XMemFlags* inclui uma marca opcional de código de quatro caracteres. Os caracteres podem ser qualquer um de a-z, A-Z, 0-9 e \$. A função [XMemMakeTag](/pt-BR/reference/system/xmem/functions/xmemmaketag) pode ser usada para construir a codificação correta do valor da marca na posição de bit correta. A marca só pode ser associada a regiões de memória confirmadas, não a reservas. Essa marca de código de quatro caracteres será representada pelos 24 bits superiores do parâmetro. A marca pode ser recuperada por meio de [XMemVirtualQuery](/pt-BR/reference/system/xmem/functions/xmemvirtualquery) e também será mostrada na análise de memória do PIX. Exemplo: ```cpp theme={null} PVOID mem = XMemVirtualAlloc(NULL, size, MEM_64K_PAGES | MEM_COMMIT, XMemMakeTag('Fred') | XMEM_CPU, PAGE_READWRITE); ```
*PageProtection* \_In\_
Tipo: DWORD A proteção de memória para a região de páginas a ser alocada. Se as páginas estiverem sendo confirmadas, você poderá especificar qualquer uma das Constantes de Proteção de Memória. Os seguintes valores específicos do XBOX são permitidos para o parâmetro *PageProtection*, e um deles é obrigatório quando **XMEM\_GRAPHICS** ou **XMEM\_GRAPHICS\_32BIT\_ADDRESS** é especificado. Esse requisito é uma mudança em relação à versão anterior do sistema operacional do XBOX. Esses valores também podem ser especificados para outras funções de gerenciamento de memória (por exemplo, VirtualProtect) para endereços de memória em intervalos que foram alocados com **XMEM\_GRAPHICS**. | Valor | Significado | | - | - | | **PAGE\_GRAPHICS\_NOACCESS**
0x0800 | Especifica que a memória não será acessível na GPU. | | **PAGE\_GRAPHICS\_READONLY**
0x1000 | Especifica que a memória será somente leitura na GPU. | | **PAGE\_GRAPHICS\_READWRITE**
0x2000 | Especifica que a memória será de leitura e gravação na GPU. | | **PAGE\_GRAPHICS\_EXECUTE**
0x4000

**GRAPHICS\_EXECUTE\_READ**
0x8000

**PAGE\_GRAPHICS\_EXECUTE\_READWRITE**
0x10000 | Especifica que a memória será executável na GPU. Isso é necessário para buffers de comando. | Esse parâmetro também pode especificar o valor a seguir, conforme indicado. | Valor | Significado | | - | - | | **PAGE\_GRAPHICS\_COHERENT**
0x20000 | Especifica que a memória compartilhada com a GPU será mantida coerente entre os caches da CPU e da GPU. | | **PAGE\_GRAPHICS\_NOCACHE**
0x40000 | Especifica que a memória não é armazenada em cache no acesso pela GPU. Esse sinalizador só é aplicável em consoles XBOX Series X\|S. | ### Valor retornado Tipo: PVOID Se a função for bem-sucedida, o valor retornado será o endereço base da região de páginas alocada. Se a função falhar, o valor retornado será **NULL**. Para obter informações de erro estendidas, chame GetLastError. ## Comentários Cada página tem um Estado de Página associado. A função **XMemVirtualAlloc** pode executar as seguintes operações: * Confirmar uma região de páginas reservadas * Reservar uma região de páginas livres * Reservar e confirmar simultaneamente uma região de páginas livres **XMemVirtualAlloc** não pode reservar uma página reservada. Ela pode confirmar uma página que já está confirmada. Isso significa que você pode confirmar um intervalo de páginas, independentemente de elas já terem sido confirmadas, e a função não falhará. Você pode usar **XMemVirtualAlloc** para reservar um bloco de páginas e, em seguida, fazer chamadas adicionais para **XMemVirtualAlloc** para confirmar páginas individuais do bloco reservado. Isso permite que um processo reserve um intervalo do seu espaço de endereço virtual sem consumir armazenamento físico até que ele seja necessário. Se o parâmetro *BaseAddress* não for **NULL**, a função usará os parâmetros *BaseAddress* e *Size* para calcular a região de páginas a ser alocada. O estado atual de todo o intervalo de páginas deve ser compatível com o tipo de alocação especificado pelo parâmetro *AllocationType*. Caso contrário, a função falhará e nenhuma das páginas será alocada. Esse requisito de compatibilidade não impede a confirmação de uma página já confirmada, conforme mencionado anteriormente. A função **XMemVirtualAlloc** pode ser usada para reservar uma região de memória no espaço de endereço virtual do processo de chamada designada para o mapeamento de páginas físicas. Essa região de memória pode então ser usada para mapear páginas físicas para dentro e para fora da memória virtual, conforme exigido pelo aplicativo. Os valores **MEM\_RESERVE** e **MEM\_64K\_PAGES** devem ser definidos no parâmetro *AllocationType*; o valor **MEM\_COMMIT** não deve ser definido. **XMEM\_MAPPABLE** deve ser definido no parâmetro *XMemFlags*. O espaço de endereço reservado dessa forma é confirmado usando a API [XMemMapPhysicalPages](/pt-BR/reference/system/xmem/functions/xmemmapphysicalpages). A função VirtualFree pode cancelar a confirmação de uma página confirmada, liberando o armazenamento da página, ou pode simultaneamente cancelar a confirmação e liberar uma página confirmada. Ela também pode liberar uma página reservada, tornando-a uma página livre. Além de fornecer extensões para características de memória específicas do XBOX, essa API diverge de VirtualAlloc por não impor um contrato de que a memória retornada seja garantidamente inicializada com zero. **XMemVirtualAlloc** também não garante a preservação do conteúdo anterior da memória. A maioria dos casos de uso de **XMemVirtualAlloc** em jogos envolve a obtenção de memória gráfica (que normalmente não se beneficia da inicialização com zero) ou a adição de memória a implementações de heap, que obtêm pouco valor útil com a inicialização com zero. Além disso, é trivial para um chamador implementar a inicialização com zero da memória retornada no momento de sua escolha. Ao não impor essa garantia do VirtualAlloc, a implementação de **XMemVirtualAlloc** tem mais flexibilidade para oferecer maior desempenho. **XMemVirtualAlloc** também diverge de VirtualAlloc no sentido de que a memória obtida por meio dessa chamada de API fica disponível imediatamente. Por outro lado, os endereços de memória retornados por VirtualAlloc serão preenchidos com páginas físicas somente no primeiro acesso, por meio de uma operação de falha de página dispendiosa. Espera-se que a memória alocada com **XMemVirtualAlloc** seja liberada com VirtualFree. Os sinalizadores de proteção de página **PAGE\_NOCACHE** e **PAGE\_WRITECOMBINE** são fixados no momento da reserva da memória e não podem ser alterados durante uma solicitação de confirmação posterior. Qualquer tentativa de alterar o status de um desses sinalizadores quando a memória for confirmada será ignorada silenciosamente. A confirmação da memória será bem-sucedida, mas a memória terá o estado original desses sinalizadores. Exemplos: ```cpp theme={null} // Allocate standard CPU only memory, using default (4K) pages PVOID cpuMemory = XMemVirtualAlloc (NULL, 1024 * 1024, MEM_RESERVE | MEM_COMMIT, XMEM_CPU, PAGE_READWRITE); ``` ```cpp theme={null} // Allocate 1MB of tooling memory using 64K pages PVOID cpu64kmemory = XMemVirtualAlloc (NULL, 1024 * 1024, MEM_64K_PAGES | MEM_RESERVE | MEM_COMMIT, XMEM_TOOL | XMEM_CPU, PAGE_READWRITE); ``` ```cpp theme={null} // Allocate 2MB graphics memory PVOID gfx64kmemory = XMemVirtualAlloc (NULL, 2 * 1024 * 1024, MEM_2MB_PAGES | MEM_RESERVE | MEM_COMMIT, XMEM_GRAPHICS, PAGE_READWRITE | PAGE_GRAPHICS_READONLY); ``` ```cpp theme={null} // Allocate 1MB of graphics memory using 64K pages in 32b address space PVOID gfxmemory32b = XMemVirtualAlloc (NULL, 1024 * 1024, MEM_64K_PAGES | MEM_RESERVE | MEM_COMMIT, XMEM_GRAPHICS_32BIT_ADDRESS, PAGE_READONLY | PAGE_GRAPHICS_READWRITE); ``` ```cpp theme={null} // Reserve 1GB of CPU visible VA space using 64K pages PVOID cpuReserve = XMemVirtualAlloc (NULL, 1024 * 1024 * 1024, MEM_64K_PAGES | MEM_RESERVE, XMEM_CPU, PAGE_READWRITE); // Now commit the first 2MB of the reservation PVOID cpuCommit = XMemVirtualAlloc (cpuReserve, 2 * 1024 * 1024, MEM_COMMIT, XMEM_CPU, PAGE_READWRITE); ``` ```cpp theme={null} // Reserve 4MB of visible VA space intended for direct physical page mapping // Note that physical pages are always 64KB and this reservation assumes // any allocations will be in 32 or 64 page (2MB\4MB) blocks PVOID physicalReserve = XMemVirtualAlloc (NULL, 4 * 1024 * 1024, MEM_2MB_PAGES | MEM_RESERVE, XMEM_GRAPHICS | XMEM_MAPPABLE, PAGE_READONLY | PAGE_GRAPHICS_COHERENT | PAGE_GRAPHICS_READWRITE); ``` ## Requisitos **Cabeçalho:** xmem.h **Biblioteca:** xmem.lib **Plataformas compatíveis:** consoles da família XBOX One e consoles XBOX Series ## Confira também [Referência de XMem](/pt-BR/reference/system/xmem/xmem_members)
[XMemMapPhysicalPages](/pt-BR/reference/system/xmem/functions/xmemmapphysicalpages)
VirtualFree ## Related topics - [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) - [Microsoft GDK ゲーム OS メモリ マネージャーの使用](/ja-jp/build/console-features/memory/system-memory-working.md)