Função MapUserPhysicalPages (memoryapi.h)

Artigo
08/24/2023

Mapeia páginas de memória física alocadas anteriormente em um endereço especificado em uma região do AWE ( Address Windowing Extensions ).

Para executar o mapeamento em lotes e desmapear várias regiões, use a função MapUserPhysicalPagesScatter .

Windows de 64 bits em sistemas baseados em Itanium: Devido à diferença de tamanhos de página, MapUserPhysicalPages não tem suporte para aplicativos de 32 bits.

Sintaxe

BOOL MapUserPhysicalPages(
  [in] PVOID      VirtualAddress,
  [in] ULONG_PTR  NumberOfPages,
  [in] PULONG_PTR PageArray
);

Parâmetros

[in] VirtualAddress

Um ponteiro para o endereço inicial da região da memória a ser remapeada.

O valor de lpAddress deve estar dentro do intervalo de endereços que a função VirtualAlloc retorna quando a região do AWE ( Address Windowing Extensions ) é alocada.

[in] NumberOfPages

O tamanho da memória física e do espaço de endereço virtual para o qual estabelecer traduções, em páginas.

O intervalo de endereços virtuais é contíguo, começando em lpAddress. Os quadros físicos são especificados pelo UserPfnArray.

O número total de páginas não pode se estender do endereço inicial além do final do intervalo especificado em AllocateUserPhysicalPages.

[in] PageArray

Um ponteiro para uma matriz de números de quadro de página física.

Esses quadros são mapeados pelo argumento lpAddress no retorno dessa função. O tamanho da memória alocada deve ser pelo menos o NumberOfPages vezes o tamanho do tipo de dados ULONG_PTR.

Não tente modificar esse buffer. Ele contém dados do sistema operacional e a corrupção pode ser catastrófica. As informações no buffer não são úteis para um aplicativo.

Se esse parâmetro for NULL, o intervalo de endereços especificado será não mapeado. Além disso, as páginas físicas especificadas não são liberadas e você deve chamar FreeUserPhysicalPages para liberá-las.

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE.

Se a função falhar, o valor retornado será FALSE e nenhum mapeamento será feito— parcial ou não. Para obter informações de erro estendidas, chame GetLastError.

Comentários

As páginas físicas não são mapeadas, mas não são liberadas. Você deve chamar FreeUserPhysicalPages para liberar as páginas físicas.

Qualquer número de páginas de memória física pode ser especificado, mas a memória não deve se estender para fora do espaço de endereço virtual alocado por VirtualAlloc . Todos os mapas de endereços existentes são substituídos automaticamente pelas novas traduções e as traduções antigas não são mapeadas.

Não é possível mapear páginas de memória física fora do intervalo especificado em AllocateUserPhysicalPages. Você pode mapear várias regiões simultaneamente, mas elas não podem se sobrepor.

As páginas físicas podem estar localizadas em qualquer endereço físico, mas não fazem suposições sobre a contígua das páginas físicas.

Para desmapear o intervalo de endereços atual, especifique NULL como o parâmetro de matriz de página de memória física. Todas as páginas mapeadas no momento não são mapeadas, mas não são liberadas. Você deve chamar FreeUserPhysicalPages para liberar as páginas físicas.

Em um ambiente multiprocessador, essa função mantém a coerência do buffer de tradução de hardware. Ao retornar dessa função, todos os threads em todos os processadores têm a garantia de ver o mapeamento correto.

Para compilar um aplicativo que usa essa função, defina a macro _WIN32_WINNT como 0x0500 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Exemplos

Para obter um exemplo, consulte Exemplo de AWE.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	memoryapi.h (inclua Windows.h, Memoryapi.h)
Biblioteca	onecore.lib
DLL	Kernel32.dll