The MmMapLockedPagesSpecifyCache routine maps the physical pages that are described by an MDL to a virtual address, and enables the caller to specify the cache attribute that is used to create the mapping.
PVOID MmMapLockedPagesSpecifyCache( _In_ PMDLX MemoryDescriptorList, _In_ KPROCESSOR_MODE AccessMode, _In_ MEMORY_CACHING_TYPE CacheType, _In_opt_ PVOID BaseAddress, _In_ ULONG BugCheckOnFailure, _In_ MM_PAGE_PRIORITY Priority );
- MemoryDescriptorList [in]
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. For mappings to user space, MDLs that are built by the MmBuildMdlForNonPagedPool routine can be used.
- AccessMode [in]
Specifies the access mode in which to map the MDL: KernelMode or UserMode. Almost all drivers should use KernelMode.
- CacheType [in]
Specifies a MEMORY_CACHING_TYPE value, which indicates the cache attribute to use to map the MDL. For more information, see the following Remarks section.
- BaseAddress [in, optional]
If AccessMode = UserMode, this parameter specifies the starting user virtual address to map the MDL to, or set to NULL to allow the system to choose the starting address. The system might round down the requested address to fit address boundary requirements, so callers must check the return value.
- BugCheckOnFailure [in]
Specifies the behavior of the routine for AccessMode = KernelMode if the MDL cannot be mapped because of low system resources. If TRUE, the system issues a bug check. If FALSE, the routine returns NULL. Drivers must set this parameter to FALSE.
- Priority [in]
Indicates the importance of success when PTEs are scarce. For a description of the possible values for Priority, see MmGetSystemAddressForMdlSafe.
MmMapLockedPagesSpecifyCache returns the starting address of the mapped pages. If the pages cannot be mapped and BugCheckOnFailure is FALSE, the routine returns NULL.
Use MmUnmapLockedPages to unmap the physical pages that were mapped by MmMapLockedPagesSpecifyCache.
If AccessMode is KernelMode, and if MmMapLockedPagesSpecifyCache cannot map the specified pages, the routine returns NULL (if BugCheckOnFailure = FALSE), or the operating system issues a bug check (if BugCheckOnFailure = TRUE).
If AccessMode is UserMode and the specified pages cannot be mapped, the routine raises an exception. Callers that specify UserMode must wrap the call to MmMapLockedPagesSpecifyCache in a try/except block. For more information, see Handling Exceptions.
If AccessMode is UserMode, the routine returns a user address that is valid in the context of the process in which the driver is running. For example, if a 64-bit driver is running in the context of a 32-bit application, the buffer is mapped to an address in the 32-bit address range of the application.
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.
A driver must not try to create more than one system-address-space mapping for an MDL. Additionally, because an MDL that is built by the MmBuildMdlForNonPagedPool routine is already mapped to the system address space, a driver must not try to map this MDL into the system address space again by using the MmMapLockedPagesSpecifyCache routine (although creating user-address-space mappings is allowed). If it is not known whether a locked-down MDL already has a system-address-space mapping, a driver can use the MmGetSystemAddressForMdlSafe macro instead of MmMapLockedPagesSpecifyCache. If the MDL is already mapped into the system address space, MmGetSystemAddressForMdlSafe will return the existing system-address-space mapping instead of creating a new mapping.
Warning A driver that maps kernel memory into user address space must avoid exposing potentially sensitive kernel data to untrusted processes. Uninitialized buffers, such as buffers that are allocated from pool, must be explicitly filled with zeros before they are mapped. In addition, the size of a user-mode buffer that is allocated from pool must be a multiple of the virtual memory page size to prevent any part of the pages in the buffer from being used for other allocations. Finally, buffers must not be freed back to the pool while they are still mapped to user address space.
If AccessMode is UserMode, the caller must be running at IRQL <= APC_LEVEL. If AccessMode is KernelMode, the caller must be running at IRQL <= DISPATCH_LEVEL.
|Available starting with Windows 2000.|
|See Remarks section.|
DDI compliance rules
Build date: 2/11/2014