MapTitlePhysicalPages

Maps pages allocated by AllocateTitlePhysicalPages into the virtual address space.

Syntax

PVOID MapTitlePhysicalPages(
         PVOID VirtualAddress,
         ULONG_PTR NumberOfPages,
         ULONG flAllocationType,
         ULONG flProtect,
         PULONG_PTR PageArray
)

Parameters

VirtualAddress
Type: PVOID

[in] A pointer to the starting address of the region of memory to remap.

NumberOfPages
Type: ULONG_PTR

[in] Specifies the number of 64 KB pages (whose addresses are supplied in PageArray) to map. The virtual address range is contiguous starting at lpAddress.

flAllocationType
Type: ULONG

[in] Must include either MEM_LARGE_PAGES or MEM_4MB_PAGES, depending on whether 64 KB of 4 MB pages (respectively) are desired.

flProtect
Type: ULONG

[in] Specifies cache policy in addition to read/write protections.

PageArray
Type: PULONG_PTR

[in, optional] A pointer to an array to store the page frame numbers of the allocated memory. The size of the array that is allocated should be at least the NumberOfPages times the size of the ULONG_PTR data type. Must not be NULL.

Return value

Type: PVOID

The mapped virtual address, or NULL if the function fails.

Remarks

If lpAddress is NULL, MapTitlePhysicalPages will select a virtual address for mapping.

If 4 MB alignment is requested, NumberOfPages must specify a multiple of 4 MB (i.e., 64 pages), and the physical pages must represent contiguous and aligned 4 MB runs, or the call will fail.

If the lpAddress parameter is not NULL, MapTitlePhysicalPages will attempt to map the supplied pages into the specified address range. If the address range was previously reserved by a call to VirtualAlloc or an earlier call to MapTitlePhysicalPages, the presence or absence of MEM_LARGE_PAGES must match the presence or absence of MEM_LARGE_PAGES in the previous call, or an error will be returned. If any pages are already mapped into the virtual address range, then they will be unmapped in favor of the newly supplied addresses. If the unmapped pages were allocated by VirtualAlloc, they will be freed at this time; if the unmapped pages were allocated by AllocateUserPhysicalPages, they will remain allocated to the process.

If MEM_GRAPHICS is specified, then VirtualAddress must be NULL or in the range 4 GB to 1 TB. If MEM_GRAPHICS is not specified, VirtualAddress must be NULL or in the range 1 TB to 8 TB.

PageArray must not be NULL. Callers wishing to unmap pages should use VirtualFree with MEM_DECOMMIT.

If VirtualFree is used to decommit any pages mapped with MapTitlePhysicalPages, they will not be freed until FreeTitlePhysicalPages is called.

VirtualProtect can be called to change the protection of any pages mapped with MapTitlePhysicalPages. In this case, the protection change will be rounded either to a multiple of 64 KB or 4 MB, depending on whether the memory was mapped with MEM_LARGE_PAGES or MEM_4MB_PAGES.

MapTitlePhysicalPages may be used to map the same physical pages multiple times in the virtual address space.

MapTitlePhysicalPages will map the pages in the CPU’s address space using 4 KB page table entries, unless MEM_LARGE_PAGES is specified, in which case it will map the pages using 2 MB page table entries.

If pages are mapped multiple times, the multiple mappings must specify identical caching attributes (PAGE_NOCACHE, PAGE_WRITECOMBINE, or PAGE_GPU_COHERENT). There is no restriction on modifying the buffer in PageArray. Callers are free to combine pages as desired, as long as the page numbers were returned by a previous call to AllocateTitlePhysicalPages.

Requirements