MapUserPhysicalPagesScatter

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

Unlike MapUserPhysicalPages, MapUserPhysicalPagesScatter allows "batch" mapping and unmapping of multiple regions.

BOOL MapUserPhysicalPagesScatter(
  PVOID *VirtualAddresses,  // starting address of region
  ULONG_PTR NumberOfPages,  // size of physical memory
  PULONG_PTR PageArray      // array of values
);

Parameters

VirtualAddresses

[in] Pointer to an array of starting addresses of the regions of memory to remap. Each entry in VirtualAddresses must be within the address range that the VirtualAlloc function returned when the AWE region was allocated. The value in NumberOfPages indicates the size of the array. Note that entries can be from multiple AWE regions.

NumberOfPages

[in] Specifies the size, in pages, of the physical memory (and virtual address space) to establish translations for. The array at VirtualAddresses specifies the virtual address range.

PageArray

[in] A non-NULL pointer to an array of values.

If this parameter is NULL, then every address in the VirtualAddresses array will be unmapped.

Otherwise, the array is used to indicate how each corresponding page in VirtualAddresses should be treated. A zero indicates that the corresponding entry in VirtualAddresses should be unmapped; any nonzero value that it has should be mapped.

The value in NumberOfPages indicates the size of the array.

Return Values

If the function succeeds, the return value is TRUE.

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

Remarks

You can specify any number of physical memory pages, 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 may be 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.

In a multiprocessor environment, this function maintains coherence of the hardware translation buffer. 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, MapUserPhysicalPages