LIM Expanded Memory Specification V4: Writing Programs That Use Expanded Memory

From Lo-tech Wiki
Jump to navigation Jump to search

This chapter describes what every program must do to use expanded memory and describes more advanced techniques of using expanded memory.

This chapter also lists programming guidelines you should follow when writing programs that use expanded memory and provides the listings of some example programs.

WHAT EVERY PROGRAM MUST DO

This section describes the steps every program must take to use expanded memory.

In order to use expanded memory, applications must perform these steps in the following order:

  1. Determine if EMM is installed.
  2. Determine if enough expanded memory pages exist for your application. (Function 3)
  3. Allocate expanded memory pages. (Function 4 or 18)
  4. Get the page frame base address. (Function 2)
  5. Map in expanded memory pages. (Function 5 or 17)
  6. Read/write/execute data in expanded memory, just as if it were conventional memory.
  7. Return expanded memory pages to expanded memory pool before exiting. (Function 6 or 18)

Table 2-1 overviews the functions while Chapter 3 describes each of these functions in detail. Example programs at the end of this chapter illustrate using expanded memory.

Function Description
1 The Get Status function returns a status code indicating whether the memory manager hardware is working correctly.
2 The Get Page Frame Address function returns the address where the 64K-byte page frame is located.
3 The Get Unallocated Page Count function returns the number of unallocated pages (pages available to your program) and the total number of pages in expanded memory.
4 The Allocate Pages function allocates the number of pages requested and assigns a unique EMM handle to these pages.
5 The Map/Unmap Handle Page function maps a logical page to a specific physical page anywhere in the mappable regions of system memory.
6 The Deallocate Pages deallocates the logical pages currently allocated to an EMM handle.
7 The Get Version function returns the version number of the memory manager software.

TABLE 2-1. THE BASIC FUNCTIONS

ADVANCED PROGRAMMING

In addition to the basic functions, the Lotus/Intel/Microsoft Expanded Memory Specification provides several advanced functions which enhance the capabilities of software that uses expanded memory.

The following sections describe the advanced programming capabilities and list the advanced EMM functions.

Note.............................................................

Before using the advanced functions, programs should first call Function 7 (Get Version) to determine whether the installed version of EMM supports these functions.

SAVING THE STATE OF MAPPING HARDWARE

Some software (such as interrupt service routines, device drivers, and resident software) must save the current state of the mapping hardware, switch mapping contexts, manipulate sections of expanded memory, and restore the original context of the memory mapping hardware. Use Functions 8 and 9 or 15 and 16 to save the state of the hardware.

RETRIEVING HANDLE AND PAGE COUNTS

Some utility programs need to keep track of how expanded memory is being used; use Functions 12 through 14 to do this.

MAPPING AND UNMAPPING MULTIPLE PAGES

Mapping multiple pages reduces the overhead an application must perform during mapping. Function 17 lets a program map (or unmap) multiple pages at one time.

In addition, you can map pages using segment addresses instead of physical pages. For example, if the page frame base address is set to D000, you can map to either physical page 0 or segment D000. Function 25 (Get Mappable Physical Address Array) returns a cross reference between all expanded memory physical pages and their corresponding segment values.

REALLOCATING PAGES

Reallocating pages (Function 18) lets applications dynamically allocate expanded memory pages without acquiring another handle or obtain a handle without allocating pages. Reallocating pages is an efficient means for applications to obtain and release expanded memory pages.

USING HANDLES AND ASSIGNING NAMES TO HANDLES

This specification lets you associate a name with a handle, so a family of applications can share information in expanded memory. For example, a software package consisting of a word processor, spreadsheet, and print spooler can share the same data among the different applications. The print spooler could use a handle name to reference data that either the spreadsheet or word processor put in expanded memory and could check for data in a particular handle name's expanded memory pages.

Use Function 20 (Set Handle Name subfunction) to assign a handle name to an EMM handle or Function 21 (Search for Named Handle subfunction) to obtain the EMM handle associated with the handle name. In addition, you can use Function 14 (Get Handle Pages) to determine the number of expanded memory pages allocated to an EMM handle.

USING HANDLE ATTRIBUTES

In addition to naming a handle, you can use Function 19 to associate an attribute (volatile or non-volatile) with a handle name. A non- volatile attribute enables expanded memory pages to preserve their data through a warmboot.

With a volatile attribute, the data is not preserved. The default attribute for handles is volatile.

Because using this function depends on the capabilities of the expanded memory hardware installed in the system, you should use the Get Attribute Capability subfunction before attempting to assign an attribute to a handle's pages.

ALTERING PAGE MAPS AND JUMPING/CALLING

You can use Functions 22 (Alter Page Map and Jump) and 23 (Alter Page Map and Call) to map a new set of values into the map registers and transfer program control to a specified address within expanded memory. These functions can be used to load and execute code in expanded memory. An application using this feature can significantly reduce the amount of conventional memory it requires. Programs can load needed modules into expanded memory at run time and use Functions 22 and 23 to transfer control to these modules.

Using expanded memory to store code can improve program execution in many ways. For example, sometimes programs need to be divided into small overlays because of conventional memory size limitations. Overlays targeted for expanded memory can be very large because LIM EMS 4.0 supports up to 32M bytes of expanded memory. This method of loading overlays improves overall system performance by conserving conventional memory and eliminating conventional memory allocation errors.

MOVING OR EXCHANGING MEMORY REGIONS

Using Function 24 (Move/Exchange Memory Region), you can easily move and exchange data between conventional and expanded memory. Function 24 can manipulate up to one megabyte of data with one function call. Although applications can perform this operation without this function, having the expanded memory manager do it reduces the amount of overhead for the application. In addition, this function checks for overlapping regions and performs all the necessary mapping, preserving the mapping context from before the exchange/move call.

GETTING THE AMOUNT OF MAPPABLE MEMORY

Function 25 enables applications to determine the total amount of mappable memory the hardware/system currently supports. Not all expanded memory boards supply the same number of physical pages (map registers).

The Get Mappable Physical Address Array Entries subfunction returns the total number of physical pages the expanded memory hardware/system is capable of supporting. The Get Mappable Physical Address Array subfunction returns a cross reference between physical page numbers and the actual segment address for each of the physical pages.

OPERATING SYSTEM FUNCTIONS

In addition to the functions for application programs, this specification defines functions for operating systems/environments. These functions can be disabled at any time by the operating system/environment, so programs should not depend on their presence. Applications that avoid this warning and use these functions run a great risk of being incompatible with other programs, including the operating system.

Function Description
8 The Save Page Map saves the contents of the page mapping registers from all expanded memory boards in an internal save area.
9 The Restore Page Map function restores (from an internal save area) the page mapping register contents on the expanded memory boards for a particular EMM handle.
10 Reserved.
11 Reserved.
12 The Get Handle Count function returns the number of open EMM handles in the system.
13 The Get Handle Pages function returns the number of pages allocated to a specific EMM handle.
14 The Get All Handle Pages function returns an array of the active EMM handles and the number of pages allocated to each one.
15 The Get/Set Page Map subfunction saves or restores the mapping context for all mappable memory regions (conventional and expanded) in a destination array which the application supplies.
16 The Get/Set Partial Page Map subfunction provides a mechanism for saving a partial mapping context for specific mappable memory regions in a system.
17 The Map/Unmap Multiple Handle Pages function can, in a single invocation, map (or unmap) logical pages into as many physical pages as the system supports.
18 The Reallocate Pages function can increase or decrease the amount of expanded memory allocated to a handle.
19 The Get/Set Handle Attribute function allows an application program to determine and set the attribute associated with a handle.
20 The Get/Set Handle Name function gets the eight character name currently assigned to a handle and can assign an eight character name to a handle.
21 The Get Handle Directory function returns information about active handles and the names assigned to each.
22 The Alter Page Map & Jump function alters the memory mapping context and transfers control to the specified address.
23 The Alter Page Map & Call function alters the specified mapping context and transfers control to the specified address. A return can then restore the context and return control to the caller.
24 The Move/Exchange Memory Region function copies or exchanges a region of memory from conventional to conventional memory, conventional to expanded memory, expanded to conventional memory, or expanded to expanded memory.
25 The Get Mappable Physical Address Array function returns an array containing the segment address and physical page number for each mappable physical page in a system.
26 The Get Expanded Memory Hardware Information function returns an array containing the hardware capabilities of the expanded memory system.
27 The Allocate Standard/Raw Pages function allocates the number of standard or non-standard size pages that the operating system requests and assigns a unique EMM handle to these pages.
28 The Alternate Map Register Set function enables an application to simulate alternate sets of hardware mapping registers.
29 The Prepare Expanded Memory Hardware for Warm Boot function prepares the expanded memory hardware for an "impending" warm boot.
30 The Enable/Disable OS/E function enables operating systems developers to enable and disable functions designed for operating system use.

TABLE 2-2. THE ADVANCED FUNCTIONS


PROGRAMMING GUIDELINES

The following section contains guidelines for programmers writing applications that use EMM.

  • Do not put a program's stack in expanded memory.
  • Do not replace interrupt 67h. This is the interrupt vector the EMM uses. Replacing interrupt 67h could result in disabling the Expanded Memory Manager.
  • Do not map into conventional memory address space your application doesn't own. Applications that use the EMM to swap into conventional memory space, must first allocate this space from the operating system. If the operating system is not aware that a region of memory it manages is in use, it will think it is available. This could have disastrous results. EMM should not be used to 'allocate' conventional memory. DOS is the proper manager of conventional memory space. EMM should only be used to swap data in conventional memory space previously allocated from DOS.
  • Applications that plan on using data aliasing in expanded memory must check for the presence of expanded memory hardware. Data aliasing occurs when mapping one logical page into two or more mappable segments. This makes one 16K-byte expanded memory page appear to be in more than one 16K-byte memory address space. Data aliasing is legal and sometimes useful for applications.
  • Software-only expanded memory emulators cannot perform data aliasing. A simple way to distinguish software emulators from actual expanded memory hardware is to attempt data aliasing and check the results. For example, map one logical page into four physical pages. Write to physical page 0. Read physical pages 1- 3 to see if the data is there as well. If the data appears in all four physical pages, then expanded memory hardware is installed in the system, and data aliasing is supported.
  • Applications should always return expanded memory pages to the expanded memory manager upon termination. These pages will be made available for other applications. If unneeded pages are not returned to the expanded memory manager, the system could 'run out' of expanded memory pages or expanded memory handles.
  • Terminate and stay resident programs (TSR's) should ALWAYS save the state of the map registers before changing them. Since TSR's may interrupt other programs which may be using expanded memory, they must not change the state of the page mapping registers without first saving them. Before exiting, TSR's must restore the state of the map registers.
    The following sections describe the three ways to save and restore the state of the map registers.
    1. Save Page Map and Restore Page Map (Functions 8 and 9). This is the simplest of the three methods. The EMM saves the map register contents in its own data structures -- the application does not need to provide extra storage locations for the mapping context. The last mapping context to be saved, under a particular handle, will be restored when a call to Restore Page Map is issued with the same handle. This method is limited to one mapping context for each handle and saves the context for only LIM standard 64K-byte page frames.
    2. Get/Set Page Map (Function 15). This method requires the application to allocate space for the storage array. The EMM saves the mapping context in an array whose address is passed to the EMM. When restoring the mapping context with this method, an application passes the address of an array which contains a previously stored mapping context.
      This method is preferable if an application needs to do more than one save before a restore. It provides a mechanism for switching between more than one mapping context.
    3. Get/Set Partial Page Map (Function 16). This method provides a way for saving a partial mapping context. It should be used when the application does not need to save the context of all mappable memory. This function also requires that the storage array be part of the application's data.
  • All functions using pointers to data structures must have those data structures in memory which will not be mapped out. Functions 22 and 23 (Alter Map and Call and Alter Map and Jump) are the only exceptions.

LIM Expanded Memory Specification V4 Contents

See Also

Retrieved from "https://www.lo-tech.co.uk/w/index.php?title=LIM_Expanded_Memory_Specification_V4:_Writing_Programs_That_Use_Expanded_Memory&oldid=113"