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)