Microsoft KB Archive/180586

{|
 * width="100%"|

INFO: GlobalSmartPageLock Documentation for Device Drivers

 * }

Q180586

-

The information in this article applies to:


 * Microsoft Windows 95 Driver Development Kit (DDK)

-

SUMMARY
The Windows 95 Device Driver Kit display driver sample code uses the GlobalSmartPageLock API, but this API is not documented in currently released development kits or the MSDN Library. This article documents the API for display driver developers.

MORE INFORMATION
UINT GlobalSmartPageLock(hglb) HGLOBAL hglb; Parameters:

"hglb - handle to the global memory object to be locked." Return value:

"This function does not return a value." Comments:

This information is provided as a supplement to the Windows 95 Device Driver Kit sample code and documentation. Applications should not use the GlobalSmartPageLock API since it violates several Windows programming practices.

The GlobalSmartPageLock API was originally developed in Windows 3.0. It's purpose was to allow one system call to "smartly" lock a memory region regardless of how virtual memory paging is being managed. This API will internally determine if the operating system is paging through real mode MS- DOS drivers, or through protected mode Windows drivers. Based on this determination, GlobalSmartPageLock will call either GlobalFix or GlobalPageLock API. Currently, it is very unlikely that a end-user will be using real mode MS-DOS drivers, so in most cases GlobalSmartPageLock will call GlobalPageLock. However, the display system driver developer cannot assume that this is always true, which is why the DDK sample code uses GlobalSmartPageLock.

See the comments below for GlobalPageLock and GlobalFix. The GlobalSmartPageLock functionality is useful to the Windows system drivers during the initialization process. This article does not document the corresponding xxxUnlock API since the display driver is not unloaded while Windows is still running and there is no need to unlock the memory. This situation may change with new multiple monitor capabilities in future versions of Windows that will use dynamically loaded hardware devices. Please contact Microsoft Technical Support if you need more information.

Windows 3.1 SDK References
The following information was copied from the Windows 3.1 SDK references:

Windows version 3.0:
     UINT GlobalPageLock(hglb) HGLOBAL hglb;  /* selector of global memory to lock   */ The GlobalPageLock function increments (increases by one) the page-lock count for the memory associated with the given global selector. As long as its page-lock count is nonzero, the data that the selector references is guaranteed to remain in memory at the same physical address.

Parameters:

"hglb - Specifies the selector of the memory to be page-locked." Return Value:

"The return value specifies the page-lock count after the function has incremented it. If the function fails, the return value is zero." Comments:

Because using this function violates preferred Windows programming practices, an application should not use it unless absolutely necessary. The function is intended to be used for dynamically allocated data that must be accessed at interrupt time. For this reason, it must be called only from a dynamic-link library (DLL). The GlobalPageLock function increments the page-lock count for the block of memory, and the GlobalPageUnlock function decrements (decreases by one) the page-lock count. Page-locking operations can be nested, but each page-locking must be balanced by a corresponding unlocking.

See also GlobalPageUnlock.

Windows version 3.0:
     void GlobalFix(hglb) HGLOBAL hglb;  /* handle of object to fix   */ The GlobalFix function prevents the given global memory object from moving in linear memory. This function interferes with effective Windows memory management and can result in linear-address fragmentation. Few applications need to fix memory in linear address space.

Parameters:

"hglb - Identifies the global memory object to be fixed in linear memory." Return Value:

"This function does not return a value." Comments:

The object is locked into linear memory at its current address, and its lock count is incremented (increased by one). Locked memory is not subject to moving or discarding except when the memory object is being reallocated by the GlobalReAlloc function. The object remains locked in memory until its lock count is decreased to zero. Each time an application calls the GlobalFix function for a memory object, it must eventually call the GlobalUnfix function, which decrements (decreases by one) the lock count for the object. Other functions also can affect the lock count of a memory object. For a list of these functions, see the description of the GlobalFlags function.

See also GlobalFlags, GlobalReAlloc, GlobalUnfix.