MmMapLockedPagesSpecifyCache

The MmMapLockedPagesSpecifyCache routine maps the physical pages that are described by an MDL, and allows the caller to specify the cache behavior of the mapped memory.

NTKERNELAPI PVOID
  MmMapLockedPagesSpecifyCache(
    IN PMDL  MemoryDescriptorList,
    IN KPROCESSOR_MODE  AccessMode,
    IN MEMORY_CACHING_TYPE  CacheType,
    IN PVOID  BaseAddress,
    IN ULONG  BugCheckOnFailure,
    IN MM_PAGE_PRIORITY  Priority
    );

Parameters

MemoryDescriptorList

Specifies the MDL to be mapped. The caller must already have probed and locked the MDL by using the MmProbeAndLockPages routine.

AccessMode

Specifies the access mode in which to map the MDL: KernelMode or UserMode. Almost all drivers should use KernelMode.

CacheType

Specifies a MEMORY_CACHING_TYPE value, which indicates the type of caching allowed for the MDL.

BaseAddress

If AccessMode = UserMode, this parameter specifies the starting user address to map the MDL to, or 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

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

Indicates the importance of success when PTEs are scarce. For a description of the possible values for Priority, seeMmGetSystemAddressForMdlSafe.

Return Value

MmMapLockedPagesSpecifyCache returns the starting address of the mapped pages. If the pages cannot be mapped and BugCheckOnFailure is FALSE, the routine returns NULL.

Headers

Declared in ntddk.h. Include ntddk.h.

Comments

Use MmUnmapLockedPages to unmap the physical pages that were mapped by MmMapLockedPagesSpecifyCache.

If AccessMode is KernelMode and MmMapLockedPagesSpecifyCache cannot map the specified pages, the routine returns NULL (if BugCheckOnFailure = FALSE), or the 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 caller must be running at IRQL <= APC_LEVEL. If AccessMode is KernelMode, the caller must be running at IRQL <= DISPATCH_LEVEL.

See Also

MmUnmapLockedPages