INFO: GlobalSmartPageLock Documentation for Device Drivers

• Windows 95 Device Driver Kit (DDK), version 4.0

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   */

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   */

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.

REFERENCES

Windows 3.1 SDK

Windows 95 DDK

For additional information, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q85329
   TITLE     : BUG: GlobalPageLock() Moves Memory Fixed by GlobalFix()

Version           : WINDOWS:4.0
Platform          : WINDOWS
Hardware          : x86
Issue type        : kbinfo