MmMapLockedPagesWithReservedMapping function (wdm.h)
The MmMapLockedPagesWithReservedMapping routine maps all or part of an address range that was previously reserved by the MmAllocateMappingAddress routine.
Syntax
PVOID MmMapLockedPagesWithReservedMapping(
[in] PVOID MappingAddress,
[in] ULONG PoolTag,
[in] PMDL MemoryDescriptorList,
[in] __drv_strictTypeMatch(__drv_typeCond)MEMORY_CACHING_TYPE CacheType
);
Parameters
[in] MappingAddress
Pointer to the beginning of the reserved virtual memory range. This must be an address previously returned by MmAllocateMappingAddress.
[in] PoolTag
Specifies the pool tag for the reserved memory buffer. This must be identical to the value specified in the PoolTag parameter of the call to MmAllocateMappingAddress that reserved the buffer.
[in] MemoryDescriptorList
A pointer to the MDL that is to be mapped. This MDL must describe physical pages that are locked down. A locked-down MDL can be built by the MmProbeAndLockPages or MmAllocatePagesForMdlEx routine.
[in] CacheType
Specifies the MEMORY_CACHING_TYPE value to use to create the mapping.
Return value
MmMapLockedPagesWithReservedMapping returns a pointer to the beginning of the mapped memory, or NULL if the system could not map the memory. This routine returns NULL only if there is an error in the function parameters (for example, the driver's mapping address is not large enough to span the supplied MDL). This function is intended to enable drivers to make forward progress even in low-resource scenarios.
Remarks
The caller can use MmMapLockedPagesWithReservedMapping to map a subrange of the virtual memory range reserved by MmAllocateMappingAddress as follows:
Use IoAllocateMdl to allocate an MDL. The returned MDL is built using the specified starting address and size of the subrange of the virtual memory range to map.
Use MmProbeAndLockPages to lock down the physical pages described by the MDL obtained in step 1.
Use MmMapLockedPagesWithReservedMapping to actually map the virtual memory to the physical memory that was locked down in step 2. Note that the virtual address returned by this function does include the byte offset that the MDL specifies. However, the MappedSystemVa field of the MDL that is set by this function does not include the byte offset.
Once the caller does not need to access the memory, it unmaps the memory with MmUnmapReservedMapping. The caller can map and unmap the memory buffer as needed, and must unmap it prior to freeing the mapping range with MmFreeMappingAddress.
Note that the MappingAddress parameter specifies the beginning of the range of memory previously reserved by the caller, not the beginning of the memory subrange to be mapped. The caller specifies the starting address and length of the buffer when it allocates the MDL with IoAllocateMdl. The buffer must fit inside the reserved memory range, but it can be a strict subset.
The routine uses the CacheType parameter only if the pages that are described by the MDL do not already have a cache type associated with them. However, in nearly all cases, the pages already have an associated cache type, and this cache type is used by the new mapping. An exception to this rule is for pages that are allocated by MmAllocatePagesForMdl, which do not have a specific cache type associated with them. For such pages, the CacheType parameter determines the cache type of the mapping.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows XP and later versions of Windows. |
| Target Platform | Universal |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |
| DDI compliance rules | HwStorPortProhibitedDDIs(storport) |