MmProbeAndLockPages function (wdm.h)
The MmProbeAndLockPages routine probes the specified virtual memory pages, makes them resident, and locks them in memory (say for a DMA transfer). This ensures the pages cannot be freed and reallocated while a device driver (or hardware) is still using them.
void MmProbeAndLockPages( PMDL MemoryDescriptorList, KPROCESSOR_MODE AccessMode, LOCK_OPERATION Operation );
[in, out] A pointer to an MDL that specifies a virtual memory buffer. If the routine successfully locks the pages in memory, the MDL is updated to describe the underlying physical pages.
[in] The access mode in which to probe the arguments, either KernelMode or UserMode.
[in] The type of operation for which the caller wants the access rights probed and the pages locked. Set this parameter to IoReadAccess, IoWriteAccess, or IoModifyAccess. IoReadAccess indicates that the driver can examine the contents of the buffer but cannot change the contents. IoWriteAccess and IoModifyAccess, which are equivalent, indicate that the driver has both read and write access to the buffer.
The highest-level driver in a chain of layered drivers that use direct I/O calls this routine. Drivers that use buffered I/O never call MmProbeAndLockPages.
MmProbeAndLockPages performs the following operations:
- If the specified memory range is paged to a backing store (disk, network, and so on), MmProbeAndLockPages makes it resident.
- The routine then confirms that the pages permit the operation specified by the Operation parameter.
- If the memory range permits the specified operation, the routine locks the pages in memory so that they cannot be paged out. Use the MmUnlockPages routine to unlock the pages.
- Finally, the routine updates the page frame number (PFN) array in the MDL to describe the locked physical pages.
If two or more MDLs describe the same physical page, the page can be locked multiple times—once for each MDL. The page is unlocked when the last MDL is set to the unlocked state.
A routine such as MmBuildMdlForNonPagedPool or IoBuildPartialMdl updates an MDL to describe pages that are either nonpageable or already locked. A call to MmProbeAndLockPages or MmUnlockPages to lock or unlock such an MDL is not allowed.
Calls to MmProbeAndLockPages must be enclosed in a try/except block. If the pages do not support the specified operation, the routine raises the STATUS_ACCESS_VIOLATION or other exceptions. For more information, see Handling Exceptions.
Callers of MmProbeAndLockPages must be running at IRQL <= APC_LEVEL for pageable addresses, or at IRQL <= DISPATCH_LEVEL for nonpageable addresses.
This routine does not provide any guarantees about the virtual address that describes these pages (that is, the virtual address might be unmapped, reused, and so on). However, the physical pages are guaranteed to be locked on successful return.
|Minimum supported client||Available starting with Windows 2000.|
|Header||wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)|
|IRQL||See Remarks section.|
|DDI compliance rules||HwStorPortProhibitedDDIs|