MapUserPhysicalPages

The MapUserPhysicalPages function maps previously allocated physical memory pages at the specified address within an Address Windowing Extensions (AWE) region.

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

BOOL MapUserPhysicalPages(
  PVOID lpAddress,         // starting address of region
  ULONG_PTR NumberOfPages, // size of physical memory
  PULONG_PTR UserPfnArray  // array of page frame numbers
);

Parameters

lpAddress

[in] Pointer to the starting address of the region of memory to remap. The value of lpAddress must be within the address range returned by the VirtualAlloc function when the AWE region was allocated.

NumberOfPages

[in] Specifies the size, in pages, of the physical memory (and virtual address space) to establish translations for. 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 specified in AllocateUserPhysicalPages.

UserPfnArray

[in] Specifies the address of an array of physical page frame numbers. These frames will be mapped by the argument lpAddress upon return from this function. The size of the memory allocated should be at least NumberOfPages times the size of the data type ULONG_PTR.

Do not attempt to modify this buffer. It contains operating system data, corruption of which could be catastrophic. There is no information in it that is useful to your application.

Specifying NULL for this parameter results in the specified address range being unmapped. (The specified physical pages are not freed. You must call FreeUserPhysicalPages to free them.)

Return Values

If the function succeeds, the return value is TRUE.

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

Remarks

Any number of physical memory pages can be specified, provided the memory would not extend outside the virtual address space allocated by VirtualAlloc. 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 specified in AllocateUserPhysicalPages.

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

Physical pages can reside at any physical address. You should make no assumptions about the contiguity of the physical pages.

To simply 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. Upon return from this function, all threads on all processors are guaranteed to see the correct mapping.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

Memory Management Overview, Memory Management Functions, Address Windowing Extensions, AllocateUserPhysicalPages, FreeUserPhysicalPages, MapUserPhysicalPagesScatter