MmLockPagableSectionByHandle

MmLockPagableSectionByHandle

VOID
MmLockPagableSectionByHandle(
IN PVOID ImageSectionHandle
);

MmLockPagableSectionByHandle takes a handle returned by MmLockPagableDataSection or MmLockPagableCodeSection. This routine 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, MmLockPagableImage pages in the section, locks it in system space and sets the reference count to one.

Parameters

ImageSectionHandle

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

Return Value

None.

Comments

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

A handle returned from an MmLockPagableXxxxSection is valid until a driver is unloaded.

Locking by handle 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 a handle to the section, the memory manager no longer has to search.

The memory manager maintains a reference count on the handle to 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 a handle is obtained, it is always valid, no matter what the count until the driver is unloaded. If the count on a handle 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 The Programmer's Guide.

Callers of MmLockPagableSectionByHandle runs at IRQL PASSIVE_Level.