The MmLockPagableSectionByHandle routine takes an indirect value that MmLockPagableDataSection or MmLockPagableCodeSection returns.

VOID 
  MmLockPagableSectionByHandle(
    IN PVOID  ImageSectionHandle
    );

Parameters

ImageSectionHandle

Supplies the handle returned by a call to MmLockPagableCodeSection or MmLockPagableDataSection.

Return Value

None

Comments

MmLockPagableSectionByHandle checks to see if the referenced section is resident in the caller's address space and if so, simply increments a reference count on the section. If the section is not resident, MmLockPagableSectionByHandle pages in the section, locks it in system space and sets the reference count to one.

If a pageable section is locked down in more than one place by a driver, use MmLockPagableXxxxSection for the first request to obtain an opaque value. Make subsequent lock requests by calling MmLockPagableSectionByHandle passing the opaque value returned by MmLockPagableXxxxSection. A locked down section is unlocked by calling MmUnlockPagableImageSection.

An opaque value returned from an MmLockPagableXxxxSection is valid the driver that contains the section is unloaded.

Locking by opaque value significantly improves driver performance. When MmLockPagableCodeSection or MmLockPagableDataSection is called, the memory manager walks the entire loaded module list to find the module containing the specified address. This is an expensive operation. Calling MmLockPagableImageSectionByHandle reduces this burden because if the caller supplies an opaque value for the section, the memory manager does not have to search the loaded module list to find it.

The memory manager maintains a reference count on the opaque value for the section. A pageable section is only available to be paged out when the reference count is zero. Every lock request increments the count; every unlock request decrements the count. A driver must take care to unlock a section as many times as it locks a section to insure that such a section will be eligible to be paged out when the section is not needed. Once an opaque value is obtained, it is always valid, no matter what the count until the driver is unloaded. If the count on an opaque value is zero and a call is made to MmLockPagableSectionByHandle, the count is set to one, and if the section has been paged out, it will be paged in.

A driver cannot call MmLockPagableSectionByHandle to lock down user buffers passed in IRPs. Use MmProbeAndLockPages instead.

For more information about paging code and data, see Making Drivers Pageable.

Requirements

IRQL: <=APC_LEVEL

Headers: Declared in Ntddk.h. Include Ntddk.h.

See Also

MmLockPagableDataSection, MmLockPagableCodeSection, MmProbeAndLockPages, MmPageEntireDriver, MmResetDriverPaging, MmUnlockPagableImageSection