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

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. 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 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 e também será mostrada na análise de memória do PIX. Exemplo:

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

// Allocate standard CPU only memory, using default (4K) pages
PVOID cpuMemory = XMemVirtualAlloc (NULL,
                                    1024 * 1024,
                                    MEM_RESERVE | MEM_COMMIT,
                                    XMEM_CPU,
                                    PAGE_READWRITE);

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

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

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

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

// 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
XMemMapPhysicalPages
VirtualFree

Porting

Build Paths

XMemVirtualAlloc

XMemVirtualAlloc

Sintaxe

Parâmetros

Valor retornado

Comentários

Requisitos

Confira também

​XMemVirtualAlloc

​Sintaxe

​Parâmetros

​Valor retornado

​Comentários

​Requisitos

​Confira também

XMemVirtualAlloc

Sintaxe

Parâmetros

Valor retornado

Comentários

Requisitos

Confira também