DevHelp VMLock
This service verifies accessibility to a region of memory and locks the memory region into physical memory. If the region is unavailable, the caller must specify whether VMLock should block until the region is available and locked, or return immediately.
Syntax
C
USHORT APIENTRY DevHelp_VMLock( ULONG Flags,
LIN LinearAddr,
ULONG Length,
LIN pPageList,
LIN pLockHandle,
PULONG PageListCount)
Assembler
MOV EBX,LinearAddress ; Linear Address of region to lock
MOV ECX,Length ; Count of bytes to be locked
MOV EDI,OFFSET pPageList ; Flat pointer to array of PageList_s structures
; filled by the call
MOV ESI,OFFSET pLockHandle ; Address of the 12-byte variable the lock handle
; will be placed in
MOV EAX,ActionFlags ; Actions to be performed for lock
; If bit 0 (0000001B) is set, the lock returns if
; the requested pages are not immediately
; available. If the bit is clear, the call
; blocks until the pages are available.
; If bit 1 (0000010B) is set, the pages that are
; to be locked must be physically contiguous.
; This should be used only by device drivers
; that are about to perform contiguous DMA
; operations on the object.
; If bit 2 (0000100B) is set, the locked pages must
; be below the 16MB address line. If this bit
; is clear, then the pages can be locked
; anywhere in memory.
; If bit 3 (0001000B) is set, then the physical
; device driver plans to write in the region
; of the segment. This will cause the dirty bit
; to be set in the page table entries because
; the physical device driver may be doing DMA to
; the pages, which does not set this bit.
; If the dirty bit is not set when writing to a
; page, then the data written to the page may be
; lost.
; If bit 4 (0010000B) is set, then the lock is
; needed for a long-term duration. This
; parameter would be used if the physical device
; driver intends to keep the lock on the object
; for greater than two seconds.
; If bit 5 (0100000B) is set, the region will be
; 'verify only' locked. This means that the
; page table mapping of this region cannot be
; removed or destructively modified (No free or
; decommit allowed in the region, cannot remove
; write permission). However, the region will
; not be physically locked in memory, the
; physical pages will retain their original
; status (swappable, discardable, etc...).
; This lock also does not force any pages to be
; present.
; Passing the returned lock handle info back to
; VMUnLock will release 'verify only' lock.
; The flags in bit positions 1 and 2 are invalid
; with this request. No physical addresses will
; be returned in lock 'verify' requests. Verify
; locks can be specified for short or long term.
; If bit 3 is set along with this bit, the
; memory will be verified for read/write access.
; If bit 3 is clear, only the read permission
; will be verified.
; All other bits must be clear.
MOV DL,DevHlp_VMLock
CALL [Device_Help]
Each PageList _ s structure describes a single physically
contiguous subregion of the physical memory that was locked . The format of the
PageList _ s structure is :
PageList _ s struc
pl _ PhysAddr DD ? ; Physical address of first byte in this sub - region
pl _ cb DD ? ; Number of contiguous bytes starting at pl _ PhysAddr
PageList _ s ends
Parameters
C
- Flags (ULONG)
- Actions to be performed for lock:
VMDHL_NOBLOCK - If bit 0 (00000001B) is set,
the lock returns if the requested pages are not
immediately available. If it is clear, the call
blocks until the pages are available.
VMDHL_CONTIGUOUS - If bit 1 (00000010B)
is set, the pages that are to be locked
must be physically contiguous. This should
only be used by device drivers that are about to
perform contiguous DMA operations on the object.
VMDHL_IGM - If bit 2 (00000100B) is set,
the locked pages must be below the 16MB address
line. If this bit is clear then the pages can be
locked anywhere in memory.
VMDHL_WRITE - If bit 3 (00001000B) is set,
then the physical device driver plans to write in
the region of the segment. This will cause the
dirty bit to be set in the page table entries since
the physical device driver may be doing DMA to the
pages which does not set this bit. If the dirty bit
is not set when writing to a page, then the data
written to the page may be lost.
VMDHL_LONG - If bit 4 (00010000B) is set,
then the lock is needed for a long term duration.
This parameter will be used if the physical device
driver intends to keep the lock on the object for
greater than 2 seconds.
VMDHL_VERIFY - If bit 5 (00100000B) is set,
the region will be 'verify only' locked. This
means that the page table mapping of this region
cannot be removed or destructively modified
(No free or decommit allowed in this region,
cannot remove write permission). However, the
region will not be physically locked in
memory, the physical pages will retain their
original status (swappable, discardable etc..).
This lock also does not force any pages to be
present. Passing the returned lock handle information
back to VMUnLock will release 'verify only' lock.
The flags in positions 1, and 2 are invalid with
this request. No physical addresses will be returned
in 'verify only' lock requests. Verify locks can be
specified short or long term. If bit 3 is set along
with this bit, the memory will be verified for
read/write access. If bit 3 is clear, only the
read permission will be verified.
All other bits must be clear.
- LinearAddr (LIN)
- Linearaddress of region to be locked.
- Length (ULONG)
- Count of bytes to be locked.
- pPageList (LIN)
- Flat pointer to array of PageList_s structures filled by the call.
- pLockHandle
- Address of the 12 byte variable the lock handle will be place in.
- PageListCount (PULONG)
- The number of elements in the page list array returned by this call.
Assembler
MOV EBX,LinearAddress ; Linear Address of region to lock
MOV ECX,Length ; Count of bytes to be locked
MOV EDI,OFFSET pPageList ; Flat pointer to array of PageList_s structures
; filled by the call
MOV ESI,OFFSET pLockHandle ; Address of the 12-byte variable the lock handle
; will be placed in
MOV EAX,ActionFlags ; Actions to be performed for lock
; If bit 0 (0000001B) is set, the lock returns if
; the requested pages are not immediately
; available. If the bit is clear, the call
; blocks until the pages are available.
; If bit 1 (0000010B) is set, the pages that are
; to be locked must be physically contiguous.
; This should be used only by device drivers
; that are about to perform contiguous DMA
; operations on the object.
; If bit 2 (0000100B) is set, the locked pages must
; be below the 16MB address line. If this bit
; is clear, then the pages can be locked
; anywhere in memory.
; If bit 3 (0001000B) is set, then the physical
; device driver plans to write in the region
; of the segment. This will cause the dirty bit
; to be set in the page table entries because
; the physical device driver may be doing DMA to
; the pages, which does not set this bit.
; If the dirty bit is not set when writing to a
; page, then the data written to the page may be
; lost.
; If bit 4 (0010000B) is set, then the lock is
; needed for a long-term duration. This
; parameter would be used if the physical device
; driver intends to keep the lock on the object
; for greater than two seconds.
; If bit 5 (0100000B) is set, the region will be
; 'verify only' locked. This means that the
; page table mapping of this region cannot be
; removed or destructively modified (No free or
; decommit allowed in the region, cannot remove
; write permission). However, the region will
; not be physically locked in memory, the
; physical pages will retain their original
; status (swappable, discardable, etc...).
; This lock also does not force any pages to be
; present.
; Passing the returned lock handle info back to
; VMUnLock will release 'verify only' lock.
; The flags in bit positions 1 and 2 are invalid
; with this request. No physical addresses will
; be returned in lock 'verify' requests. Verify
; locks can be specified for short or long term.
; If bit 3 is set along with this bit, the
; memory will be verified for read/write access.
; If bit 3 is clear, only the read permission
; will be verified.
; All other bits must be clear.
Return Code
C
Success Indicator: Clear if pages are locked - returns PageListCount.
Possible errors: Carry flag set if conversion is not performed.
Assembler
'C' Clear if pages locked.
EAX = If caller requested, the number of elements in the PageList array.
'C' Set if segment unavailable.
EAX = Error code.
Remarks
Use of short-term locks for greater than two seconds can cause a shortage of pages that are available for system use. Under these circumstances, a system halt could occur. If satisfying the lock request will reduce the amount of free memory in the system below a predetermined minimum, both short-term and long-term locks can fail.
Address verification is done automatically with every VMLock request. Locking down memory in fixed physical addresses is done only if the verify only bit is not set. It is the responsibility of the physical device driver to ensure that enough entries have been reserved for the range of memory being locked (possibly one entry per page in the range plus one more, if the region does not begin on a page boundary). If this pointer contains the value -1, then no physical addresses are returned. This parameter must be -1 for verify locks.
Because locking occurs on a per-page basis, the VMLock service routine will round LinearAddress down to the nearest page boundary. If physically contiguous locking is requested, Length cannot exceed 64KB; otherwise an error is returned. The combination of LinearAddress+Length is rounded up to the nearest page boundary.
Example Code
C
#include "dhcalls.h"
USHORT APIENTRY DevHelp_VMLock( ULONG Flags,
LIN LinearAddr,
ULONG Length,
LIN pPageList,
LIN pLockHandle,
PULONG PageListCount)