MapUserPhysicalPages function (memoryapi.h)

Article
07/27/2022

Maps previously allocated physical memory pages at a specified address in an Address Windowing Extensions (AWE) region.

To perform batch mapping and unmapping of multiple regions, use the MapUserPhysicalPagesScatter function.

64-bit Windows on Itanium-based systems: Due to the difference in page sizes, MapUserPhysicalPages is not supported for 32-bit applications.

Syntax

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

Parameters

[in] VirtualAddress

A pointer to the starting address of the region of memory to remap.

The value of lpAddress must be within the address range that the VirtualAlloc function returns when the Address Windowing Extensions (AWE) region is allocated.

[in] NumberOfPages

The size of the physical memory and virtual address space for which to establish translations, in pages.

The virtual address range is contiguous starting at lpAddress. The physical frames are specified by the UserPfnArray.

The total number of pages cannot extend from the starting address beyond the end of the range that is specified in AllocateUserPhysicalPages.

[in] PageArray

A pointer to an array of physical page frame numbers.

These frames are mapped by the argument lpAddress on return from this function. The size of the memory that is allocated should be at least the NumberOfPages times the size of the data type ULONG_PTR.

Do not attempt to modify this buffer. It contains operating system data, and corruption could be catastrophic. The information in the buffer is not useful to an application.

If this parameter is NULL, the specified address range is unmapped. Also, the specified physical pages are not freed, and you must call FreeUserPhysicalPages to free them.

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE and no mapping is done—partial or otherwise. To get extended error information, call GetLastError.

Remarks

The physical pages are unmapped but they are not freed. You must call FreeUserPhysicalPages to free the physical pages.

Any number of physical memory pages can be specified, but the memory must not extend outside the virtual address space that VirtualAlloc allocates. Any existing address maps are automatically overwritten with the new translations, and the old translations are unmapped.

You cannot map physical memory pages outside the range that is specified in AllocateUserPhysicalPages. You can map multiple regions simultaneously, but they cannot overlap.

Physical pages can be located at any physical address, but do not make assumptions about the contiguity of the physical pages.

To unmap the current address range, specify NULL as the physical memory page array parameter. Any currently mapped pages are unmapped, but are not freed. You must call FreeUserPhysicalPages to free the physical pages.

In a multiprocessor environment, this function maintains hardware translation buffer coherence. On return from this function, all threads on all processors are guaranteed to see the correct mapping.

To compile an application that uses this function, define the _WIN32_WINNT macro as 0x0500 or later. For more information, see Using the Windows Headers.

Examples

For an example, see AWE Example.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	memoryapi.h (include Windows.h, Memoryapi.h)
Library	onecore.lib
DLL	Kernel32.dll