Lotus Development Corporation
55 Cambridge Parkway
Cambridge, MA 02142
Intel Corporation
5200 NE Elam Young Parkway
Hillsboro, OR 97124
Microsoft Corporation
16011 NE 36TH Way
Box 97017
Redmond, WA 98073
This specification was jointly developed by Lotus Development
Corporation, Intel Corporation, and Microsoft Corporation. Although
it has been released into the public domain and is not confidential or
proprietary, the specification is still the copyright and property of
Lotus Development Corporation, Intel Corporation, and Microsoft
Corporation.
DISCLAIMER OF WARRANTY
LOTUS DEVELOPMENT CORPORATION, INTEL CORPORATION, AND MICROSOFT
CORPORATION EXCLUDE ANY AND ALL IMPLIED WARRANTIES, INCLUDING
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
NEITHER LOTUS NOR INTEL NOR MICROSOFT MAKE ANY WARRANTY OF
REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS
SPECIFICATION, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. NEITHER LOTUS NOR INTEL NOR MICROSOFT SHALL
HAVE ANY LIABILITY FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF OR RESULTING FROM THE USE OR MODIFICATION OF THIS
SPECIFICATION.
This specification uses the following trademarks:
Intel is a trademark of Intel Corporation
Lotus is a trademark of Lotus Development Corporation
Microsoft is a trademark of Microsoft Corporation
1
CHAPTER 1
INTRODUCTION
Because even the maximum amount (640K bytes) of conventional memory
isn't always enough for large application programs, Lotus Development
Corporation, Intel Corporation, and Microsoft Corporation created the
Lotus/Intel/Microsoft (LIM) Expanded Memory Specification.
The LIM Expanded Memory Specification defines the software interface
between the Expanded Memory Manager (EMM) -- a device driver that
controls and manages expanded memory -- and application programs that
use expanded memory.
WHAT IS EXPANDED MEMORY?
Expanded memory is memory beyond DOS's 640K-byte limit. The LIM
specification supports up to 32M bytes of expanded memory. Because
the 8086, 8088, and 80286 (in real mode) microprocessors can
physically address only 1M byte of memory, they access expanded memory
through a window in their physical address range. The next section
explains how this is done.
HOW EXPANDED MEMORY WORKS
Expanded memory is divided into segments called logical pages. These
pages are typically 16K-bytes of memory. Your computer accesses
logical pages through a physical block of memory called a page frame.
The page frame contains multiple physical pages, pages that the
microprocessor can address directly. Physical pages are also
typically 16K bytes of memory.
This page frame serves as a window into expanded memory. Just as your
computer screen is a window into a large spreadsheet, so the page
frame is a window into expanded memory.
A logical page of expanded memory can be mapped into (made to appear
in) any one of the physical pages in the page frame. Thus, a read or
write to the physical page actually becomes a read or write to the
associated logical page. One logical page can be mapped into the page
frame for each physical page.
The page frame is located above 640K bytes. Normally, only video
adapters, network cards, and similar devices exist between 640K and
1024K.
This specification also defines methods for operating systems and
environments to access expanded memory through physical pages below
640K bytes. These methods are intended for operating
system/environment developers only.
2
CHAPTER 2
WRITING PROGRAMS THAT USE EXPANDED MEMORY
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.
TABLE 2-1. THE BASIC FUNCTIONS
----------------------------------------------------------------------
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.
3
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.
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.
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.
4
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
5
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.
TABLE 2-2. THE ADVANCED FUNCTIONS
----------------------------------------------------------------------
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.
6
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.
7
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.
8
PROGRAMMING GUIDELINES
The following section contains guidelines for programmers writing
applications that use EMM.
o Do not put a program's stack in expanded memory.
o Do not replace interrupt 67h. This is the interrupt vector the
EMM uses. Replacing interrupt 67h could result in disabling the
Expanded Memory Manager.
o 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.
o 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.
o 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.
o 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
9
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.
o 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.
10
CHAPTER 3
EMM FUNCTIONS
This chapter provides you with a standardized set of expanded memory
functions. Because they are standardized, you avoid potential
compatibility problems with other expanded memory programs that also
adhere to the memory manager specification. Programs that deal
directly with the hardware or that don't adhere to this specification
will be incompatible.
Table 3-1 presents a sequential list of the EMM functions. The
remainder of this chapter provides detailed descriptions of each
function.
TABLE 3-1. LIST OF EMM FUNCTIONS
----------------------------------------------------------------------
Number Function Name Hex Value Page
----------------------------------------------------------------------
22 Alter Page Map & Jump
(Physical page number mode) 5500h 77
Alter Page Map & Jump
(Segment address mode) 5501h 77
23 Alter Page Map & Call
(Physical page number mode) 5600h 80
Alter Page Map & Call
(Segment address mode) 5601h 80
Get Page Map Stack Space Size 5602h 84
24 Move Memory Region 5700h 86
Exchange Memory Region 5701h 91
25 Get Mappable Physical Address Array 5800h 96
Get Mappable Physical Address Array Entries 5801h 99
26 Get Hardware Configuration Array 5900h 101
Get Unallocated Raw Page Count 5901h 104
27 Allocate Standard Pages 5A00h 106
12
Allocate Raw Pages 5A01h 109
28 Get Alternate Map Register Set 5B00h 112
Set Alternate Map Register Set 5B01h 117
Get Alternate Map Save Array Size 5B02h 120
Allocate Alternate Map Register Set 5B03h 122
Deallocate Alternate Map Register Set 5B04h 124
Allocate DMA Register Set 5B05h 126
Enable DMA on Alternate Map Register Set 5B06h 128
Disable DMA on Alternate Map Register Set 5B07h 130
Deallocate DMA Register Set 5B08h 132
29 Prepare Expanded Memory Hardware for Warmboot 5Ch 134
30 Enable OS/E Function Set 5D00h 135
Disable OS/E Function Set 5D01h 138
Return OS/E Access Key 5D02h 140
13
FUNCTION 1 GET STATUS
PURPOSE
The Get Status function returns a status code indicating whether the
memory manager is present and the hardware is working correctly.
CALLING PARAMETERS
AH = 40h
Contains the Get Status function.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager is present in the system, and the hardware is
working correctly.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
EXAMPLE
MOV AH, 40h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
14
FUNCTION 2 GET PAGE FRAME ADDRESS
PURPOSE
The Get Page Frame Address function returns the segment address where
the page frame is located.
CALLING PARAMETERS
AH = 41h
Contains the Get Page Frame function.
RESULTS
These results are valid only if the status returned is zero.
BX = page frame segment address
Contains the segment address of the page frame.
REGISTERS MODIFIED
AX, BX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the page frame address in the BX
register.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
EXAMPLE
page_frame_segment DW ?
MOV AH, 41h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV page_frame_segment, BX ; save page frame address
15
FUNCTION 3 GET UNALLOCATED PAGE COUNT
PURPOSE
The Get Unallocated Page Count function returns the number of
unallocated pages and the total number of expanded memory pages.
CALLING PARAMETERS
AH = 42h Contains the Get Unallocated Page Count function.
RESULTS
These results are valid only if the status returned is zero.
BX = unallocated pages
The number of expanded memory pages that are currently
available for use (unallocated).
DX = total pages
The total number expanded memory pages.
REGISTERS MODIFIED
AX, BX, DX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the number of unallocated pages
and the number of total pages in expanded memory.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
EXAMPLE
un_alloc_pages DW ?
total_pages DW ?
MOV AH, 42h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV un_alloc_pages, BX ; save unallocated page count
MOV total_pages, DX ; save total page count
16
FUNCTION 4 ALLOCATE PAGES
PURPOSE
The Allocate Pages function allocates the number of pages requested
and assigns a unique EMM handle to these pages. The EMM handle owns
these pages until the application deallocates them.
Handles which are assigned using this function will have 16K-byte
pages, the size of a standard expanded memory page. If the expanded
memory board hardware isn't able to supply 16K-byte pages, it will
emulate them by combining multiple non-standard size pages to form a
single 16K-byte page. All application programs and functions that use
the handles this function returns will deal with 16K-byte pages.
The numeric value of the handles the EMM returns are in the range of 1
to 254 decimal (0001h to 00FEh). The OS handle (handle value 0) is
never returned by the Allocate Pages function. Also, the uppermost
byte of the handle will be zero and cannot be used by the application.
A memory manager should be able to supply up to 255 handles, including
the OS handle. An application can use Function 21 to find out how
many handles an EMM supports.
Allocating zero pages to a handle is not valid. If an application
needs to allocate 0 pages to a handle it should use Function 27
provided for this purpose.
This note affects expanded memory manager implementers and operating
system developers only. Applications should not use the following
characteristic of the memory manager. An application violating this
rule will be incompatible with future versions of Microsoft's
operating systems and environments.
To be compatible with this specification, an expanded memory manager
will provide a special handle which is available to the operating
system only. This handle will have a value of 0000h and will have a
set of pages allocated to it when the expanded memory manager driver
installs. The pages that the memory manager will automatically
allocate to handle 0000h are those that backfill conventional memory.
Typically, this backfill occurs between addresses 40000h (256K) and
9FFFFh (640K). However, the range can extend below and above this
limit if the hardware and memory manager have the capability.
An operating system won't have to invoke Function 4 to obtain this
handle because it can assume the handle already exists and is
available for use immediately after the expanded memory device driver
installs. When an operating system wants to use this handle, it uses
the special handle value of 0000h. The operating system will be able
to invoke any EMM function using this special handle value. To
allocate pages to this handle, the operating system need only invoke
Function 18 (Reallocate pages)..
There are two special cases for this handle:
17
1. Function 4 (Allocate Pages). This function must never return zero
as a handle value. Applications must always invoke Function 4 to
allocate pages and obtain a handle which identifies the pages
which belong to it. Since Function 4 never returns a handle value
of zero, an application will never gain access to this special
handle.
2. Function 6 (Deallocate Pages). If the operating system uses it to
deallocate the pages which are allocated to this special handle,
the pages the handle owns will be returned to the manager for use.
But the handle will not be available for reassignment. The
manager should treat a deallocate pages function request for this
handle the same as a reallocate pages function request, where the
number of pages to reallocate to this handle is zero.
CALLING PARAMETERS
AH = 43h
Contains the Allocate Pages function.
BX = num_of_pages_to_alloc
Contains the number of pages you want your program to
allocate.
RESULTS
These results are valid only if the status returned is zero.
DX = handle
Contains a unique EMM handle. Your program must use this
EMM handle (as a parameter) in any function that requires
it. You can use up to 255 handles. The uppermost byte of
the handle will be zero and cannot be used by the
application.
REGISTERS MODIFIED
AX, DX
STATUS
AH = 0 SUCCESSFUL
The manager has allocated the requested pages to the
assigned EMM handle.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
18
AH = 85h RECOVERABLE
All EMM handles are being used.
AH = 87h RECOVERABLE
There aren't enough expanded memory pages present in the
system to satisfy your program's request.
AH = 88h RECOVERABLE
There aren't enough unallocated pages to satisfy your
program's request.
AH = 89h RECOVERABLE
Your program attempted to allocate zero pages.
EXAMPLE
num_of_pages_to_alloc DW ?
emm_handle DW ?
MOV BX, num_of_pages_to_alloc ; load number of pages
MOV AH, 43h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV emm_handle, DX ; save EMM handle
19
FUNCTION 5 MAP/UNMAP HANDLE PAGES
PURPOSE
The Map/Unmap Handle Page function maps a logical page at a specific
physical page anywhere in the mappable regions of system memory.
The lowest valued physical page numbers are associated with regions of
memory outside the conventional memory range. Use Function 25 (Get
Mappable Physical Address Array) to determine which physical pages
within a system are mappable and determine the segment addresses which
correspond to a specific physical page number. Function 25 provides a
cross reference between physical page numbers and segment addresses.
This function can also unmap physical pages, making them inaccessible
for reading or writing. You unmap a physical page by setting its
associated logical page to FFFFh.
You might unmap an entire set of mapped pages, for example, before
loading and executing a program. Doing so ensures the loaded program,
if it accesses expanded memory, won't access the pages your program
has mapped. However, you must save the mapping context before you
unmap the physical pages. This enables you to restore it later so you
can access the memory you mapped there. To save the mapping context,
use Function 8, 15, or 16. To restore the mapping context, use
Function 9, 15, or 16.
The handle determines what type of pages are being mapped. Logical
pages allocated by Function 4 and Function 27 (Allocate Standard Pages
subfunction) are referred to as pages and are 16K bytes long. Logical
pages allocated by Function 27 (Allocate Raw Pages subfunction) are
referred to as raw pages and might not be the same size as logical
pages.
CALLING PARAMETERS
AH = 44h
Contains the Map Handle Page function.
AL = physical_page_number
Contains the number of the physical page into which the
logical page number is to be mapped. Physical pages are
numbered zero relative.
BX = logical_page_number
Contains the number of the logical page to be mapped at the
physical page within the page frame. Logical pages are
numbered zero relative. The logical page must be in the
range zero through (number of pages allocated to the EMM
handle - 1). However, if BX contains logical page number
FFFFh, the physical page specified in AL will be unmapped
(be made inaccessible for reading or writing).
DX = emm_handle
Contains the EMM handle your program received from Function
4 (Allocate Pages).
REGISTERS MODIFIED
20
AX
STATUS
AH = 0 SUCCESSFUL
The manager has mapped the page. The page is ready to be
accessed.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 83h NON-RECOVERABLE
The memory manager couldn't find the EMM handle your
program specified.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager isn't
defined.
AH = 8Ah RECOVERABLE
The logical page is out of the range of logical pages which
are allocated to the EMM handle. This status is also
returned if a program attempts map a logical page when no
logical pages are allocated to the handle.
AH = 8Bh RECOVERABLE
The physical page number is out of the range of allowable
physical pages. The program can recover by attempting to
map into memory at a physical page which is within the
range of allowable physical pages.
EXAMPLE
emm_handle DW ?
logical_page_number DW ?
physical_page_number DB ?
MOV DX, emm_handle ; load EMM handle
MOV BX, logical_page_number ; load logical page number
MOV AL, physical_page_number ; load physical page number
MOV AH, 44h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
21
FUNCTION 6 DEALLOCATE PAGES
PURPOSE
Deallocate Pages deallocates the logical pages currently allocated to
an EMM handle. Only after the application deallocates these pages can
other applications use them. When a handle is deallocated, it name is
set to all ASCII nulls (binary zeros).
A program must perform this function before it exits to DOS. If it
doesn't, no other programs can use these pages or the EMM handle.
This means that a program using expanded memory should trap critical
errors and control-break if there is a chance that the program will
have allocated pages when either of these events occur.
Calling Parameters
AH = 45h
Contains the Deallocate Pages function.
DX = handle
Contains the EMM handle returned by Function 4 (Allocate
Pages).
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has deallocated the pages previously allocated
to the EMM handle.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 83h NON-RECOVERABLE
The manager couldn't find the specified EMM handle.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 86h RECOVERABLE
The memory manager detected a save or restore page mapping
context error (Function 8 or 9). There is a page mapping
register state in the save area for the specified EMM
handle. Save Page Map (Function 8) placed it there and a
subsequent Restore Page Map (Function 9) has not removed
22
it. If you have saved the mapping context, you must
restore it before you deallocate the EMM handle's pages.
EXAMPLE
emm_handle DW ?
MOV DX, emm_handle ; load EMM handle
MOV AH, 45h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
23
FUNCTION 7 GET VERSION
PURPOSE
The Get Version function returns the version number of the memory
manager software.
CALLING PARAMETERS
AH = 46h
Contains the Get Version function.
RESULTS
These results are valid only if the status returned is zero.
AL = version number
Contains the memory manager's version number in binary
coded decimal (BCD) format. The upper four bits contain
the integer digit of the version number. The lower four
bits contain the fractional digit of version number. For
example, version 4.0 is represented like this:
0100 0000
/ \
4 . 0
When checking for a version number, an application should
check for a version number or greater. Vendors may use the
fractional digit to indicate enhancements or corrections to
their memory managers. Therefore, to allow for future
versions of memory managers, an application shouldn't
depend on an exact version number.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager is present in the system and the hardware is
working correctly.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
EXAMPLE
24
emm_version DB ?
MOV AH, 46h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV emm_version, AL ; save version number
25
FUNCTION 8 SAVE PAGE MAP
PURPOSE
Save Page Map saves the contents of the page mapping registers on all
expanded memory boards in an internal save area. The function is
typically used to save the memory mapping context of the EMM handle
that was active when a software or hardware interrupt occurred. (See
Function 9, Restore Page Map, for the restore operation.) If you're
writing a resident program, an interrupt service, or a device driver
that uses expanded memory, you must save the state of the mapping
hardware. You must save this state because application software using
expanded memory may be running when your program is invoked by a
hardware interrupt, a software interrupt, or DOS.
The Save Page Map function requires the EMM handle that was assigned
to your resident program, interrupt service routine, or device driver
at the time it was initialized. This is not the EMM handle that the
application software was using when your software interrupted it.
The Save Page Map function saves the state of the map registers for
only the 64K-byte page frame defined in versions 3.x of this
specification. Since all applications written to LIM versions 3.x
require saving the map register state of only this 64K-byte page
frame, saving the entire mapping state for a large number of mappable
pages would be inefficient use of memory. Applications that use a
mappable memory region outside the LIM 3.x page frame should use
Function 15 or 16 to save and restore the state of the map registers.
CALLING PARAMETERS
AH = 47h
Contains the Save Page Map function.
DX = handle
Contains the EMM handle assigned to the interrupt service
routine that's servicing the software or hardware
interrupt. The interrupt service routine needs to save the
state of the page mapping hardware before mapping any
pages.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has saved the state of the page mapping
hardware.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
26
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 83h NON-RECOVERABLE
The memory manager couldn't find the EMM handle your
program specified.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Ch NON-RECOVERABLE
There is no room in the save area to store the state of the
page mapping registers. The state of the map registers has
not been saved.
AH = 8Dh CONDITIONALLY-RECOVERABLE
The save area already contains the page mapping register
state for the EMM handle your program specified.
EXAMPLE
emm_handle DW ?
MOV DX, emm_handle ; load EMM handle
MOV AH, 47h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
27
FUNCTION 9 RESTORE PAGE MAP
PURPOSE
The Restore Page Map function restores the page mapping register
contents on the expanded memory boards for a particular EMM handle.
This function lets your program restore the contents of the mapping
registers its EMM handle saved. (See Function 8, Save Page Map for the
save operation.)
If you're writing a resident program, an interrupt service routine, or
a device driver that uses expanded memory, you must restore the
mapping hardware to the state it was in before your program took over.
You must save this state because application software using expanded
memory might have been running when your program was invoked.
The Restore Page Map function requires the EMM handle that was
assigned to your resident program, interrupt service routine, or
device driver at the time it was initialized. This is not the EMM
handle that the application software was using when your software
interrupted it.
The Restore Page Map function restores the state of the map registers
for only the 64K-byte page frame defined in versions 3.x of this
specification. Since all applications written to LIM versions 3.x
require restoring the map register state of only this 64K-byte page
frame, restoring the entire mapping state for a large number of
mappable pages would be inefficient use of memory. Applications that
use a mappable memory region outside the LIM 3.x page frame should use
Function 15 or 16 to save and restore the state of the map registers.
CALLING PARAMETERS
AH = 48h
Contains the Restore Page Map function.
DX = emm_handle
Contains the EMM handle assigned to the interrupt service
routine that's servicing the software or hardware
interrupt. The interrupt service routine needs to restore
the state of the page mapping hardware.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has restored the state of the page mapping
registers.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
28
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 83h NON-RECOVERABLE
The memory manager couldn't find the EMM handle your
program specified.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Eh CONDITIONALLY-RECOVERABLE
There is no page mapping register state in the save area
for the specified EMM handle. Your program didn't save the
contents of the page mapping hardware, so Restore Page Map
can't restore it.
EXAMPLE
emm_handle DW ?
MOV DX, emm_handle ; load EMM handle
MOV AH, 48h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
29
FUNCTION 10 RESERVED
In earlier versions of the Lotus/Intel/Microsoft Expanded Memory
Specification the use of this function was documented. This function
is now documented as "RESERVED" (i.e. not documented) in the public
versions of the specification and new programs should not use it.
Existing programs that use this function may still work correctly if
the hardware is capable of supporting them. Since IBM Microchannel
hardware is not capable of supporting this function, it cannot be
implemented in the IBM Microchannel architecture. However, programs
that use Functions 16 through 30 in Version 4.0 of this specification
must not use Functions 10 and 11. These functions won't work
correctly if a program attempts to mix the use of the new functions
(Functions 16 through 30) and functions 10 and 11. Functions 10 and
11 are specific to the hardware on Intel expanded memory boards and
will not work correctly on all vendors expanded memory boards.
30
FUNCTION 11 RESERVED
In earlier versions of the Lotus/Intel/Microsoft Expanded Memory
Specification the use of this function was documented. This function
is now documented as "RESERVED" (i.e. not documented) in the public
versions of the specification and new programs should not use it.
Existing programs that use this function may still work correctly if
the hardware is capable of supporting them. Since IBM Microchannel
hardware is not capable of supporting this function, it cannot be
implemented in the IBM Microchannel architecture. However, programs
that use Functions 16 through 30 in Version 4.0 of this specification
must not use Functions 10 and 11. These functions won't work
correctly if a program attempts to mix the use of the new functions
(Functions 16 through 30) and functions 10 and 11. Functions 10 and
11 are specific to the hardware on Intel expanded memory boards and
will not work correctly on all vendors expanded memory boards.
31
FUNCTION 12 GET HANDLE COUNT
PURPOSE
The Get Handle Count function returns the number of open EMM handles
(including the operating system handle 0) in the system.
CALLING PARAMETERS
AH = 4Bh
Contains the Get Handle Count function.
RESULTS
These results are valid only if the status returned is zero.
BX = total_open_emm_handles
Contains the number of open EMM handles [including the
operating system handle (0)]. This number will not exceed
255.
REGISTERS MODIFIED
AX, BX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the number of active EMM handles.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
32
EXAMPLE
total_open_emm_handles DW ?
MOV AH, 4Bh ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV total_open_emm_handles, BX ; save total active handle count
33
FUNCTION 13 GET HANDLE PAGES
PURPOSE
The Get Handle Pages function returns the number of pages allocated to
a specific EMM handle.
CALLING PARAMETERS
AH = 4Ch
Contains the Get Handle Pages function.
DX = emm_handle
Contains the EMM handle.
RESULTS
These results are valid only if the status returned is zero.
BX = num_pages_alloc_to_emm_handle
Contains the number of logical pages allocated to the
specified EMM handle. This number never exceeds 2048
because the memory manager allows a maximum of 2048 pages
(32M bytes) of expanded memory.
REGISTERS MODIFIED
AX, BX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the number of pages allocated to
the EMM handle.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 83h NON-RECOVERABLE
The memory manager couldn't find the EMM handle your
program specified.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
34
EXAMPLE
emm_handle DW ?
pages_alloc_to_handle DW ?
MOV DX, emm_handle ; load EMM handle
MOV AH, 4Ch ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV pages_alloc_to_handle, BX ; save number of pages allocated
; to specified handle
35
FUNCTION 14 GET ALL HANDLES PAGES
PURPOSE
The Get All Handle Pages function returns an array of the open emm
handles and the number of pages allocated to each one.
CALLING PARAMETERS
AH = 4Dh
Contains the Get All Handle Pages function.
ES:DI = pointer to handle_page
Contains a pointer to an array of structures where a copy
of all open EMM handles and the number of pages allocated
to each will be stored. Each structure has these two
members:
.emm_handle
The first member is a word which contains the value of the
open EMM handle. The values of the handles this function
returns will be in the range of 0 to 255 decimal (0000h to
00FFh). The uppermost byte of the handle is always zero.
.pages_alloc_to_handle
The second member is a word which contains the number of
pages allocated to the open EMM handle.
RESULTS
These results are valid only if the status returned is zero.
BX = total_open_emm_handles
Contains the number of open EMM handles (including the
operating system handle [0]). The number cannot be zero
because the operating system handle is always active and
cannot be deallocated. This number will not exceed 255.
REGISTERS MODIFIED
AX, BX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the array.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
36
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager isn't
defined.
MOV AX, SEG handle_page
MOV ES, AX
LEA DI, handle_page ; ES:DI points to handle_page
MOV AH, 4Dh ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV total_open_handles, BX ; save total open handle count
37
FUNCTION 15 GET/SET PAGE MAP
GET PAGE MAP SUBFUNCTION
PURPOSE
The Get Page Map subfunction saves the mapping context for all
mappable memory regions (conventional and expanded) by copying the
contents of the mapping registers from each expanded memory board to a
destination array. The application must pass a pointer to the
destination array. This subfunction doesn't require an EMM handle.
Use this function instead of Functions 8 and 9 if you need to save or
restore the mapping context but don't want (or have) to use a handle.
CALLING PARAMETERS
AX = 4E00h
Contains the Get Page Map subfunction.
ES:DI = dest_page_map
Contains a pointer to the destination array address in
segment:offset format. Use the Get Size of Page Map Save
Array subfunction to determine the size of the desired
array.
RESULTS
These results are valid only if the status returned is zero.
dest_page_map
The array contains the state of all the mapping registers
on all boards in the system. It also contains any
additional information necessary to restore the boards to
their original state when the program invokes a Set
subfunction.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the array.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
38
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
dest_page_map DB ? DUP (?)
MOV AX, SEG dest_page_map
MOV ES, AX
LEA DI, dest_page_map ; ES:DI points to dest_page_map
MOV AX, 4E00h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
39
FUNCTION 15 GET/SET PAGE MAP (CONTINUED)
SET PAGE MAP SUBFUNCTION
PURPOSE
The Set Page Map subfunction restores the mapping context for all
mappable memory regions (conventional and expanded) by copying the
contents of a source array into the mapping registers on each expanded
memory board in the system. The application must pass a pointer to
the source array. This subfunction doesn't require an EMM handle.
Use this function instead of Functions 8 and 9 if you need to save or
restore the mapping context but don't want (or have) to use a handle.
CALLING PARAMETERS
AX = 4E01h
Contains the Set Page Map subfunction.
DS:SI = source_page_map
Contains a pointer to the source array address in
segment:offset format. The application must point to an
array which contains the mapping register state. Use the
Get Size of Page Map Save Array subfunction to determine
the size of the desired array.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has passed the array.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A3h NON-RECOVERABLE
The contents of the source array have been corrupted, or
the pointer passed to the subfunction is invalid.
EXAMPLE
source_page_map DB ? DUP (?)
40
MOV AX, SEG source_page_map
MOV DS, AX
LEA SI, source_page_map ; DS:SI points to source_page_map
MOV AX, 4E01h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
41
FUNCTION 15 GET/SET PAGE MAP (CONTINUED)
GET & SET PAGE MAP SUBFUNCTION
PURPOSE
The Get & Set subfunction simultaneously saves a current mapping
context and restores a previous mapping context for all mappable
memory regions (both conventional and expanded). It first copies the
contents of the mapping registers from each expanded memory board in
the system into a destination array. (The application must pass a
pointer to the destination array.) Then, the subfunction copies the
contents of a source array into the mapping registers on each of the
expanded memory boards. (The application must pass a pointer to the
source array.)
Use this function instead of Functions 8 and 9 if you need to save or
restore the mapping context but don't want (or have) to use a handle.
CALLING PARAMETERS
AX = 4E02h
Contains the Get & Set Page Map subfunction.
ES:DI = dest_page_map
Contains a pointer to the destination array address in
segment:offset format. The current contents of the map
registers will be saved in this array.
DS:SI = source_page_map
Contains a pointer to the source array address in
segment:offset format. The contents of this array will be
copied into the map registers. The application must point
to an array which contains the mapping register state.
This address is required only for the Set or Get and Set
subfunctions.
RESULTS
These results are valid only if the status returned is zero.
dest_page_map
The array contains the mapping state. It also contains any
additional information necessary to restore the original
state when the program invokes a Set subfunction.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has returned and passed both arrays.
42
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE the function code passed to the memory
manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A3h NON-RECOVERABLE
The contents of the source array have been corrupted, or
the pointer passed to the subfunction is invalid.
EXAMPLE
dest_page_map DB ? DUP (?)
source_page_map DB ? DUP (?)
MOV AX, SEG dest_page_map
MOV ES, AX
MOV AX, SEG source_page_map
MOV DS, AX
LEA DI, dest_page_map ; ES:DI points to dest_page_map
LEA SI, source_page_map ; DS:SI points to source_page_map
MOV AX, 4E02h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
43
FUNCTION 15 GET/SET PAGE MAP (CONTINUED)
GET SIZE OF PAGE MAP SAVE ARRAY SUBFUNCTION
PURPOSE
The Get Size of Page Map Save Array subfunction returns the storage
requirements for the array passed by the other three subfunctions.
This subfunction doesn't require an EMM handle.
CALLING PARAMETERS
AX = 4E03h
Contains the Get Size of Page Map Save Array subfunction.
The size of this array depends on how the expanded memory
system is configured and how the expanded memory manager is
implemented. Therefore, the size must be determined after
the memory manager is loaded.
RESULTS
These results are valid only if the status returned is zero.
AL = size_of_array
Contains the number of bytes that will be transferred to
the memory area an application supplies whenever a program
requests the Get, Set, or Get and Set subfunctions.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the array size.
AH = 80h NON-Recoverable the manager detected a malfunction in the
memory manager software.
AH = 81h NON-Recoverable the manager detected a malfunction in the
expanded memory hardware.
AH = 84h NON-Recoverable the function code passed to the memory
manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
size_of_array DB ?
MOV AX, 4E03h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
44
MOV size_of_array, AL ; save array size
45
FUNCTION 16 GET/SET PARTIAL PAGE MAP
GET PARTIAL PAGE MAP SUBFUNCTION
PURPOSE
The Get Partial Page Map subfunction saves a partial mapping context
for specific mappable memory regions in a system. Because this
function saves only a subset of the entire mapping context, it uses
much less memory for the save area and may be potentially faster than
Function 15. The subfunction does this by copying the contents of
selected mapping registers from each expanded memory board to a
destination array.
The application must pass a pair of pointers. The first points to a
structure which specifies which mappable segments to save; the second
points to the destination array.
Use this function instead of Functions 8 and 9 if you need to save or
restore the mapping context but don't want (or have) to use a handle.
CALLING PARAMETERS
AX = 4F00h
Contains the Get Partial Page Map subfunction.
DS:SI = partial_page_map
Contains a pointer to a structure which specifies only
those mappable memory regions which are to have their
mapping context saved. The structure members are described
below.
.mappable_segment_count
The first member is a word which specifies the number of
members in the word array which immediately follows it.
This number should not exceed the number of mappable
segments in the system.
.mappable_segment
The second member is a word array which contains the
segment addresses of the mappable memory regions whose
mapping contexts are to be saved. The segment address must
be a mappable segment. Use Function 25 to determine which
segments are mappable.
ES:DI = dest_array
Contains a pointer to the destination array address in
Segment:Offset format. To determine the size of the
required array, see the Get Size of Partial Page Map Save
Array subfunction.
RESULTS
46
These results are valid only if the status returned is zero.
dest_array
The array contains the partial mapping context and any
additional information necessary to restore this context to
its original state when the program invokes a Set
subfunction.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has saved the partial map context.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Bh NON-RECOVERABLE
One of the specified segments is not a mappable segment.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A3h NON-RECOVERABLE
The contents of the partial page map structure have been
corrupted, the pointer passed to the subfunction is
invalid, or the mappable_segment_count exceeds the number
of mappable segments in the system.
EXAMPLE
partial_page_map partial_page_map_struct <>
dest_array DB ? DUP (?)
MOV AX, SEG partial_page_map
MOV DS, AX
LEA SI, partial_page_map ; DS:SI points to
MOV AX, SEG dest_array ; partial_page_map
MOV ES, AX
LEA DI, dest_array ; ES:DI points to dest_array
MOV AX, 4F00h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
47
FUNCTION 16 GET/SET PARTIAL PAGE MAP (CONTINUED)
SET PARTIAL PAGE MAP SUBFUNCTION
PURPOSE
The Set Partial Page Map subfunction provides a mechanism for
restoring the mapping context for a partial mapping context for
specific mappable memory regions in a system. Because this function
restores only a subset of the entire mapping context and not the
entire systems mapping context, it uses much less memory for the save
area and is potentially faster than Function 15. The subfunction does
this by copying the contents of the source array to selected mapping
registers on each expanded memory board. The application passes a
pointer to the source array. Use this function instead of Functions 8
and 9 if you need to save or restore the mapping context but don't
want (or have) to use a handle.
CALLING PARAMETERS
AX = 4F01h
Contains the Set Partial Page Map subfunction.
source_array DB ? DUP (?)
DS:SI = source_array
Contains a pointer to the source array in segment:offset
format. The application must point to an array which
contains the partial mapping register state. To determine
the size of the required array, see the Get Size of Partial
Page Map Save Array subfunction.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has restored the partial mapping context.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
48
AH = A3h NON-RECOVERABLE
The contents of the source array have been corrupted, or
the pointer passed to the subfunction is invalid.
EXAMPLE
MOV AX, SEG source_array
MOV DS, AX
LEA SI, source_array ; DS:SI points to source_array
MOV AX, 4F01h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
49
FUNCTION 16 GET/SET PARTIAL PAGE MAP (CONTINUED)
GET SIZE OF PARTIAL PAGE MAP SAVE ARRAY SUBFUNCTION
PURPOSE
The Return Size subfunction returns the storage requirements for the
array passed by the other two subfunctions. This subfunction doesn't
require an EMM handle.
CALLING PARAMETERS
AX = 4F02h
Contains the Get Size of Partial Page Map Save Array
subfunction. The size of this array depends on the
expanded memory system configuration and the implementation
of the expanded memory manager. Therefore, it will vary
between hardware configurations and implementations and
must be determined after a specific memory manager is
loaded.
BX = number of pages in the partial array
Contains the number of pages in the partial map to be saved
by the Get/Set Partial Page Map subfunctions. This number
should be the same as the mappable_segment_count in the Get
Partial Page Map subfunction.
Results
These results are valid only if the status returned is zero.
AL = size_of_partial_save_array
Contains the number of bytes that will be transferred to
the memory area supplied by an application whenever a
program requests the Get or Set subfunction.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the array size.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
50
AH = 8Bh NON-RECOVERABLE
The number of pages in the partial array is outside the
range of physical pages in the system.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
number_of_pages_to_map DW ?
size_of_partial_save_array DB ?
MOV BX, number_of_pages_to_map
MOV AX, 4F02h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV size_of_partial_save_array, AL; save array size
51
FUNCTION 17 MAP/UNAMP MULTIPLE HANDLE PAGES
PURPOSE
This function can, in a single invocation, map (or unmap) logical
pages into as many physical pages as the system supports.
Consequently, it has less execution overhead than mapping pages one at
a time. For applications which do a lot of page mapping, this is the
preferred mapping method.
MAPPING MULTIPLE PAGES
The handle passed to this function determines what type of logical
pages are being mapped. Logical pages that Function 4 and Function 27
(Allocate Standard Pages subfunction) allocate are referred to as
pages and are 16K bytes. Logical pages that Function 27 (Allocate Raw
Pages subfunction) allocates are referred to as raw pages and might
not be the same size as the pages Function 4 and Function 27 (Allocate
Standard Pages subfunction) allocate.
UNMAPPING MULTIPLE PAGES
This function can make specific physical pages unavailable for reading
or writing. A logical page which is unmapped from a specific physical
page cannot be read or written from that physical page. The logical
page which is unavailable (unmapped) can be made available again by
mapping it, or a new logical page, at the physical page that was
unmapped. Unmapping a physical page is accomplished by setting the
logical page it is associated with to FFFFh.
You might unmap an entire set of mapped pages, for example, before
loading and executing a program. This ensures that the loaded program
won't be able to access the pages your program has mapped. However,
you must save the mapping context before you unmap the physical pages.
This enables you to restore it later so that you may access the memory
you had mapped there. You can save the mapping context with Functions
8, 15, or 16. You can restore the mapping context with Functions 9,
15, or 16.
MAPPING AND UNMAPPING MULTIPLE PAGES SIMULTANEOUSLY
Both mapping and unmapping pages can be done in the same invocation.
Mapping or unmapping no pages is not considered an error. If a
request to map or unmap zero pages is made, nothing is done and no
error is returned.
ALTERNATE MAPPING AND UNMAPPING METHODS
You can map or unmap pages using two methods. Both methods produce
identical results.
1 The first method specifies both a logical page and a physical page
at which the logical page is to be mapped. This method is an
extension of Function 5 (Map Handle Page).
52
2 The second method specifies both a logical page and a
corresponding segment address at which the logical page is to be
mapped. While this is functionally the same as the first method,
it may be easier to use the actual segment address of a physical
page than to use a number which only represents its location. The
memory manager verifies whether the specified segment address
falls on the boundary of a mappable physical page. The manager
then translates the segment address passed to it into the
necessary internal representation to map the pages.
MAP/UNMAP MULTIPLE HANDLE PAGES
LOGICAL PAGE/PHYSICAL PAGE METHOD
CALLING PARAMETERS
AX = 5000h
Contains the Map/Unmap Multiple Handle Pages subfunction
using the logical page/physical page method.
CX = log_to_phys_map_len
Contains the number of entries in the array. For example,
if the array contained four pages to map or unmap, then CX
would contain 4. The number in CX should not exceed the
number of mappable pages in the system.
DS:SI = pointer to log_to_phys_map array
Contains a pointer to an array of structures that contains
the information necessary to map the desired pages. The
array is made up of the following two elements:
.log_page_number
The first member is a word which contains the number of the
logical page which is to be mapped. Logical pages are
numbered zero relative, so the number for a logical page
can only range from zero to (maximum number of logical
pages allocated to the handle - 1).
If the logical page number is set to FFFFh, the physical
page associated with it is unmapped rather than mapped.
Unmapping a physical page makes it inaccessible for reading
or writing.
.phys_page_number
The second member is a word which contains the number of
the physical page at which the logical page is to be
mapped. Physical pages are numbered zero relative, so the
number for a physical page can only range from zero to
53
(maximum number of physical pages supported in the system -
1).
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The logical pages have been mapped, or unmapped, at the
specified physical pages.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager couldn't find the specified EMM handle. The
manager doesn't currently have any information pertaining
to the specified EMM handle. The program has probably
corrupted its EMM handle.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Ah RECOVERABLE
One or more of the mapped logical pages is out of the range
of logical pages allocated to the EMM handle. The program
can recover by attempting to map a logical page which is
within the bounds for the specified EMM handle. When this
error occurs, the only pages mapped were the ones valid up
to the point that the error occurred.
AH = 8Bh RECOVERABLE
One or more of the physical pages is out of the range of
mappable physical pages, or the log_to_phys_map_len exceeds
the number of mappable pages in the system. The program
can recover from this condition by attempting to map into
memory at a physical page which is in the range of the
physical page numbers supported by the system. When this
error occurs, the only pages mapped were the ones valid up
to the point that the error occurred.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
CX = log_to_segment_map_len
Contains the number of entries in the array. For example,
if the array contained four pages to map or unmap, then CX
would contain four.
DS:SI = pointer to log_to_segment_map array
Contains a pointer to an array of structures that contains
the information necessary to map the desired pages. The
array is made up of the following elements:
.log_page_number
The first member is a word which contains the number of the
logical pages to be mapped. Logical pages are numbered
zero relative, so the number for a logical page can range
from zero to (maximum number of logical pages allocated to
the handle - 1).
If the logical page number is set to FFFFh, the physical
page associated with it is unmapped rather than mapped.
Unmapping a physical page makes it inaccessible for reading
or writing.
.mappable_segment_address
The second member is a word which contains the segment
address at which the logical page is to be mapped. This
segment address must correspond exactly to a mappable
segment address. The mappable segment addresses are
available with Function 25 (Get Mappable Physical Address
Array)
REGISTERS MODIFIED
AX
STATUS
56
AH = 0 SUCCESSFUL
The logical pages have been mapped (or unmapped), at the
specified physical pages.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager could not find the specified EMM handle. The
manager doesn't have any information pertaining to the
specified EMM handle. The program has probably corrupted
its EMM handle.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Ah RECOVERABLE
One or more of the logical pages to be mapped is out of the
range of logical pages allocated to the EMM handle. The
program can recover from this condition by mapping a
logical page which is within the bounds for the specified
EMM handle. When this error occurs, the only pages mapped
or unmapped were the ones valid up to the point that the
error occurred.
AH = 8Bh RECOVERABLE
One or more of the mappable segment addresses specified is
not mappable, the segment address doesn't fall exactly on a
mappable address boundary, or the log_to_segment_map_len
exceeds the number of mappable segments in the system. The
program can recover from this condition by mapping into
memory on an exact mappable segment address. When this
error occurs, the only pages mapped were the ones valid up
to the point that the error occurred.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
MOV AX, SEG log_to_seg_map
MOV DS, AX
LEA SI, log_to_seg_map ; DS:SI points to log_to_seg_map
MOV CX, LENGTH log_to_seg_map ; load # of segments to
; map/unmap
MOV DX, emm_handle ; load handle
MOV AX, 5001h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
57
JNZ emm_err_handler ; jump to error handler on error
58
FUNCTION 18 REALLOCATE PAGES
PURPOSE
This function allows an application program to increase or decrease
(reallocate) the number of logical pages allocated to an EMM handle.
There are four reallocation cases of interest:
1 A reallocation count of zero. The handle assigned to application
remains assigned and is still available for use by the
application. The memory manager won't reassign the handle to any
other application. However, the handle will have any currently
allocated pages returned to the memory manager. The application
must invoke the Deallocate Pages function (Function 6) before
returning to DOS, or the handle will remain assigned and no other
application will be able to use it.
2 A reallocation count equal to the current allocation count. This
is not treated as an error, and a successful status is returned.
3 A reallocation count greater than the current allocation count.
The memory manager will attempt to add new pages to those pages
already allocated to the specified EMM handle. The number of new
pages added is the difference between the reallocation count and
the current allocation count. The sequence of logical pages
allocated to the EMM handle remains continuous after this
operation. The newly allocated pages have logical page numbers
which begin where the previously allocated pages ended, and
continue in ascending sequence.
4 A reallocation count less than the current allocation count. The
memory manager will attempt to subtract some of the currently
allocated pages and return them to the memory manager. The number
of old pages subtracted is the difference between the current
allocation count and the re-allocation count. The pages are
subtracted from the end of the sequence of pages currently
allocated to the specified EMM handle. The sequence of logical
pages allocated to the EMM handle remains continuous after this
operation.
The handle determines what type of logical pages are being
reallocated. Logical pages which were originally allocated with
Function 4 or Function 27 (Allocate Standard Pages subfunction) are
called pages and are 16K bytes long. Logical pages which were
allocated with Function 27 (Allocate Raw Pages subfunction) are called
raw pages and might not be the same size as pages allocated with
Function 4 or Function 27 (Allocate Standard Pages subfunction).
CALLING PARAMETERS
AH = 51h
Contains the Reallocate Handle Pages function.
DX = handle
Contains the EMM handle.
59
BX = reallocation_count
Contains the total number of pages this handle should have
allocated to it after this function is invoked.
RESULTS
These results are valid only if the status returned is zero.
BX = number of pages allocated to handle after reallocation
Contains the number of pages now allocated to the EMM
handle after the pages have been added or subtracted. If
the status returned is not zero, the value in BX is equal
to the number of pages allocated to the handle prior to the
invocation of this function. This information can be used
to verify that the request generated the expected results.
REGISTERS MODIFIED
AX, BX
STATUS
AH = 00h SUCCESSFUL
The pages specified have been added or subtracted to or
from the handle specified.
AH = 80h NON-Recoverable the manager has detected a malfunction in
the memory manager software.
AH = 81h NON-Recoverable the manager has detected a malfunction in
the expanded memory hardware.
AH = 83h NON-Recoverable the manager could not find the specified
EMM handle. The manager doesn't have any information
pertaining to the specified EMM handle. The program may
have corrupted its EMM handle.
AH = 84h NON-Recoverable the function code passed to the manager is
not defined.
AH = 87h Recoverable the number of pages that are available in the
system is insufficient for the new allocation request. The
program can recover from this condition by specifying fewer
pages be allocated to the EMM handle.
AH = 88h Recoverable the number of unallocated pages is insufficient
for the new allocation request. The program can recover
from this condition by either requesting again when
additional pages are available or specifying fewer pages.
MOV BX, realloc_count ; specify count
MOV AH, 51h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV current_alloc_page_count, BX
61
FUNCTION 19 GET/SET HANDLE ATTRIBUTE
DESIGN CONSIDERATIONS
This function is an option which will probably not be available in a
typical expanded memory manager, system, or memory board. Most
personal computer systems disable memory refresh signals for a
considerable period during a warm boot. This can corrupt some of the
data in memory boards, even though there is no problem with the design
of the memory board, its operation, or the memory chips. This memory
refresh deficiency is present in the software design of the ROM BIOS
in most personal computer systems.
The majority of memory board designs, chip types, or personal computer
systems won't be able to support the non-volatility feature. The
reason that this ROM BIOS deficiency is not evident in the
conventional or extended memory area is that the ROM BIOS always
initializes this area during a warm boot. Memory data integrity is
not a problem with the conventional or extended memory region, because
it isn't physically possible to have data retained there across a warm
boot event -- the ROM BIOS sets it to zero.
Consequently, expanded memory board manufacturers should not supply
this function unless their board can guarantee the integrity of data
stored in the board's memory during a warm boot. Generally, this
means the memory board has an independent memory refresh controller
which does not depend on the system board's memory refresh.
If the expanded memory manager, system, or memory board cannot support
this feature, it should return the not supported status described in
the function.
62
FUNCTION 19 GET/SET HANDLE ATTRIBUTE (CONTINUED)
GET HANDLE ATTRIBUTE SUBFUNCTION
PURPOSE
This subfunction returns the attribute associated with a handle. The
attributes are volatile or non-volatile. Handles with non-volatile
attributes enable the memory manager to save the contents of a
handle's pages between warm boots. However, this function may be
disabled with a user option or may not be supported by the memory
board or system hardware.
If the handle's attribute has been set to non-volatile, the handle,
its name (if it is assigned one), and the contents of the pages
allocated to the handle are all maintained after a warm boot.
CALLING PARAMETERS
AX = 5200h
Contains the Get Handle Attribute subfunction.
DX = handle
Contains the EMM handle.
RESULTS
These results are valid only if the status returned is zero.
AL = handle attribute
Contains the EMM handle's attribute. The only attributes a
handle may have are volatile or non-volatile. A value of
zero indicates the handle is volatile. A value of one
indicates that the handle is non-volatile.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The handles attribute has been obtained.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager couldn't find the specified EMM handle. The
manager doesn't have any information pertaining to the
specified EMM handle. The program may have corrupted its
EMM handle.
63
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 91h NON-RECOVERABLE
This feature is not supported.
EXAMPLE
emm_handle DW ?
handle_attrib DB ?
MOV DX, emm_handle ; specify EMM handle
MOV AX, 5200h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV handle_attrib, AL ; save handle attribute
64
FUNCTION 19 GET/SET HANDLE ATTRIBUTE (CONTINUED)
SET HANDLE ATTRIBUTE SUBFUNCTION
PURPOSE
This subfunction can be used to modify the attribute which a handle
has associated with it. The attributes which a handle may have are
volatile or non-volatile. The non-volatile attribute enables the EMM
to save the contents of a handle's pages between warm boots. However,
this function may be disabled with a user option or may not be
supported by the memory board or system hardware.
If the handle's attribute has been set to non-volatile, the handle,
its name (if it is assigned one), and the contents of the pages
allocated to the handle are all maintained after a warm boot.
CALLING PARAMETERS
AX = 5201h
Contains the Set Handle Attribute function.
DX = handle
Contains the EMM handle.
BL = new handle attribute
Contains the handle's new attribute. A value of zero
indicates that the handle should be made volatile. A value
of one indicates that the handle should be made non-
volatile.
A volatile handle attribute instructs the memory manager to
deallocate both the handle and the pages allocated to it
after a warm boot. If all handles have the volatile
attribute (the default attribute) at warm boot, the handle
directory will be empty and all of expanded memory will be
initialized to zero immediately after a warm boot.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The handles attribute has been modified.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager could not find the specified EMM handle. The
65
manager doesn't have any information pertaining to the
specified EMM handle. The program may have corrupted its
EMM handle.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 90h NON-RECOVERABLE
The attribute type is undefined.
AH = 91h NON-RECOVERABLE
This feature is not supported.
EXAMPLE
emm_handle DW ?
new_handle_attrib DB ?
MOV DX, emm_handle ; specify EMM handle
MOV BL, new_handle_attrib ; specify the set attribute
MOV AX, 5201h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
66
FUNCTION 19 GET/SET HANDLE ATTRIBUTE (CONTINUED)
GET ATTRIBUTE CAPABILITY SUBFUNCTION
PURPOSE
This subfunction can be used to determine whether the memory manager
can support the non-volatile attribute.
CALLING PARAMETERS
AX = 5202h
Contains the Get Attribute Capability subfunction.
RESULTS
These results are valid only if the status returned is zero.
AL = attribute capability
Contains the attribute capability. A value of zero
indicates that the memory manager and hardware supports
only volatile handles. A value of one indicates that the
memory manager/hardware supports both volatile and non-
volatile handles.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The attribute capability has been returned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
attrib_capability DB ?
MOV AX, 5202h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV attrib_capability, AL ; save attribute capability
67
FUNCTION 20 GET/SET HANDLE NAME
GET HANDLE NAME SUBFUNCTION
PURPOSE
This subfunction gets the eight character name currently assigned to a
handle. There is no restriction on the characters which may be used
in the handle name (that is, anything from 00h through FFh).
The handle name is initialized to ASCII nulls (binary zeros) three
times: when the memory manager is installed, when a handle is
allocated, and when a handle is deallocated. A handle with a name
which is all ASCII nulls, by definition, has no name. When a handle
is assigned a name, at least one character in the name must be a non-
null character in order to distinguish it from a handle without a
name.
CALLING PARAMETERS
AX = 5300h
Contains the Get Handle Name function.
DX = handle number
Contains the EMM handle.
ES:DI = pointer to handle_name array
Contains a pointer to an eight-byte array into which the
name currently assigned to the handle will be copied.
RESULTS
These results are valid only if the status returned is zero.
handle_name array
Contains the name associated with the specified handle.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The handle name has been returned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager couldn't find the specified EMM handle. The
68
manager doesn't have any information on the specified EMM
handle. The program may have corrupted its EMM handle.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
handle_name DB 8 DUP (?)
emm_handle DW ?
MOV AX, SEG handle_name
MOV ES, AX
LEA DI, handle_name ; ES:DI points to handle_name
MOV DX, emm_handle ; specify EMM handle
MOV AX, 5300h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
69
FUNCTION 20 GET/SET HANDLE NAME
SET HANDLE NAME SUBFUNCTION
PURPOSE
This subfunction assigns an eight character name to a handle. There
is no restriction on the characters which may be used in the handle
name. The full range of values may be assigned to each character in a
name (that is, 00h through FFh).
At installation, all handles have their name initialized to ASCII
nulls (binary zeros). A handle with a name consisting of all ASCII
nulls has no name. When a handle is assigned a name, at least one
character in the name must be a non-null character in order to
distinguish it from a handle without a name. No two handles may have
the same name.
A handle can be renamed at any time by setting the handles name to a
new value. A handle can have its name removed by setting the handle's
name to all ASCII nulls. When a handle is deallocated, its name is
removed (set to ASCII nulls).
CALLING PARAMETERS
AX = 5301h
Contains the Set Handle Name function.
DX = handle number
Contains the EMM handle.
DS:SI = pointer to handle_name
Contains a pointer to a byte array which contains the name
that is to be assigned to the handle. The handle name must
be padded with nulls if the name is less than eight
characters long.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The handle name has been assigned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager couldn't find the specified EMM handle. The
manager doesn't currently have any information pertaining
70
to the specified EMM handle. The program may have
corrupted its EMM handle.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A1h RECOVERABLE
A handle with this name already exists. The specified
handle was not assigned a name.
EXAMPLE
handle_name DB "AARDVARK"
emm_handle DW ?
MOV AX, SEG handle_name
MOV DS, AX
LEA SI, handle_name ; DS:SI points to handle_name
MOV DX, emm_handle ; specify EMM handle
MOV AX, 5301h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
71
FUNCTION 21 GET HANDLE DIRECTORY
GET HANDLE DIRECTORY SUBFUNCTION
PURPOSE
This function returns an array which contains all active handles and
the names associated with each. Handles which have not been assigned
names have a default name of all ASCII nulls (binary zeros). When a
handle is first allocated, or when all the pages belonging to a handle
are deallocated (that is, an open handle is closed), its default name
is set to ASCII nulls. It takes a subsequent assignment of a name for
a handle to have a name after it has been opened. The full range of
values may be assigned to each character in a name (that is, 00h
through FFh).
The number of bytes required by the array is:
10 bytes * total number of handles
The maximum size of this array is:
(10 bytes/entry) * 255 entries = 2550 bytes.
CALLING PARAMETERS
AX = 5400h
Contains the Get Handle Directory function.
ES:DI = pointer to handle_dir
Contains a pointer to an area of memory into which the
memory manager will copy the handle directory. The handle
directory is an array of structures. There are as many
entries in the array as there are open EMM handles. The
structure consists of the following elements:
.handle_value
The first member is a word which contains the value of the
open EMM handle.
.handle_name
The second member is an 8 byte array which contains the
ASCII name associated with the EMM handle. If there is no
name currently associated with the handle, it has a value
of all zeros (ASCII nulls).
RESULTS
These results are valid only if the status returned is zero.
72
handle_dir
Contains the handle values and handle names associated with
each handle value.
AL = number of entries in the handle_dir array
Contains the number of entries in the handle directory
array. This is also the same as the number of open
handles. For example, if only one handle is active, AL
will contain a one.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The handle directory has been returned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
handle_dir handle_dir_struct 255 DUP (?)
num_entries_in_handle_dir DB ?
MOV AX, SEG handle_dir
MOV ES, AX
LEA DI, handle_dir ; ES:DI points to handle_dir
MOV AX, 5400h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV num_entries_in_handle_dir, AL ; save number of entries
73
FUNCTION 21 GET HANDLE DIRECTORY
SEARCH FOR NAMED HANDLE SUBFUNCTION
PURPOSE
This subfunction searches the handle name directory for a handle with
a particular name. If the named handle is found, this subfunction
returns the handle number associated with the name. At the time of
installation, all handles have their names initialized to ASCII nulls.
A handle with a name which is all ASCII nulls has, by definition, no
name. When a handle is assigned a name, at least one character in the
name must be a non-null character in order to distinguish it from a
handle without a name.
CALLING PARAMETERS
AX = 5401h
Contains the Search for Named Handle subfunction.
DS:SI = handle_name
Contains a pointer to an 8-byte string that contains the
name of the handle be searched for.
RESULTS
These results are valid only if the status returned is zero.
DX = value of named handle
The value of the handle which matches the handle name
specified.
REGISTERS MODIFIED
AX, DX
STATUS
AH = 0 SUCCESSFUL
The handle value for the named handle has been found.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
74
AH = A0h RECOVERABLE
No corresponding handle could be found for the handle name
specified.
AH = A1h NON-RECOVERABLE
A handle found had no name (all ASCII nulls).
EXAMPLE
named_handle DB 'AARDVARK'
named_handle_value DW ?
MOV AX, SEG named_handle
MOV DS, AX
LEA SI, named_handle ; DS:SI points to named_handle
MOV AX, 5401h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV named_handle_value, DX ; save value of named handle
75
FUNCTION 21 GET HANDLE DIRECTORY
GET TOTAL HANDLES SUBFUNCTION
PURPOSE
This subfunction returns the total number of handles that the memory
manager supports, including the operating system handle (handle value
0).
CALLING PARAMETERS
AX = 5402h
Contains the Get Total Handles subfunction.
RESULTS
These results are valid only if the status returned is zero.
BX = total_handles
The value returned represents the maximum number of handles
which a program may request the memory manager to allocate
memory to. The value returned includes the operating
system handle (handle value 0).
REGISTERS MODIFIED
AX, BX
STATUS
AH = 0 SUCCESSFUL
The total number of handles supported has been returned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
total_handles DW ?
MOV AX, 5402h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV total_handles, BX ; save total handle count
76
FUNCTION 22 ALTER PAGE MAP & JUMP
PURPOSE
This function alters the memory mapping context and transfers control
to the specified address. It is analogous to the FAR JUMP in the 8086
family architecture. The memory mapping context which existed before
the invocation of this function is lost.
Mapping no pages and jumping is not considered an error. If a request
to map zero pages and jump is made, control is transferred to the
target address, and this function performs a far jump.
CALLING PARAMETERS
AH = 55h
Contains the Alter Page Map & Jump function.
AL = physical page number/segment selector
Contains a code which indicates whether the value contained
in the .log_phys_map.phys_page_number_seg are physical page
numbers or are the segment address representation of the
physical page numbers. A zero in AL indicates that the
values are physical page numbers. A one in AL indicates
that the values in these members are the segment address
representations of the physical page numbers.
DX = handle number
Contains the EMM handle.
DS:SI = pointer to map_and_jump structure
Contains a pointer to a structure that contains the
information necessary to map the desired physical pages and
jump to the target address. The structure consists of the
following elements:
.target_address
The first member is a far pointer which contains the target
address to which control is to be transferred. The address
is represented in segment:offset format. The offset
portion of the address is stored in the low portion of the
double word.
.log_phys_map_len
The second member is a byte which contains the number of
entries in the array of structures which immediately
77
follows it. The array is as long as the application
developer needs to map the desired logical pages into
physical pages. The number of entries cannot exceed the
number of mappable pages in the system.
.log_phys_map_ptr
The third member is a pointer to an array of structures
which contain the logical page numbers and Alternate DMA
register sets physical page numbers or segment addresses at
which they are to be mapped. Each entry in the array of
structures contains the following two elements:
.log_page_number
The first member of this structure is a word which contains
the number of the logical page to be mapped.
.phys_page_number_seg
The second member of this structure is a word which
contains either the physical page number or the segment
address representation of the physical page number at which
the previous logical page number is to be mapped. The
value passed in AL determines the type of representation.
Values in registers which don't contain required parameters maintain
the values across the jump. The values in registers (with the
exception of AX) and the flag state at the beginning of the function
are still in the registers and flags when the target address is
reached.
STATUS
AH = 0 SUCCESSFUL
Control has been transferred to the target address.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager could not find the specified EMM handle. The
manager does not currently have any information pertaining
to the specified EMM handle. The program may have
corrupted its EMM handle.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
78
AH = 8Ah RECOVERABLE
One or more of the logical pages to map into a
corresponding physical page is out of the range of logical
pages which are allocated to the EMM handle. The program
can recover from this condition by mapping a logical page
which is within the bounds for the EMM handle.
AH = 8Bh RECOVERABLE
One or more of the physical pages is out of the range of
allowable physical pages, or the log_phys_map_len exceeds
the number of mappable pages in the system. Physical page
numbers are numbered zero relative. The program can
recover from this condition by mapping into memory at a
physical page which is in the range of supported physical
pages.
AH = 8Fh RECOVERABLE
The subfunction parameter is invalid.
MOV AX, SEG map_and_jump
MOV DS, AX
LEA SI, map_and_jump ; DS:SI points to map_and_jump
MOV DX, emm_handle
MOV AH, 55h ; load function code
MOV AL, phys_page_or_seg_mode ; specify physical page or seg
; mode
INT 67h ; call memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
79
FUNCTION 23 ALTER PAGE MAP & CALL
ALTER PAGE MAP & CALL SUBFUNCTION
PURPOSE
This subfunction saves the current memory mapping context, alters the
specified memory mapping context, and transfers control to the
specified address. It is analogous to the FAR CALL in the 8086 family
architecture. Just as a return from a FAR CALL restores the original
value in the code segment register, this subfunction restores the
state of the specified mapping context after the return.
There is no explicit expanded memory subfunction which emulates a
return from a FAR CALL. However, this facility is implicitly
available through the standard return from a FAR CALL. The following
paragraphs describe how this works:
After this function is invoked, unless an error is detected, the
memory manager will transfer control to the address specified. If an
error occurs, the memory manager returns immediately with the error
code in the AH register. Otherwise, the memory manager pushes on the
stack information which enables it to restore the mapping context
after the return.
When the called procedure wants to return to the calling procedure, it
simply issues a standard FAR RETURN. The memory manager traps this
return, restores the specified mapping context, and returns to the
calling procedure. The memory manager also returns a status from a
successful return just as it does for all functions.
Developers using this subfunction must make allowances for the
additional stack space this subfunction will use.
CALLING PARAMETERS
AH = 56h
Contains the Alter Page Map & Call function.
AL = physical page number/segment selector
Contains a code which indicates whether the value contained
in the
80
.new_page_map.phys_page_number_seg/.old_page_map.phys_page_number_seg
members are physical pages numbers or are the segment
address representation of the physical page numbers. A
value of zero in AL indicates that the values in these
members are physical page numbers. A value of one in AL
indicates that the values in these members are the segment
address representations of the physical page numbers.
DX = handle number
Contains the EMM handle.
DS:SI = pointer to map_and_call structure
Contains a pointer to a structure which contains the
information necessary to map the desired physical pages and
call the target address. The structure members are
described here:
.target_address
The first member is a far pointer which contains the target
address to which control is to be transferred. The address
is represented in segment:offset format. The offset
portion of the address is stored in the low portion of the
pointer. The application must supply this value.
.new_page_map_len
The second member is a byte which contains the number of
entries in the new mapping context to which
new_page_map_ptr points. This number cannot exceed the
number of mappable pages in the system.
.new_page_map_ptr
The third member is a far pointer that points to an array
of structures which contains a list of the logical page
numbers and the physical page numbers/segments at which
they are to be mapped immediately after the call. The
contents of the new array of structures are described at
the end of the map_and_call structure.
.old_page_map_len
The fourth member is a byte which contains the number of
entries in the old mapping context to which
old_page_map_ptr points. This number cannot exceed the
number of mappable pages in the system.
.old_page_map_ptr
The fifth member is a far pointer that points to an array
of structures which contains a list of the logical page
numbers and the physical page numbers/segments at which
they are to be mapped immediately after the return. The
contents of the old array of structures are described at
the end of the map_and_call structure.
.reserved
The sixth member is reserved for use by the memory manager.
Each entry in the old and new array of structures contains two
elements:
81
.log_page_number
The first member of this structure is a word which contains
a logical page number which is to be mapped at the
succeeding physical page number/segment immediately after
the CALL (in the case of the new array of structures) or
after the RETURN (in the case of the old array of
structures).
.phys_page_number_seg
The second member of this structure is a word which
contains either the physical page number or the segment
address representation of the physical page number/segment
at which the preceding logical page is to be mapped
immediately after the CALL (in the case of the new array of
structures) or after the RETURN (in the case of the old
array of structures).
Values in registers which don't contain required parameters maintain
the values across the call. The values in registers (with the
exception of AX) and the flag state at the beginning of the function
are still in the registers and flags when the target address is
reached.
STATUS
AH = 0 SUCCESSFUL
Control has been transferred to the target address.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager couldn't find the specified EMM handle. The
manager doesn't have any information pertaining to the
specified EMM handle. The program may have corrupted its
EMM handle.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Ah RECOVERABLE
One or more of the logical pages to map into a
corresponding physical page is out of the range of logical
pages which are allocated to the EMM handle. The program
can recover from this condition by mapping a logical page
which is within the bounds for the EMM handle.
82
AH = 8Bh RECOVERABLE
One or more of the physical pages is out of the range of
allowable physical pages, or you've specified more physical
pages than exist in the system. Physical page numbers are
numbered zero relative. The program can recover from this
condition by mapping a physical page which is in the range
from zero to three.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
MOV AX, SEG map_and_call
MOV DS, AX
LEA SI, map_and_call ; DS:SI points to map_and_call
MOV DX, emm_handle ; specify EMM handle
MOV AH, 56h ; load function code
MOV AL, phys_page_or_seg_mode ; specify physical page or seg
; mode
INT 67h ; control is actually
; transferred to the called
; procedure at this point
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
83
FUNCTION 23 ALTER PAGE MAP & CALL
GET PAGE MAP STACK SPACE SIZE SUBFUNCTION
PURPOSE
Since the Alter Page Map & Call function pushes additional information
onto the stack, this subfunction returns the number of bytes of stack
space the function requires.
CALLING PARAMETERS
AX = 5602h
Contains the Get Page Map Stack Space Size subfunction.
RESULTS
These results are valid only if the status returned is zero.
BX = stack space required
Contains the number of bytes which the Alter Page Map &
Call function will require. In other words, BX contains
the number (including the return address) which has to be
added to the stack pointer to remove all elements from the
stack.
REGISTERS MODIFIED
AX, BX
STATUS
AH = 0 SUCCESSFUL
The size of the array has been returned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
stack_space_reqd DW ?
MOV AX, 5602h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
84
MOV stack_space_reqd, BX ; save required stack size count
85
FUNCTION 24 MOVE/EXCHANGE MEMORY REGION
MOVE MEMORY REGION SUBFUNCTION
PURPOSE
This subfunction copies a region of memory in the following memory
source/destination combinations.
o conventional memory to conventional memory
o conventional memory to expanded memory
o expanded memory to conventional memory
o expanded memory to expanded memory
You do not have to save and restore the expanded memory mapping
context to perform these move operations. The current mapping context
is maintained throughout this operation.
The length of the region is limited by the amount of expanded memory
allocated to the handles specified.
However, in most practical applications, the region length will be
considerably smaller. A region length of zero is not an error, and no
move will be performed.
A region length which exceeds 16K bytes is not an error. In this case
the function assumes that a group of logical pages is the target for
the move. The logical page specified represents the first logical
page in which the move will take place. If the region length exceeds
16K bytes, or if the region is less than 16K bytes but spans logical
pages, there must be sufficient logical pages remaining after the
first logical page for the entire region to fit.
If your application needs to save a region of conventional memory in
expanded memory, you can move it without having to perform a save or
restore of the current mapping context.
The memory manager maintains the context. A move of up to 1M byte may
be performed, although practical lengths are substantially less than
this value.
If the source and destination handles are identical, the source and
destination regions are tested for overlap before the move. If they
overlap, the move direction is chosen so that the destination region
receives an intact copy of the source region. A status will be
returned indicating that this overlap has occurred.
CALLING PARAMETERS
AX = 5700h
Contains the Move Memory Region function.
DS:SI = pointer to exchange_source_dest structure
Contains a pointer to a data structure which contains the
source and destination information for the exchange. The
structure members are described here:
.region_length
The first member is a double word which specifies the
length of the memory region (in bytes) to be moved.
.source_memory_type
The second member is a byte which specifies the type of
memory where the source region resides. A value of zero
indicates that the source region resides in conventional
memory (excluding the page frame segment). A value of one
indicates that the source region resides in expanded
memory.
.source_handle
If the source region resides in expanded memory, the third
member is a word which specifies the handle number
associated with the source memory region. If the source
region resides in conventional memory, this variable has no
meaning and should be set to zero for future compatibility.
.source_initial_offset
The fourth member is a word which specifies the offset
within the source region from which to begin the move. If
the source region resides in expanded memory, the
source_initial_offset is relative to the beginning of the
16K logical page. Because the offset is relative to the
beginning of a 16K expanded memory page, it may only take
on values between 0000h and 3FFFh.
If the source region resides in conventional memory, the
source_initial_offset is a word which specifies the offset,
relative to the beginning of the source segment, from which
to begin the move. Because the offset is relative to the
beginning of a 64K-byte conventional memory segment, it may
take on values between 0000h and FFFFh.
.source_initial_seg_page
The fifth member is a word which specifies the initial
segment or logical page number within the source region
from which to begin the move. If the source region resides
in expanded memory, the value specifies the logical page
within the source region from which to begin the move. If
the source region resides in conventional memory, the
87
source_initial_seg_page specifies the initial segment
address within conventional memory from which to begin the
move.
.dest_memory_type
The sixth member is a byte which specifies the type of
memory where the destination region resides. A value of
zero indicates conventional memory; a value of one
indicates expanded memory.
.dest_handle
If the destination region resides in expanded memory, the
seventh member is a word which specifies the handle number
associated with the destination memory region. If the
destination region resides in conventional memory, this
variable has no meaning and should be set to zero for
future compatibility.
.dest_initial_offset
The eighth member is a word which specifies the offset
within the destination region from which to begin the move.
If the destination region resides in expanded memory, the
dest_initial_offset is relative to the beginning of the
16K-byte logical page. Because the offset is relative to
the beginning of a 16K-byte expanded memory page, it may
take on values between 0000h and 3FFFh.
If the destination region resides in conventional memory,
the dest_initial_offset is a word which specifies the
offset, relative to the beginning of the destination
segment, to begin the move. Because the offset is relative
to the beginning of a 64K conventional memory segment, it
may take on values between 0000h and FFFFh.
.dest_initial_seg_page
The ninth member is a word which specifies the initial
segment or logical page number within the destination
region from which to begin the move.
If the destination region resides in expanded memory then
the value specifies the logical page within the destination
region from which to begin the exchange.
If the destination region resides in conventional memory,
the dest_initial_seg_page specifies the initial segment
address within conventional memory from which to begin the
move.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The memory regions have been moved.
88
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager couldn't find either the source or destination
EMM handles. The memory manager doesn't have any
information on the handles specified. The program may have
corrupted its EMM handles.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Ah NON-RECOVERABLE
One or more of the logical pages is out of the range of
logical pages allocated to the source/destination handle.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 92h SUCCESSFUL
The source and destination expanded memory regions have the
same handle and overlap. This is valid for a move. The
move has been completed and the destination region has a
full copy of the source region. However, at least a
portion of the source region has been overwritten by the
move. Note that the source and destination expanded memory
regions with different handles will never physically
overlap because the different handles specify totally
different regions of expanded memory.
AH = 93h CONDITIONALLY-RECOVERABLE
The length of the source or destination expanded memory
region specified exceeds the length of the expanded memory
region allocated either the source or destination handle.
Insufficient pages are allocated to this handle to move a
region of the size specified. The program can recover from
this condition by allocating additional pages to the
destination or source handle and attempting to execute the
function again. However, if the application program
allocated as much expanded memory as it thought it needed,
this may be a program error and is not recoverable.
AH = 94h NON-RECOVERABLE
The conventional memory region and expanded memory region
overlap. This is invalid, the conventional memory region
cannot overlap the expanded memory region.
AH = 95h NON-RECOVERABLE
The offset within the logical page exceeds the length of
the logical page. The initial source or destination
offsets within an expanded memory region must be between
0000h and 3FFFh (16383 or (length of a logical page - 1)).
89
AH = 96h NON-RECOVERABLE
Region length exceeds 1M byte.
AH = 98h NON-RECOVERABLE
The memory source and destination types are undefined.
AH = A2h NON-RECOVERABLE
An attempt was made to wrap around the 1M-byte address
space of conventional memory during the move. The
combination of source/destination starting address and
length of the region to be moved exceeds 1M byte. No data
was moved.
EXAMPLE
move_source_dest move_source_dest_struct (?)
MOV AX, SEG move_source_dest
MOV DS, AX
LEA SI, move_source_dest ; DS:SI points to
; move_source_dest
MOV AX, 5700h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
90
FUNCTION 24 MOVE/EXCHANGE MEMORY REGION
EXCHANGE MEMORY REGION SUBFUNCTION
PURPOSE
This subfunction exchanges (using a string move) a region of memory in
any of the following memory source/destination combinations.
o conventional memory to conventional memory
o conventional memory to expanded memory
o expanded memory to conventional memory
o expanded memory to expanded memory
The term expanded memory region refers only to the area of memory
above 640K bytes (9FFFFh). If a system provides mappable conventional
memory, this function treats the mappable conventional memory regions
as ordinary conventional memory. The contents of the source region
and the destination region are exchanged.
The exchange operation can be performed without having to save and
restore the expanded memory mapping context. The current mapping
context is maintained throughout this operation. The length of the
region is limited to the amount of expanded memory allocated to the
specified EMM handles. A length of zero is not an error; however, no
exchange will be performed. A region length which exceeds 16K bytes
is not an error. In this case the function assumes that a group of
logical pages is the target for the exchange. The logical page
specified represents the first logical page in which the exchange will
take place. If the region length exceeds 16K bytes, or if the region
is less than 16K bytes but spans logical pages, there must be
sufficient logical pages remaining after the first logical page for
the entire region to fit.
If your application needs to exchange a region of conventional memory
with expanded memory, you can simply exchange it with the region of
interest without having to perform a save or restore of the current
mapping context.
An exchange of up to 1M byte may be performed, although practical
lengths are obviously below that value. Checking is done before
starting the exchange to prevent the possibility of overlap during the
exchange operation. Overlapping source and destination regions for a
exchange are invalid, and the exchange will not take place.
CALLING PARAMETERS
AX = 5701h
Contains the Exchange Memory Region function.
DS:SI = pointer to move_source_dest structure
Contains a pointer to the data structure which contains the
source & destination information for the exchange. The
structure members are described here:
.region_length
The first member is a double word which specifies the
length of the memory region to be exchanged.
.source_memory_type
The second member is a byte which specifies the type of
memory where the source region resides. A value of zero
indicates that the source region resides in conventional
memory. A value of one indicates that the source region
resides in expanded memory.
.source_handle
If the source region resides in expanded memory, the third
member is a word which specifies the handle number
associated with the source memory region. If the source
region resides in conventional memory, this variable has no
meaning and should be set to zero for future compatibility.
.source_initial_offset
The fourth member is a word which specifies the offset
within the source region from which to begin the exchange.
If the source region resides in expanded memory, the
source_initial_offset is relative to the beginning of the
16K-byte logical page. Because the offset is relative to
the beginning of a 16K-byte expanded memory page, it may
only take on values between 0000h and 3FFFh.
If the source region resides in conventional memory, the
source_initial_offset is a word which specifies the offset,
relative to the beginning of the source segment, to begin
the exchange at. Because the offset is relative to the
beginning of a 64K-byte conventional memory segment, it may
only take on values between 0000h and FFFFh.
.source_initial_seg_page
The fifth member is a word which specifies the initial
segment or logical page number within the source region
from which to begin the exchange.
If the source region resides in expanded memory then the
value specifies the logical page within the source region
from which to begin the exchange.
92
If the source region resides in conventional memory, the
source_initial_seg_page specifies the initial segment
address within conventional memory from which to begin the
exchange.
.dest_memory_type
The sixth member is a byte which specifies the type of
memory where the destination region resides. A value of
zero indicates that the destination region resides in
conventional memory (excluding the page frame segment). A
value of one indicates that the destination region resides
in expanded memory.
.dest_handle
If the destination region resides in expanded memory, the
seventh member is a word which specifies the handle number
associated with the destination memory region. If the
destination region resides in conventional memory , then
this variable has no meaning and should be set to zero for
future compatibility.
.dest_initial_offset
The eighth member is a word which specifies the offset
within the destination region from which to begin the
exchange.
If the destination region resides in expanded memory, the
dest_initial_offset is relative to the beginning of the
16K-byte logical page. Because the offset is relative to
the beginning of a 16K-byte expanded memory page, it may
only take on values between 0000h and 3FFFh.
If the destination region resides in conventional memory,
the dest_initial_offset is a word which specifies the
offset, relative to the beginning of the destination
segment, to begin the exchange at. Because the offset is
relative to the beginning of a 64K-byte conventional memory
segment, it may only take on values between 0000h and
FFFFh.
.dest_initial_seg_page
The ninth member is a word which specifies the initial
segment or logical page number within the destination
region from which to begin the exchange.
If the destination region resides in expanded memory, the
value specifies the logical page within the destination
region from which to begin the exchange.
If the destination region resides in conventional memory,
the dest_initial_seg_page specifies the initial segment
address within conventional memory from which to begin the
exchange.
REGISTERS MODIFIED
AX
93
STATUS
AH = 0 SUCCESSFUL
The memory regions have been exchanged.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 83h NON-RECOVERABLE
The manager could not find either the source or destination
EMM handles. The memory manager does not currently have
any information pertaining to the handles specified. The
program may have corrupted its EMM handles.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Ah NON-RECOVERABLE
One or more of the logical pages is out of the range of
logical pages allocated to the source/destination handle.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 93h CONDITIONALLY RECOVERABLE
The length of the source or destination expanded memory
region specified, exceeds the length of the expanded memory
region allocated to the source or destination specified EMM
handle. There are insufficient pages allocated to this
handle to exchange a region of the size specified. The
program can recover from this condition by attempting to
allocate additional pages to the destination or source
handle and attempting to execute the function again.
However, if the application program was allocated as much
expanded memory as it thought it needed, this may be a
program error and is therefore not recoverable.
AH = 94h NON-RECOVERABLE
The conventional memory region and expanded memory region
overlap. This is invalid, the conventional memory region
cannot overlap the expanded memory region.
AH = 95h NON-RECOVERABLE
The offset within the logical page exceeds the length of
the logical page. The initial source or destination
offsets within an expanded memory region must be between
0000h and 3FFFh (16383 or (length of a logical page - 1)).
AH = 96h NON-RECOVERABLE
Region length exceeds 1M Byte limit.
94
AH = 97h NON-RECOVERABLE
The source and destination expanded memory regions have the
same handle and overlap. This is invalid, the source and
destination expanded memory regions cannot have the same
handle and overlap when they are being exchanged. Note that
the source and destination expanded memory regions which
have different handles will never physically overlap
because the different handles specify totally different
regions of expanded memory.
AH = 98h NON-RECOVERABLE
The memory source and destination types are undefined.
AH = A2h NON-RECOVERABLE
An attempt was made to wrap around the 1M-byte address
space of conventional memory during the exchange. The
source starting address together with the length of the
region to be exchanged exceeds 1M byte. No data was
exchanged.
EXAMPLE
xchg_source_dest xchg_source_dest_struct (?)
MOV AX, SEG xchg_source_dest
MOV DS, AX
LEA SI, xchg_source_dest ; DS:SI points to
; xchg_source_dest
MOV AX, 5701h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
95
FUNCTION 25 GET MAPPABLE PHYSICAL ADDRESS ARRAY
GET MAPPABLE PHYSICAL ADDRESS ARRAY SUBFUNCTION
PURPOSE
This subfunction returns an array containing the segment address and
physical page number for each mappable physical page in a system. The
contents of this array provide a cross reference between physical page
numbers and the actual segment addresses for each mappable page in the
system. The array is sorted in ascending segment order. This does
not mean that the physical page numbers associated with the segment
addresses are also in ascending order.
CALLING PARAMETERS
AX = 5800h
Contains the Get Mappable Physical Address Array
subfunction.
ES:DI = mappable_phys_page
Contains a pointer to an application-supplied memory area
where the memory manager will copy the physical address
array. Each entry in the array is a structure containing
two members:
.phys_page_segment
The first member is a word which contains the segment
address of the mappable physical page associated with the
physical page number following it. The array entries are
sorted in ascending segment address order.
.phys_page_number
The second member is a word which contains the physical
page number which corresponds to the previous segment
address. The physical page numbers are not necessarily in
ascending order.
EXAMPLE 1
An expanded memory board has its page frame starting at address C0000h
and has no mappable conventional memory. For this configuration,
physical page 0 corresponds to segment address C000h, physical page 1
corresponds to segment address C400h, etc. The array would contain
the following data (in this order):
C000h, 00h
C400h, 01h
C800h, 02h
CC00h, 03h
EXAMPLE 2
96
An expanded memory board has a large page frame starting at address
C0000h and has mappable conventional memory from 90000h through
9FFFFh. For this configuration, physical page 0 corresponds to
segment address C000h, physical page 1 corresponds to segment address
C400h, etc. The array would contain the following data in the order
specified. Note that the expanded memory region always has the lowest
numerically valued physical page numbers.
These results are valid only if the status returned is zero.
CX = number of entries in the mappable_phys_page
Multiply this number by (SIZE mappable_phys_page_struct) to
determine the number of bytes the physical page address
array requires.
REGISTERS MODIFIED
AX, CX
STATUS
AH = 0 SUCCESSFUL
The hardware configuration array has been returned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
97
EXAMPLE
mappable_phys_page mappable_phys_page_struct (?)
MOV AX, SEG mappable_phys_page
MOV ES, AX
LEA DI, mappable_phys_page ; ES:DI points to
; mappable_phys_page
MOV AX, 5800h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV mappable_page_entry_count, CX ; save mappable page entry count
98
FUNCTION 25 GET MAPPABLE PHYSICAL ADDRESS ARRAY
GET MAPPABLE PHYSICAL ADDRESS ARRAY ENTRIES SUBFUNCTION
PURPOSE
This subfunction gets the number of entries which will be required for
the array the first subfunction returns.
CALLING PARAMETERS
AX = 5801h
Contains the Get Physical Page Address Array Entry Count
subfunction. This subfunction returns a word which
represents the number of entries in the array returned by
the previous subfunction. This number also represents the
number of mappable physical pages in a system.
RESULTS
These results are valid only if the status returned is zero.
CX = number of entries in the mappable_phys_page
Multiply this number by (SIZE mappable_phys_page_struct) to
determine the number of bytes the physical page address
array will require.
REGISTERS MODIFIED
AX, CX
STATUS
AH = 0 SUCCESSFUL
The physical page address array has been returned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
mappable_page_entry_count DW ?
MOV AX, 5801h ; load function code
INT 67h ; call memory manager
OR AH, AH ; check EMM status
99
JNZ emm_err_handler ; jump to error handler on error
MOV mappable_page_entry_count, CX ; save mappable page entry count
100
FUNCTION 26 GET EXPANDED MEMORY HARDWARE INFORMATION
This function is for use by operating systems only. This function can
be disabled at any time by the operating system. Refer to Function 30
for a description of how an operating system does this.
PURPOSE
This subfunction returns an array containing expanded memory hardware
configuration information for use by an operating system/environment.
CALLING PARAMETERS
AX = 5900h
Contains the Get Hardware Configuration Array subfunction.
ES:DI = hardware_info
Contains a pointer to a memory area that the operating
system supplies where the memory manager will copy expanded
memory hardware information. The structure contains these
five members:
.raw_page_size
The first member is a word which contains the size of a raw
mappable physical page in paragraphs (16 bytes). LIM
standard pages are always 16K bytes. However, other
implementations of expanded memory boards do not
necessarily comply with this standard and can emulate a
16K-byte page by mapping in multiple smaller pages. This
member specifies the size of a mappable physical page
viewed from the hardware implementation level.
.alternate_register_sets
The second member is a word which specifies the number of
alternate mapping register sets. The additional mapping
register sets are termed alternate mapping register sets in
this document.
All expanded memory boards have at least one set of
hardware registers to perform the logical to physical page
mapping. Some expanded memory boards have more than one
set of these mapping registers. This member specifies how
many of these alternate mapping register sets exist (beyond
the one set that all expanded memory boards have) on the
expanded memory boards in the system. If an expanded
101
memory card has only one set of mapping registers (that is,
no alternate mapping register sets) this member has a value
of zero.
.context_save_area_size
The third member is a word which contains the storage
requirements for the array required to save a mapping
context. The value returned in this member is exactly the
same as that returned by Function 15 (Get Size of Page Map
Save Array subfunction).
.DMA_channels
The fourth member is a word which contains the number of
register sets that can be assigned to DMA channels. These
DMA register sets, although similar in use to alternate
register sets, are for DMA mapping and not task mapping.
If the expanded memory hardware does not support DMA
register sets, care must be taken when DMA is taking place.
In a multitasking operating system, when one task is
waiting for DMA to complete, it is useful to be able to
switch to another task. However, if the DMA is taking
place in memory that the second task will need to remap,
remapping would be disastrous.
If the expanded memory hardware can detect when DMA is
occurring, the OS/E should allow task switches and
remapping during DMA. If no special support for DMA is
available, no remapping should be done when DMA is in
progress.
.DMA_channel_operation
The fifth member is a word which specifies a special case
for the DMA register sets. A value of zero specifies that
the DMA register sets behave as described in Function 28.
A value of one specifies that the expanded memory hardware
has only one DMA register set. In addition, if any channel
is mapped through this register set, then all channels are
mapped through it. For LIM standard boards, this value is
zero.
RESULTS
These results are valid only if the status returned is zero.
hardware_info
Contains the expanded memory hardware specific information
described above.
REGISTERS MODIFIED
AX
STATUS
102
AH = 0 SUCCESSFUL
The hardware configuration array has been returned.
AH = 80h NON-RECOVERABLE
The manager has detected a malfunction in the memory
manager software.
AH = 81h NON-RECOVERABLE
The manager has detected a malfunction in the expanded
memory hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the manager is not defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A4h NON-RECOVERABLE
Access to this function has been denied by the operating
system. The function cannot be used at this time.
EXAMPLE
hardware_info hardware_info_struct (?)
MOV AX, SEG hardware_info
MOV ES, AX
LEA DI, hardware_info ; ES:DI points to hardware_info
MOV AX, 5900h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
103
FUNCTION 26 GET EXPANDED MEMORY HARDWARE INFORMATION
GET UNALLOCATED RAW PAGE COUNT SUBFUNCTION
PURPOSE
The Get Unallocated Raw Page Count subfunction returns the number of
unallocated non-standard length mappable pages as well as the total
number of non-standard length mappable pages in expanded memory to the
operating system.
One variety of expanded memory board has a page size which is a sub-
multiple of 16K bytes. An expanded memory page which is a sub-
multiple of 16K is termed a raw page. An operating system may deal
with mappable physical page sizes which are sub-multiples of 16K
bytes.
If the expanded memory board supplies pages in exact multiples of 16K
bytes, the number of pages this function returns is identical to the
number Function 3 (Get Unallocated Page Count) returns. In this case,
there is no difference between a page and a raw page.
CALLING PARAMETERS
AX = 5901h
Contains the Get Unallocated Raw Page Count subfunction.
RESULTS
These results are valid only if the status returned is zero.
BX = unallocated raw pages
The number of raw pages that are currently available for
use.
DX = total raw pages
The total number of raw pages in expanded memory.
REGISTERS MODIFIED
AX, BX, DX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the number unallocated raw pages
and the number of total raw pages in expanded memory.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
104
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
EXAMPLE
unalloc_raw_pages DW ?
total_raw_pages DW ?
MOV AX, 5901h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV unalloc_raw_pages, BX ; save unallocated raw page
; count
MOV total_raw_pages, DX ; save total raw page count
105
FUNCTION 27 ALLOCATE STANDARD/RAW PAGES
ALLOCATE STANDARD PAGES SUBFUNCTION
PURPOSE
The Allocate Standard Pages subfunction allocates the number of
standard size (16K bytes) pages that the operating system requests and
assigns a unique EMM handle to these pages. The EMM handle owns these
pages until the operating system deallocates them. This subfunction
allows you to allocate zero pages to a handle, unlike Function 4
(Allocate Pages).
This note affects expanded memory manager implementers and operating
system developers only. Applications should not use the following
characteristic of the memory manager. An application violating this
rule will be incompatible with future versions of Microsoft's
operating systems and environments.
To be compatible with this specification, an expanded memory manager
will provide a special handle which is available to the operating
system only. This handle will have a value of 0000h and will have a
set of pages allocated to it when the expanded memory manager driver
installs. The pages that the memory manager will automatically
allocate to handle 0000h are those that backfill conventional memory.
Typically, this backfill occurs between addresses 40000h (256K) and
9FFFFh (640K). However, the range can extend below and above this
limit if the hardware and memory manager have the capability.
An operating system won't have to invoke Function 27 to obtain this
handle because it can assume the handle already exists and is
available for use immediately after the expanded memory device driver
installs. When an operating system wants to use this handle, it uses
the special handle value of 0000h. The operating system will be able
to invoke any EMM function using this special handle value. To
allocate pages to this handle, the operating system need only invoke
Function 18 (Reallocate pages).
There are two special cases for this handle:
1. Function 27 (Allocate Standard Pages). This function must never
return zero as a handle value. Applications must always invoke
Function 27 to allocate pages and obtain a handle which identifies
the pages which belong to it. Since Function 27 never returns a
handle value of zero, an application will never gain access to
this special handle.
2. Function 6 (Deallocate Pages). If the operating system uses it to
deallocate the pages which are allocated to this handle, the pages
the handle owns will be returned to the manager for use. But the
handle will not be available for reassignment. The manager should
treat a deallocate pages function request for this handle the same
as a reallocate pages function request, where the number of pages
to reallocate to this handle is zero.
106
CALLING PARAMETERS
AX = 5A00h
Contains the Allocate Standard Pages subfunction.
BX = num_of_standard_pages_to_alloc
Contains the number of standard pages the operating system
wants to allocate.
RESULTS
These results are valid only if the status returned is zero.
DX = handle
Contains a unique EMM handle. The operating system must
use this EMM handle as a parameter in any function that
requires it. Up to 255 handles may be obtained. (Both
Function 27 and Function 4 must share the same 255
handles).
For all functions using this handle, the length of the
physical and logical pages allocated to it are standard
length (that is, 16K bytes).
REGISTERS MODIFIED
AX, DX
STATUS
AH = 0 SUCCESSFUL
The manager has allocated the pages to an assigned EMM raw
handle.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 85h RECOVERABLE
All EMM handles are being used.
AH = 87h RECOVERABLE
There aren't enough expanded memory pages present in the
system to satisfy the operating system's request.
AH = 88h RECOVERABLE
There aren't enough unallocated pages to satisfy the
operating system's request.
107
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
MOV BX, num_of_standard_pages_to_alloc
MOV AX, 5A00h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV emm_handle, DX ; save handle
108
FUNCTION 27 ALLOCATE STANDARD/RAW PAGES
ALLOCATE RAW PAGES SUBFUNCTION
PURPOSE
The Allocate Raw Pages subfunction allocates the number of non-
standard size pages that the operating system requests and assigns a
unique EMM handle to these pages. The EMM handle owns these pages
until the operating system deallocates them. This function allows you
to allocate zero pages to a handle, unlike Function 4 (Allocate
Pages).
A hardware vendor may design an expanded memory board that has a page
size which is a sub-multiple of 16K bytes. A physical page which is a
sub-multiple of 16K is termed a raw page. The operating system may
deal with page sizes which are sub-multiples of 16K bytes. The memory
manager must treat any function using a handle with raw pages
allocated to it by Allocate Raw Pages differently than it does a
handle that has normal 16K-byte pages allocated to it.
Handles which are assigned using Function 4 (Allocate pages) or
Function 27 (Allocate Standard Pages subfunction) must have pages
which are 16K bytes -- this is the length of a standard expanded
memory page. If the expanded memory board hardware is not able to
supply 16K-byte pages, the memory manager must emulate pages which are
16K bytes combining multiple non-standard size pages to form a single
16K-byte page.
Handles which are assigned using Function 27 (Allocate Raw Pages) are
called raw handles. All logical pages allocated to a raw handle may
have a non-standard length (that is, not 16K bytes). However, once
the operating system has allocated a number of raw pages to a handle,
it is the responsibility of the memory manager to recognize that raw
handle as one that has non-standard size pages allocated to it. The
memory manager must identify these handles and treat all functions
which use handles which have non-standard page lengths differently.
The logical page length becomes the length of the non-standard size
page for any raw handle that Function 27 assigns.
This note affects expanded memory manager implementers and operating
system developers only. Applications should not use the following
characteristic of the memory manager. An application violating this
rule will be incompatible with future versions of Microsoft's
operating systems and environments.
To be compatible with this specification, an expanded memory manager
will provide a special handle which is available to the operating
system only. This handle will have a value of 0000h and will have a
set of pages allocated to it when the expanded memory manager driver
installs. The pages that the memory manager will automatically
allocate to handle 0000h are those that backfill conventional memory.
Typically, this backfill occurs between addresses 40000h (256K) and
9FFFFh (640K). However, the range can extend below and above this
limit if the hardware and memory manager have the capability.
109
An operating system won't have to invoke Function 27 to obtain this
handle because it can assume the handle already exists and is
available for use immediately after the expanded memory device driver
installs. When an operating system wants to use this handle, it uses
the special handle value of 0000h. The operating system will be able
to invoke any EMM function using this special handle value. To
allocate pages to this handle, the operating system need only invoke
Function 18 (Reallocate pages).
There are two special cases for this handle:
1 Function 27 (Allocate Raw Pages). This function must never return
zero as a handle value. Applications must always invoke Function
27 to allocate pages and obtain a handle which identifies the
pages which belong to it. Since Function 27 never returns a
handle value of zero, an application will never gain access to
this special handle.
2 Function 6 (Deallocate Pages). If the operating system uses it to
deallocate the pages which are allocated to this special handle,
the pages the handle owns will be returned to the manager for use.
But the handle will not be available for reassignment. The
manager should treat a deallocate pages function request for this
handle the same as a reallocate pages function request, where the
number of pages to reallocate to this handle is zero.
CALLING PARAMETERS
AX = 5A01h
Contains the Allocate Raw Pages subfunction.
BX = num_of_raw_pages_to_alloc
Contains the number of raw pages the operating system wants
to allocate.
RESULTS
These results are valid only if the status returned is zero.
DX = raw handle
Contains a unique EMM raw handle. The operating system
must use this EMM raw handle as a parameter in any function
that requires it. Up to 255 handles may be obtained.
(Both Function 4 and Function 27 must share the same 255
handles).
For all functions using this raw handle, the length of the
physical and logical pages allocated to it may be non-
standard (that is, not 16K bytes).
REGISTERS MODIFIED
AH = 0 SUCCESSFUL
The manager has allocated the raw pages to an assigned EMM
raw handle.
110
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 85h RECOVERABLE
All EMM handles are being used.
AH = 87h RECOVERABLE
There aren't enough expanded memory raw pages present in
the system to satisfy the operating system's request.
AH = 88h RECOVERABLE
There aren't enough unallocated raw pages to satisfy the
operating system's request.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
MOV BX, num_of_raw_pages_to_alloc
MOV AX, 5A01h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV emm_raw_handle, DX ; save raw handle
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
DESIGN CONSIDERATIONS
The hardware support for the entire set of subfunctions described is
generally not present on every expanded memory board from every vendor
of expanded memory board products. For some of the subfunctions,
software emulation is provided. For other subfunctions, a certain
protocol in their use must be observed. The subfunctions for which
this is most crucial are those which address system DMA capabilities.
System DMA Capabilities & Expanded Memory Support of DMA
In a multitasking operating system, when one task is waiting for DMA
to complete, it is useful to be able to switch to another task. This
specification describes a capability which may be designed into
expanded memory boards to provide DMA into memory regions which may be
mapped out while the DMA is occurring. For expanded memory boards
that do not provide this, it is crucial to understand that while DMA
is in progress into a region of mappable memory, the memory mapping
context cannot be changed. That is, all DMA action must be complete
before any remapping of pages can be done.
Expanded Memory Support of DMA Register Sets
Expanded memory boards which have DMA registers sets could support DMA
into a region of mappable memory while the memory mapping context is
being switched. It is important to realize that these DMA register
sets are separate from the alternate map register sets. An example of
how an OS/E might use DMA registers sets follows:
EXAMPLE 1
1. Allocate a DMA register set.
2. Get current register set.
3. Set the DMA register set.
4. Map in the memory desired.
5. Get the DMA register set.
6. Set the original register set.
7. Assign the desired DMA channel to the DMA register set.
The preceding set of calls makes all DMA accesses for the desired DMA
channel get mapped through the current DMA register set regardless of
the current register set. In other words, the DMA register set
112
overrides the current mapping register set for DMA operations on the
DMA channel specified. A DMA channel that is not assigned to a DMA
register set has all its DMA operations mapped through the current
mapping register set.
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
The subfunction does one of two things depending on the map register
set which is active at the time this function is invoked:
1. If the preceding Set Alternate Map Register Set call was done with
the alternate map register set equal to zero (BL = 0), these
points apply:
a. The context save area pointer saved within EMM by the Set
Alternate Map Register Set subfunction) is returned by
this call. This pointer is always returned for boards
which do not supply alternate mapping register sets.
b. If the context save area pointer returned is not equal to
zero, this subfunction copies the contents of the mapping
registers on each expanded memory board in the system into
the save area specified by the pointer. The format of
this save area is the same as that returned by Function 15
(Get Page Map subfunction). This is intended to simulate
getting an alternate map register set. Note that the
memory manager does not allocate the space for the
context: the operating system must do so.
c. If the context save area pointer returned is equal to
zero, this subfunction does not copy the contents of the
mapping registers on each expanded memory board in the
system into the save area specified by the pointer.
d. The context save area pointer must have been initialized
by a previous Set Alternate Map Register Set call. Note
that the value of the context save area pointer saved
within EMM is zero immediately after installation.
e. The context save area must be initialized by a previous
Get Page Map call (Function 15).
2. If the preceding Set Alternate Map Register Set call was done with
the alternate map register set greater than zero (BL > 0), then
the number of the alternate map register set which is in use at
the time that this function is invoked is returned. The context
save area pointer is not returned in this case.
CALLING PARAMETERS
114
AX = 5B00h
Contains the Get Alternate Map Register Set subfunction.
RESULTS
These results are valid only if the status returned is zero.
IF (BL <> 0) current active alternate map register set number
Contains the alternate map register set which was active at
the time that this function was invoked.
ES:DI
Unaffected.
IF (BL = 0)
Indicates that a pointer to an area which contains the
state of all the map registers on all boards in the system,
and any additional information necessary to restore the
boards to their original state, has been returned.
ES:DI = pointer to a map register context save area
Contains a pointer to an operating system supplied context
save area. The pointer is in standard segment:offset
format. This pointer is always returned if the expanded
memory hardware does not supply alternate mapping register
sets.
The operating system first passes this pointer to the memory manager
whenever it invokes a Set Alternate Map Register Set subfunction (the
description follows). If the OS/E invokes this function before
invoking a Set Alternate Map Register Set subfunction, this function
returns a pointer value of zero. The OS/E must have allocated the
space for the save area. However, the OS must request that the memory
manager initialize the contents of this save area before it contains
any useful information.
The OS/E must initialize the save area it has allocated by invoking
Function 15 (Get Page Map subfunction). After the OS/E has done this,
the save area will contain the state of all the map registers on all
boards in the system. The save area will also contain any additional
information necessary to restore the boards to their original state
when the operating system invokes a Set Alternate Map Register Set
subfunction.
REGISTERS MODIFIED
AX, BX, ES:DI
STATUS
AH = 0 SUCCESSFUL
The manager got the alternate map register set.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
115
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A4h NON-RECOVERABLE
The operating system denied access to this function. The
function cannot be used at this time.
EXAMPLE
alt_map_reg_set DB ?
context_save_area_ptr_seg DW ?
context_save_area_ptr_offset DW ?
MOV AX, 5B00h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV alt_map_reg_set, BL
TEST BL, BL
JNZ no_ptr_returned
MOV context_save_area_ptr_seg, ES ; save pointer values
MOV context_save_area_ptr_offset, DI
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
The subfunction does one of two things, depending on the map register
set specified:
1 If the alternate map register set specified is zero, map register
set zero is activated. If the map register context restore area
pointer is not equal to zero, the contents of the restore area
pointed to by ES:DI are copied into register set zero on each
expanded memory board in the system. If the pointer is equal to
zero, the contents are not copied.
Regardless of its value, the map register context restore area
pointer is saved within the memory manager. It will be used
during the Get Alternate Map Register Set subfunction.
The operating system must supply the pointer to the area. This
subfunction is intended to simulate setting an alternate map
register set. Note that the operating system must allocate the
space for the context. The memory manager saves the context save
area pointer internally.
2 If the alternate map register set specified is not zero, the
alternate map register set specified is activated. The restore
area, which the operating system is pointing to, is not used.
CALLING PARAMETERS
AX = 5B01h
Contains the Set Alternate Map subfunction.
BL = new alternate map register set number
Contains the number of the alternate map register set which
is to be activated.
If BL <> 0
A pointer to a map register context restore area is not
required and the contents of ES:DI are unaffected and
ignored. The alternate map register set specified in BL is
activated if the board supports it.
If BL = 0
A pointer to an area which contains the state of all the
map registers on all boards in the system, and any
additional information necessary to restore the boards to
their original state, has been passed in ES:DI.
117
ES:DI = pointer to a map register context restore area
Contains a pointer to an OS/E supplied map register context
restore area. The pointer is in standard segment:offset
format. This pointer must always be passed if the expanded
memory hardware does not supply alternate mapping register
sets.
The memory manager must save this pointer whenever the OS/E
invokes this function. The OS/E must have allocated the
space for the restore area. Additionally, the contents of
this restore area must have been initialized by the memory
manager before it will contain any useful information. The
OS/E initializes the restore area it has allocated by
invoking Function 15 (Get Page Map subfunction). After the
OS/E has done this, the restore area will contain the state
of the map registers on all boards in the system, and any
additional information necessary to restore the boards to
their original state when the operating system invokes a
Set Alternate Map Register Set subfunction.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager set the alternate map register set.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 9Ah NON-RECOVERABLE
Alternate map register sets are supported, but the
alternate map register set specified is not supported.
AH = 9Ch NON-RECOVERABLE
Alternate map register sets are not supported, and the
alternate map register set specified is not zero.
AH = 9Dh NON-RECOVERABLE
Alternate map register sets are supported, but the
alternate map register set specified is either not defined
or not allocated.
118
AH = A3h NON-RECOVERABLE
The contents of the source array have been corrupted, or
the pointer passed to the subfunction is invalid.
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time.
EXAMPLE
alt_map_reg_set DB ?
context_restore_area_ptr_seg DW ?
context_restore_area_ptr_offset DW ?
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
This subfunction returns the storage requirements for the map register
context save area referenced by the other subfunctions.
CALLING PARAMETERS
AX = 5B02h
Contains the Get Alternate Map Save Array Size subfunction.
RESULTS
These results are valid only if the status returned is zero.
DX = size_of_array
Contains the number of bytes that will be transferred to
the memory area supplied by an operating system whenever an
operating system requests the Get, Set, or Get and Set
subfunction.
REGISTERS MODIFIED
AX, DX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the array size.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
120
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time.
EXAMPLE
size_of_array DW ?
MOV AX, 5B02h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV size_of_array, DX ; save size of array
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
The Allocate Alternate Map Register Set subfunction gets the number of
an alternate map register set for an operating system if an alternate
map register set is currently available for use. If the hardware does
not support alternate map register sets, an alternate map register set
number of zero will be returned.
The alternate map register set allocated may be referred to by this
number when using the Get or Set Alternate Map Register Set
subfunctions. The operating system can use these subfunctions to
switch map contexts very rapidly on expanded memory boards with
alternate map register sets.
This subfunction copies the currently active alternate map register
sets contents into the newly allocated alternate map register set's
mapping registers. This is done so that when the OS/E performs a Set
Alternate Map Register Set subfunction the memory mapped before the
allocation of the new alternate map will be available for reading and
writing. This function does not actually change the alternate map
register set in use, but in addition to allocating a new alternate map
register set, it prepares the new alternate map register set for a
subsequent Set Alternate Map Register Set subfunction.
CALLING PARAMETERS
AX = 5B03h
Contains the Allocate Alternate Map Register Set
subfunction.
RESULTS
These results are valid only if the status returned is zero.
BL = alternate map register set number
Contains the number of an alternate map register set. If
there are no alternate map register sets supported by the
hardware, a zero will be returned. In this case, the Get
Alternate Map function (Function 28) should be invoked in
order to obtain a pointer to a map register context save
area. The OS/E must supply this save area. The save area
is necessary because the hardware doesn't support alternate
map register sets.
REGISTERS MODIFIED
122
AX, BX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the array size.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 9Bh NON-RECOVERABLE
Alternate map register sets are supported. However, all
alternate map register sets are currently allocated.
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time.
EXAMPLE
alt_map_reg_num DB ?
MOV AX, 5B03h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV alt_map_reg_num, BL ; save # of alternate map reg
; set
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
The Deallocate Alternate Map Register Set subfunction returns the
alternate map register set to the memory manager for future use. The
memory manager may reallocate the alternate map register set when
needed.
This subfunction also makes the mapping context of the alternate map
register specified unavailable for reading or writing (unmapping).
This protects the pages previously mapped in an alternate map register
set by making them inaccessible. Note that the current alternate map
register set cannot be deallocated. This makes all memory which was
currently mapped into conventional and expanded memory inaccessible.
CALLING PARAMETERS
AX = 5B04h
Contains the Deallocate Alternate Map Register Set
subfunction.
BL = alternate register set number
Contains the number of the alternate map register set to
deallocate. Map register set zero cannot be allocated or
deallocated. However, if alternate map register set zero
is specified and this subfunction is invoked, no error will
be returned. The function invocation is ignored in this
case.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the array size.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
124
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 9Ch NON-RECOVERABLE
Alternate map register sets are not supported and the
alternate map register set specified is not zero.
AH = 9Dh NON-RECOVERABLE
Alternate map register sets are supported, but the
alternate map register set specified is either not defined
or not allocated.
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time.
EXAMPLE
alternate_map_reg_set DB ?
MOV AL, alternate_map_reg_set ; specify alternate map reg set
MOV AX, 5B04h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
The Allocate DMA Register Set subfunction gets the number of a DMA
register set for an OS/E, if a DMA register set is currently available
for use. If the hardware does not support DMA register sets, a DMA
register set number of zero will be returned.
In a multitasking operating system, when one task is waiting for DMA
to complete, it is useful to be able to switch to another task.
However, if the DMA is being mapped through the current register set,
the switching cannot occur. That is, all DMA action must be complete
before any remapping of pages can be done.
The operating system would initiate a DMA operation on a specific DMA
channel using a specific alternate map register set. This alternate
map register set would not be used again, by the operating system or
an application, until after the DMA operation is complete. The
operating system guarantees this by not changing the contents of the
alternate map register set, or allowing an application to change the
contents of the alternate map register set, for the duration of the
DMA operation.
CALLING PARAMETERS
AX = 5B05h
Contains the Allocate DMA Register Set subfunction.
RESULTS
These results are valid only if the status returned is zero.
BL = DMA register set number
Contains the number of a DMA register set. If there are no
DMA register sets supported by the hardware, a zero will be
returned.
REGISTERS MODIFIED
AX, BX
STATUS
AH = 0 SUCCESSFUL
The manager has allocated the DMA register set.
126
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 9Bh NON-RECOVERABLE
DMA register sets are supported. However, all DMA register
sets are currently allocated.
AH = A4h NON-RECOVERABLE
Access to this function has been denied by the operating
system. The function cannot be used at this time.
EXAMPLE
DMA_reg_set_number DB ?
MOV AX, 5B05h ; load function code
INT 67h ; call memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV DMA_reg_set_number, BL ; save number of DMA register
; set
127
FUNCTION 28 ALTERNATE MAP REGISTER SET
ENABLE DMA ON ALTERNATE MAP REGISTER SET SUBFUNCTION
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
This subfunction allows DMA accesses on a specific DMA channel to be
associated with a specific alternate map register set. In a
multitasking operating system, when a task is waiting for the
completion of DMA, it is useful to be able to switch to another task
until the DMA operation completes.
Any DMA on the specified channel will go through the specified DMA
register set regardless of the current register set. If a DMA channel
is not assigned to a DMA register set, DMA for that channel will be
mapped through the current register set.
CALLING PARAMETERS
AX = 5B06h
Contains the Enable DMA on Alternate Map Register Set
subfunction.
BL = DMA register set number
Contains the number of the alternate map register set to be
used for DMA operations on the DMA channel specified by DL.
If the alternate map register set specified is zero, no
special action will be taken on DMA accesses for the DMA
channel specified.
DL = DMA channel number
Contains the DMA channel which is to be associated with the
DMA map register set specified in BL.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has enabled DMA on the DMA register set and the
DMA channel specified.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
128
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 9Ah NON-RECOVERABLE
Alternate DMA register sets are supported, but the
alternate DMA register set specified is not supported.
AH = 9Ch NON-RECOVERABLE
Alternate DMA register sets are not supported, and the DMA
register set specified is not zero.
AH = 9Dh NON-RECOVERABLE
DMA register sets are supported, but the DMA register set
specified is either not defined or not allocated.
AH = 9Eh NON-RECOVERABLE
Dedicated DMA channels are not supported.
AH = 9Fh NON-RECOVERABLE
Dedicated DMA channels are supported. But the DMA channel
specified is not supported.
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time.
EXAMPLE
alt_map_reg_set DB ?
DMA_channel_num DB ?
MOV BL, alt_map_reg_set
MOV DL, DMA_channel_num
MOV AX, 5B06h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
129
FUNCTION 28 ALTERNATE MAP REGISTER SET
DISABLE DMA ON ALTERNATE MAP REGISTER SET SUBFUNCTION
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
This subfunction disables DMA accesses for all DMA channels which were
associated with a specific alternate map register set.
CALLING PARAMETERS
AX = 5B07h
Contains the Disable DMA on Alternate Map Register Set
subfunction.
BL = alternate register set number
Contains the number of the DMA register set for which all
operations are to be disabled. If the alternate map
register set specified is zero, no action will be taken.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has returned the array size.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 9Ah NON-RECOVERABLE
Alternate DMA register sets are supported, but the
alternate DMA register set specified is not supported.
130
AH = 9Ch NON-RECOVERABLE
Alternate DMA register sets are not supported, and the DMA
register set specified is not zero.
AH = 9Dh NON-RECOVERABLE
DMA register sets are supported, but the DMA register set
specified is either not defined or not allocated.
AH = 9Eh NON-RECOVERABLE
Dedicated DMA channels are not supported.
AH = 9Fh NON-RECOVERABLE
Dedicated DMA channels are supported, but the DMA channel
specified is not supported.
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time.
EXAMPLE
DMA_reg_set DB ?
MOV BL, DMA_reg_set
MOV AX, 5B07h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
This function is for use by operating systems only. The operating
system can disable this function at any time. Refer to Function 30
for a description of how an operating system can enable or disable
this function.
PURPOSE
The Deallocate DMA Register Set subfunction deallocates the specified
DMA register set.
CALLING PARAMETERS
AX = 5B08h
Contains the Deallocate DMA Register Set subfunction.
BL = DMA register set number
Contains the number of the DMA register set which should
not be used for DMA operations any longer. The DMA
register set would have been previously allocated and
enabled for DMA operations on a specific DMA channel. If
the DMA register set specified is zero, no action will be
taken.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has deallocated the DMA register set.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = 9Ch NON-RECOVERABLE
DMA register sets are not supported, and the DMA register
set specified is not zero.
132
AH = 9Dh NON-RECOVERABLE
DMA register sets are supported, but the DMA register set
specified is either not defined or not allocated.
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time.
EXAMPLE
DMA_reg_set_num DB ?
MOV DMA_reg_set_num, BL
MOV AX, 5B08h ; load function code
INT 67h ; call memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
133
FUNCTION 29 PREPARE EXPANDED MEMORY HARDWARE FOR WARM BOOT
PURPOSE
This function prepares the expanded memory hardware for an impending
warm boot. This function assumes that the next operation that the
operating system performs is a warm boot of the system. In general,
this function will effect the current mapping context, the alternate
register set in use, and any other expanded memory hardware
dependencies which need to be initialized at boot time. If an
application decides to map memory below 640K, the application must
trap all possible conditions leading to a warm boot and invoke this
function before performing the warm boot itself.
CALLING PARAMETERS
AH = 5Ch
Contains the Prepare for Warmboot function.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The manager has prepared the expanded memory hardware for a
warm boot.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
EXAMPLE
MOV AH, 5Ch ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
134
FUNCTION 30 ENABLE/DISABLE OS/E FUNCTION SET FUNCTIONS
This function is for use by operating systems only. The operating
system can disable this function at any time.
PURPOSE
This subfunction provides an OS/E with the ability to enable all
programs or device drivers to use the OS/E specific functions. The
capability is provided only for an OS/E which manages regions of
mappable conventional memory and cannot permit programs to use any of
the functions which affect mappable conventional memory regions, but
must be able to use these functions itself. When an OS/E disables
these functions and a program attempts to use them, the memory manager
returns a status to the program indicating that the OS/E has denied
the program access to the function. In other words, the functions
will not work when disabled. However, all programs may use them when
enabled. The OS/E (Operating System/Environment) functions this
subfunction enables are:
Function 26. Get Expanded Memory Hardware Information.
Function 28. Alternate Map Register Sets.
Function 30. Enable/Disable Operating System Functions.
It appears contradictory that the OS/E can re-enable these functions
when the function which re-enables them is itself disabled. An
overview of the process follows.
The memory manager enables all the OS/E specific functions, including
this one, when it is loaded. The OS/E gets exclusive access to these
functions by invoking either of the Enable/Disable OS/E Function Set
subfunctions before any other software does.
On the first invocation of either of these subfunctions, the memory
manager returns an access_key which the OS/E must use in all future
invocations of either of these subfunctions. The memory manager does
not require the access_key on the first invocation of the
Enable/Disable OS/E Function Set subfunctions.
ENABLE OS/E FUNCTION SET SUBFUNCTION
On all subsequent invocations, the access_key is required for either
the Enable or Disable OS/E Function Set subfunctions. Since the
access_key is returned only on the first invocation of the
Enable/Disable OS/E Function Set subfunctions, and presumably the OS/E
is the first software to invoke this function, only the OS/E obtains a
copy of this key. The memory manager must return an access key with a
random value, a fixed value key defeats the purpose of providing this
level of security for an OS/E.
CALLING PARAMETERS
135
AX = 5D00h
Contains the Enable OS/E Function Set subfunction.
BX,CX = access_key
Required on all function invocations after the first. The
access_key value returned by the first function invocation
is required.
RESULTS
These results are valid only if the status returned is zero.
BX,CX = access_key
Returned only on the first function invocation, the memory
manager returns a random valued key which will be required
thereafter for the execution of this function. On all
invocations after the first, this key is not returned.
Neither BX or CX is affected after the first time this
function is invoked.
REGISTERS MODIFIED
AX, BX, CX
STATUS
AH = 0 SUCCESSFUL
The operating system function set has been enabled.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time. The value of the
key which was passed to this function does not entitle the
program to execute this function.
EXAMPLE
First invocation
access_key DW 2 DUP (?)
MOV AX, 5D00h ; load function code
136
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV access_key[0], BX
MOV access_key[2], CX
All invocations after the first
access_key DW 2 DUP (?)
MOV BX, access_key[0]
MOV CX, access_key[2]
MOV AX, 5D00h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to test handler on error
137
FUNCTION 30 ENABLE/DISABLE OS/E FUNCTION SET FUNCTIONS
This function is for use by operating systems only. The operating
system can disable this function at any time.
PURPOSE
This subfunction provides an OS/E with the ability to disable all
programs or device drivers from using the OS/E specific functions.
The capability is provided only for an OS/E which manages regions of
mappable conventional memory and cannot permit programs to use any of
the functions which would affect mappable conventional memory regions.
When an OS/E disables these functions and a program attempts to use
them, the memory manager returns a status to the program indicating
that the OS/E has denied the program access to the function. In other
words, the functions will not work when disabled.
The OS/E (Operating System) functions which are disabled by this
subfunction are:
Function 26. Get Expanded Memory Hardware Information.
Function 28. Alternate Map Register Sets.
Function 30. Enable/Disable Operating System Functions.
CALLING PARAMETERS
AX = 5D01h
Contains the Disable OS/E Function Set subfunction.
BX,CX = access_key
Required on all function invocations after the first. The
access_key value returned by the first function invocation
is required.
RESULTS
These results are valid only if the status returned is zero.
BX,CX = access_key
Returned only on the first function invocation, the memory
manager returns a random valued key which will be required
thereafter for the execution of this function. On all
invocations after the first, this key is not returned.
Neither BX nor CX is affected after the first time this
function is invoked.
REGISTERS MODIFIED
AX, BX, CX
STATUS
138
AH = 0 SUCCESSFUL
The operating system function set has been disabled.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A4h NON-RECOVERABLE
The operating system has denied access to this function.
The function cannot be used at this time. The value of the
key which was passed to this function does not entitle the
program to execute this function.
EXAMPLE
First Function invocation:
access_key DW 2 DUP (?)
MOV AX, 5D01h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
MOV access_key[0], BX
MOV access_key[2], CX
All invocations after the first:
access_key DW 2 DUP (?)
MOV BX, access_key[0]
MOV CX, access_key[2]
MOV AX, 5D01h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
139
FUNCTION 30 ENABLE/DISABLE OS/E FUNCTION SET FUNCTIONS
This function is for use by operating systems only. The operating
system can disable this function at any time.
PURPOSE
This subfunction provides an OS/E with the ability to return the
access key to the memory manager. Returning the access key to the
memory manager places the memory manager in the state it is in at
installation time (regarding the use of the OS/E function set and the
access key). That is, access to the OS/E function set is enabled.
Upon execution of the next enable/disable OS/E function set
subfunction, the access key will once again be returned.
CALLING PARAMETERS
AX = 5D02h
Contains the Return Access Key subfunction.
BX,CX = access_key
Required on all function invocations. The access_key value
returned by the first function invocation of the enable or
disable subfunctions is required.
REGISTERS MODIFIED
AX
STATUS
AH = 0 SUCCESSFUL
The access key has been returned to the memory manager.
AH = 80h NON-RECOVERABLE
The manager detected a malfunction in the memory manager
software.
AH = 81h NON-RECOVERABLE
The manager detected a malfunction in the expanded memory
hardware.
AH = 84h NON-RECOVERABLE
The function code passed to the memory manager is not
defined.
AH = 8Fh NON-RECOVERABLE
The subfunction parameter is invalid.
AH = A4h NON-RECOVERABLE
Access to this function has been denied by the operating
system. The function cannot be used at this time. The
140
value of the key which was passed to this function does not
entitle the program to execute this function.
EXAMPLE
access_key DW 2 DUP (?)
MOV BX, access_key[0]
MOV CX, access_key[2]
MOV AX, 5D02h ; load function code
INT 67h ; call the memory manager
OR AH, AH ; check EMM status
JNZ emm_err_handler ; jump to error handler on error
141
APPENDIX A FUNCTION AND STATUS CODE CROSS REFERENCE TABLES
This appendix contains two cross reference tables: one lists this
function codes and the status codes they return; the other lists the
status codes and the functions that return them.
TABLE A-1. FUNCTION AND STATUS CODE CROSS REFERENCE
----------------------------------------------------------------------
Function Status Description
----------------------------------------------------------------------
40h 00h 80h 81h 84h Get memory manager status
41h 00h 80h 81h 84h Get Page Frame Segment Address
TABLE A-2. STATUS AND FUNCTION CODE CROSS REFERENCE
----------------------------------------------------------------------
Status Functions Description
----------------------------------------------------------------------
00h All The function completed normally.
80h All The memory manager has detected a
malfunction in the expanded memory
software.
81h All The memory manager has detected a
malfunction in the expanded memory
hardware.
82h None This error code is not returned in
version 3.2 of the memory manager
or above. In earlier versions of
the memory manager this code meant
a "busy" status. This status
indicated that the memory manager
was already processing an expanded
memory request when the current
request was made and is unable to
process another request. In
versions 3.2 of the memory manager
and above, the memory manager is
never "busy" and can always honor
requests.
83h 44h 45h 47h 48h The memory manager can not find
4Ch 5000h 5001h 51h the handle specified.
5200h 5201h 5300h 5301h
5500h 5501h 5600h 5601h
5700h 5701h
84h All The function code passed to the
manager is not currently defined.
85h 43h 5A00h 5A01h No handles are currently available.
All assignable handles are
currently in use.
86h 45h A mapping context restoration error
has been detected. This error
occurs when a program attempts to
return a handle and there is still
a "mapping context" on the context
stack for the indicated handle.
87h 43h 51h 5A00h 5A01h The number of total pages that are
available in the system is
insufficient to honor the request.
146
88h 43h 51h 5A00h 5A01h The number of unallocated pages
currently available is insufficient
to honor the allocation request.
89h 43h Zero pages could not be assigned to
a handle.
8Ah 44h 5000h 5001h 5500h The logical page to map into memory
5501h 5600h 5601h 5700h is out of the range of logical
5701h pages which are allocated to the
handle.
8Bh 44h 4F00h 4F02h 5000h One or more of the physical pages
5001h 5600h 5601h 5500h is out of the range of allowable
5501h physical pages.
8Ch 47h The mapping register context save
area is full.
8Dh 47h The mapping register context stack
already has a context associated
with the handle. The program has
attempted to save the mapping
register context when there was
already a context for the handle on
the stack.
8Eh 48h The mapping register context stack
does not have a context associated
with the handle. The program has
attempted to restore the mapping
register context when there was no
context for the handle on the
stack.
8Fh All The subfunction parameter passed to
the function requiring a
subfunction code is not defined.
90h 5201h The attribute type is undefined.
91h 5200h 5201h The system configuration does not
support non-volatility.
92h 5700h The source and destination expanded
memory regions have the same handle
and overlap. This is valid for a
move. The move has been completed
and the destination region has a
full copy of the source region.
However, at least a portion of the
source region has been overwritten
by the move.
93h 5700h 5701h The length of the specified source
or destination expanded memory
region exceeds the length of the
147
expanded memory region allocated to
the specified source or destination
handle. There are insufficient
pages allocated to this handle to
move/exchange a region of the size
specified.
94h 5700h 5701h The conventional memory region and
expanded memory region overlap.
This is invalid, the conventional
memory region cannot overlap the
expanded memory region.
95h 5700h 5701h The offset within the logical page
exceeds the length of the logical
page. The initial source or
destination offsets within an
expanded memory region must be
between 0 and the (length of a
logical page - 1) or 16383 (3FFFh).
96h 5700h 5701h Region length exceeds 1M-byte
limit.
97h 5701h The source and destination expanded
memory regions have the SAME handle
AND overlap. This is invalid; the
source and destination expanded
memory regions cannot have the same
handle and overlap when they are
being exchanged.
98h 5700h 5701h The memory source and destination
types are undefined/not supported.
9Ah 5B01h 5B06h 5B07h Alternate map register sets are
supported, but the alternate map
register set specified is not
supported.
9Bh 5B03h 5B05h Alternate map/DMA register sets are
supported. However, all alternate
map/DMA register sets are currently
allocated.
9Ch 5B01h 5B04h 5B06h 5B07h Alternate map/DMA register sets are
5B08h not supported, and the alternate
map/DMA register set specified is
not zero.
9Dh 5B01h 5B04h 5B06h 5B07h Alternate map/DMA register sets are
5B08h supported, but the alternate map
register set specified is not
defined, not allocated, or is the
currently allocated map register
set.
148
9Eh 5B06h 5B07h Dedicated DMA channels are not
supported.
9Fh 5B06h 5B07h Dedicated DMA channels are
supported. But the DMA channel
specified is not supported.
A0h 5401h No corresponding handle value could
be found for the handle name
specified.
A1h 5301h 5401h A handle with this name already
exists. The specified handle was
not assigned a name.
A2h 5700h 5701h An attempt was made to "wrap
around" the 1M-byte address space
during the move/exchange. The
source starting address together
with the length of the region to be
moved/exchanged exceeds 1M-byte. No
data was moved/exchanged.
A3h 4E01h 4E02h 4F00h 4F01h The contents of the data structure
5B01h passed to the function have either
been corrupted or are meaningless.
A4h 5900h 5B00h 5B01h 5B02h The operating system has denied
5B03h 5B04h 5B05h 5B06h access to this function. The
5B07h 5B08h 5D00h 5D01h function cannot be used at this
5D02h time.
149
APPENDIX B
TESTING FOR THE PRESENCE OF THE EXPANDED MEMORY MANAGER
Before an application program can use the Expanded Memory Manager, it
must determine whether DOS has loaded the manager. This appendix
describes two methods your program can use to test for the presence of
the memory manager and how to choose the correct one for your
situation.
The first method uses the DOS "open handle" technique; the second
method uses the DOS "get interrupt vector" technique.
WHICH METHOD SHOULD YOUR PROGRAM USE?
The majority of application programs can use either the "open handle"
or the "get interrupt vector" method. However, if your program is a
device driver or if it interrupts DOS during file system operations,
you must use only the "get interrupt vector" method.
Device drivers execute from within DOS and can't access the DOS file
system; programs that interrupt DOS during file system operations have
a similar restriction. During their interrupt processing procedures,
they can't access the DOS file system because another program may be
using the system.
Since the "get interrupt vector" method doesn't require the DOS file
system, you must use it for these types of programs.
THE "OPEN HANDLE" TECHNIQUE
Most application programs can use the DOS "open handle" technique to
test for the presence of the memory manager. This section describes
how to use the technique and gives an example.
Don't use this technique if your program is a device driver or if it
interrupts DOS during file system operations. Use the "get interrupt
vector" technique described later in this chapter.
USING THE "OPEN HANDLE" TECHNIQUE
This section describes how to use the DOS "open handle" technique to
test for the presence of the memory manager. Follow these steps in
order:
1. Issue an "open handle" command (DOS function 3Dh) in "read only"
access mode (register AL = 0). This function requires your
program to point to an ASCII string which contains the path name
of the file or device in which you're interested (register set
DS:DX contains the pointer). In this case the file is actually
the name of the memory manager.
You should format the ASCII string as follows:
ASCII_device_name DB "EMMXXXX0", 0
150
The ASCII codes for the capital letters EMMXXXX0 are terminated by
a byte containing a value of zero.
2. If DOS returns no error status code, skip Steps 3 and 4 and go to
Step 5. If DOS returns a "Too many open files" error status code,
go to Step 3. If DOS returns a "File/Path not found" error status
code, skip Step 3 and go to Step 4.
3. If DOS returns a "Too many open files" (not enough handles),
status code, your program should invoke the "open file" command
before it opens any other files. This will guarantee that at
least one file handle will be available to perform the function
without causing this error.
After the program performs the "open file" command, it should
perform the test described in Step 6 and close the "file handle"
(DOS function 3Eh). Don't keep the manager "open" after this
status test is performed since "manager" functions are not
available thru DOS. Go to Step 6.
4. If DOS returns a "File/Path not found", the memory manager is not
installed. If your application requires the memory manager, the
user will have to reboot the system with a disk containing the
memory manager and the appropriate CONFIG.SYS file before
proceeding.
5. If DOS doesn't return an error status code you can assume that
either a device with the name EMMXXXX0 is resident in the system,
or a file with this name is on disk in the current disk drive. Go
to Step 6.
6. Issue an "I/O Control for Devices" command (DOS function 44h) with
a "get device information" command (register AL = 0h). DOS
function 44h determines whether EMMXXXX0 is a device or a file.
You must use the file handle (register BX) which you obtained in
Step 1 to access the "EMM" device. This function returns the
"device information" in a word (register DX). Go to step 7.
7. If DOS returns any error status code, you should assume that the
memory manager device driver is not installed. If your
application requires the memory manager, the user will have to
reboot the system with a disk containing the memory manager and
the appropriate CONFIG.SYS file before proceeding.
8. If DOS didn't return an error status, test the contents of bit 7
(counting from 0) of the "device information" word (register DX)
the function returned. Go to Step 9.
9. If bit 7 of the "device information" word contains a zero, then
EMMXXXX0 is a file, and the memory manager device driver is not
present. If your application requires its presence, the user will
have to reboot the system with a disk containing the memory
manager and the appropriate CONFIG.SYS file before proceeding. If
bit 7 contains a one, then EMMXXXX0 is a device. Go to Step 10.
151
10. Issue an "I/O Control for Devices" command (DOS function 44h) with
a "get output status" command (register AL = 7h).
You must use the file handle you obtained in Step 1 to access the
"EMM" device (register BX). Go to Step 11.
11. If the expanded memory device driver is "ready," the memory
manager passes a status value of "0FFh" in register AL. The
status value is "00h" if the device driver is "not ready."
If the memory manager device driver is "not ready" and your
application requires its presence, the user will have to reboot
the system with a disk containing the memory manager and the
appropriate CONFIG.SYS file before proceeding.
If the memory manager device driver is "ready", go to Step 12.
12. Issue a "Close File Handle" command (DOS function 3Eh) to close
the expanded memory device driver. You must use the file handle
you obtained in Step 1 to close the "EMM" device (register BX)
AN EXAMPLE OF THE "OPEN HANDLE" TECHNIQUE
The following procedure is an example of the "open handle" technique
outlined in the previous section.
;---------------------------------------------------------------;
; The following procedure tests for the presence of the EMM ;
; in the system. It returns the CARRY FLAG SET if the EMM is ;
; present. If the EMM is not present, this procedure returns ;
; the CARRY FLAG CLEAR. ;
;---------------------------------------------------------------;
first_test_for_EMM PROC NEAR
PUSH DS
PUSH CS
POP DS
MOV AX, 3D00h ; issue device open in
LEA DX, ASCII_device_name ; read only mode
INT 21h
JC first_test_for_EMM_error_exit ; test for error during open
MOV BX, AX ; get file handle returned by DOS
MOV AX, 4400h ; issue IOCTL get device info
INT 21h
JC first_test_for_EMM_err_exit ; test for get device info error
TEST DX, 0080h ; test to determine
JZ first_test_for_EMM_err_exit ; if ASCII_device_name
; is a device or a file
MOV AX, 4407h ; issue "IOCTL"
INT 21h
JC first_test_for_EMM_error_exit ; test for IOCTL error
PUSH AX ; save "IOCTL" status
MOV AH, 3Eh ; issue "close
INT 21h ; file handle"
152
POP AX ; restore "IOCTL" status
CMP AL, 0FFh ; test for "device ready" status
JNE first_test_for_EMM_error_exit ; returned by the driver
first_test_for_EMM_exit:
POP DS ; EMM is present in the system
STC
RET
first_test_for_EMM_error_exit:
POP DS ; EMM is NOT present in the system
CLC
RET
ASCII_device_name DB "EMMXXXX0", 0
first_test_for_EMM ENDP
153
THE "GET INTERRUPT VECTOR" TECHNIQUE
Any type of program can use the DOS "get interrupt vector" technique
to test for the presence of the memory manager. This section
describes how to use the technique and gives an example.
Be sure to use this technique (and not the "open handle technique) if
your program is a device driver or if it interrupts DOS during file
system operations.
USING THE "GET INTERRUPT VECTOR" TECHNIQUE
This section describes how to use the DOS "get interrupt vector"
technique to test for the presence of the memory manager. Follow
these steps in order:
1. Issue a "get vector" command (DOS function 35h) to obtain the
contents of interrupt vector array entry number 67h (addresses
0000:019C thru 0000:019F).
The memory manager uses this interrupt vector to perform all
manager functions. The Offset portion of this interrupt service
routine address is stored in the word located at address
0000:019Ch; the Segment portion is stored in the word located at
address 0000:019Eh.
2. Compare the "device name field" with the contents of the ASCII
string which starts at the address specified by the segment
portion of the contents of interrupt vector address 67h and a
fixed offset of 000Ah. If DOS loaded the memory manager at boot
time this name field will have the name of the device in it.
Since the memory manager is implemented as a character device
driver, its program origin is 0000h. Device drivers are required
to have a "device header" located at the program origin. Within
the "device header" is an 8 byte "device name field." For a
character mode device driver this name field is always located at
offset 000Ah within the device header. The device name field
contains the name of the device which DOS uses when it references
the device.
If the result of the "string compare" in this technique is
positive, the memory manager driver is present.
AN EXAMPLE OF THE "GET INTERRUPT VECTOR" TECHNIQUE
The following procedure is an example of the "get interrupt vector"
technique outlined in the previous section.
;---------------------------------------------------------------;
; The following procedure tests for the presence of the EMM ;
; in the system. It returns the CARRY FLAG SET if the EMM is ;
; present. If the EMM is not present, this procedure returns ;
; the CARRY FLAG CLEAR. ;
;---------------------------------------------------------------;
154
second_test_for_EMM PROC NEAR
PUSH DS
PUSH CS
POP DS
MOV AX, 3567h ; issue "get interrupt vector"
INT 21h
MOV DI, 000Ah ; use the SEGMENT in ES returned by
; DOS, place the "device name
; field" OFFSET in DI
LEA SI, ASCII_device_name ; place the OFFSET of the device
; name string in SI, the SEGMENT
; is already in DS
MOV CX, 8 ; compare the name strings
CLD
REPE CMPSB
JNE second_test_for_EMM_error_exit
second_test_for_EMM_exit:
POP DS ; EMM is present in the system
STC
RET
second_test_for_EMM_error_exit:
POP DS ; EMM is NOT present in the system
CLC
RET
ASCII_device_name DB "EMMXXXX0"
second_test_for_EMM ENDP
155
APPENDIX C
EXPANDED MEMORY MANAGER IMPLEMENTATION GUIDELINES
In addition to the functional specification, the expanded memory
manager should provide certain resources. The following guidelines
are provided so required resources are present in expanded memory
managers which comply with this version of the LIM specification.
o The amount of expanded memory supported:
Up to a maximum of 32M bytes of expanded memory should be
supported.
o The number of handles supported:
The maximum number expanded memory handles provided should be 255,
the minimum should be 64.
o Handle Numbering:
Although a handle is a word quantity, there is a maximum of 255
handles, including the operating system handle. This
specification defines the handle word as follows: the low byte of
the word is the actual handle value, the high byte of the handle
is set to 00 by the memory manager. Previous versions of this
specification did not specify the value of handles.
o New handle type: Handles versus Raw Handles:
The difference between a raw handle and a regular handle is
slight. If you use Function 27 to "Allocate raw pages to a
handle", what is returned in DX is termed a raw handle. The raw
handle does not necessarily refer to 16 Kbyte pages. Instead it
refers to the "raw" page size, which depends on the expanded
memory hardware.
An application program can use Function 26 to find the raw page
size, and by using the raw handle Function 27 returns, it can
access them with the finer resolution that a particular expanded
memory board may allow.
On the other hand, applications which use Function 4 to "allocate
pages to handle" receive a handle which always refers to 16K-byte
pages. On expanded memory boards with smaller raw pages, the EMM
driver will allocate and maintain the number of raw pages it takes
to create a single composite 16K-byte page. The difference
between the expanded memory boards raw page size and the 16K-byte
LIM page size is transparent to the application when it is using a
handle obtained with Function 4.
The memory manager must differentiate between pages allocated to
handles and pages allocated to raw handles. The meaning of a call
to the driver changes depending on whether a handle or a raw
handle is passed to the memory manager. If, for example, a handle
is passed to Function 18 (Reallocate), the memory manager will
156
increase or decrease the number of 16K-byte pages allocated to the
handle. If Function 18 is passed a raw handle, the memory manager
will increase or decrease the number of raw (non-16K-byte) pages
allocated to the raw handle. For LIM standard boards, there is no
difference between pages and raw pages.
o The system Raw Handle (Raw Handle = 0000):
For expanded memory boards that can remap the memory in the lower
640K-byte address space, managing the pages of memory which are
used to fill in the lower 640K can be a problem. To solve this
problem, the memory manager will create a raw handle with a value
of 0000 when DOS loads the manager. This raw handle is called the
system handle.
At power up, the memory manager will allocate all of the pages
that are mapped into the lower 640K bytes to the system handle.
These pages should be mapped in their logical order. For example,
if the system board supplies 256K bytes of RAM, and the 384K bytes
above it is mappable, the system handle should have its logical
page zero mapped into the first physical page at 256K, its logical
page one mapped into the next physical page, and so on.
The system handle should deal with raw pages. To release some of
these pages so application programs can use them, an operating
system could decrease the number of pages allocated to the system
handle with the "Reallocate" function. Invoking the "Deallocate"
function would decrease the system handle to zero size, but it
must not deallocate the raw handle itself. The "Deallocate"
function treats the system handle differently than it treats other
raw handles. If the operating system can ever be "exited" (for
example, the way Windows can be exited), it must increase the size
of the system handle back to what is needed to fill 640K and map
these logical pages back into physical memory before returning to
DOS.
157
There are two functional special cases for this handle:
- The first special case deals with Function 4 (Allocate
Pages). This function must never return zero as a handle
value. Applications must always invoke Function 4 to
allocate pages and obtain a handle which identifies its
pages. Since Function 4 will never return a handle value
of zero, an application will never gain access to this
special handle.
- The second special case deals with Function 6 (Deallocate
Pages). If the operating system uses Function 6 to
deallocate the pages which are allocated to the system
handle, the pages will be returned to the manager for use,
but the handle will not be available for reassignment.
The manager should treat a "deallocate pages" function
request for this handle the same as a "reallocate pages"
function request, where the number of pages to reallocate
to this handle is zero.
o Terminate and Stay Resident (TSR) Program Cooperation In order for
TSR's to cooperate with each other and with other applications,
TSR's must follow this rule: a program may only remap the DOS
partition it lives in.
This rule applies at all times, even when no expanded memory is
present.
o Accelerator Cards: To support generic accelerator cards, the
support of Function 34, as defined by AST, is encouraged.
158
APPENDIX D
OPERATING SYSTEM/ENVIRONMENT USE OF FUNCTION 28
All expanded memory boards have a set of registers that "remember" the
logical to physical page mappings. Some boards have extra (or
alternate) sets of these mapping registers. Because no expanded
memory board can supply an infinite number of alternate map register
sets, this specification provides a way to simulate them using
Function 28 (Alternate Map Register Set).
EXAMPLES
For the examples in this section, assume the hardware supports
alternate map register sets. First Windows is brought up, then
"Reversi" is started. Then control is switched back to the MS-DOS
Executive. For this procedure, here are the calls to the expanded
memory manager:
EXAMPLE 1
Allocate alt reg set ; Start up the MS-DOS
(for the MS-DOS executive) ; Executive
Set alt reg set
(for MS-DOS Executive)
Allocate alt reg set ; Start up Reversi
(for Reversi)
Set alt reg set
(for Reversi)
Map pages
(for Reversi)
Set alt reg set ; Switch back to MS-DOS
(for MS-DOS Executive) ; Executive
Notice this procedure needed no "get" calls because the register set
contained all the information needed to save a context. However,
using "Get" calls would have no ill effects.
159
EXAMPLE 2
Allocate alt reg set ; Start up MS-DOS
(for MS-DOS Executive) ; Executive
Set alt reg set
(for MS-DOS Executive)
Get alt reg set
(for MS-DOS Executive)
Allocate alt reg set ; Start up Reversi
(for Reversi)
Set alt reg set
(for Reversi)
Map pages
(for Reversi)
Get alt reg set
(for Reversi)
Set alt reg set ; Switch back to MS-DOS
(for MS-DOS Executive) ; Executive
The important point to follow is that a Set must always precede a Get.
The model of Set then Get is the inverse of what interrupt handlers
use, which is Get then Set (Get the old map context and Set the new
one). Another crucial point is that an alternate map register set
must have the current mapping when allocated; otherwise, the Set will
create chaos.
What happens if this is simulated in software? The same Set and Get
model applies. The main difference is where the context is saved.
Since the allocate call is dynamic and there is no limit on the number
of sets allocated, the OS/E must supply the space required. Device
drivers cannot allocate space dynamically, since the request would
fail. If the Allocate register set call returns a status indicating
the alternate map register sets aren't supported, the OS/E must
allocate space for the context. It must also initialize the context
using Function 15. At that point it can do the Set, passing a pointer
to the map context space. On the Get call, the EMM driver is to
return a pointer to the same context space.
EXAMPLE 3
Allocate alt reg set ; Start up MS-DOS
(for the MS-DOS executive) ;Executive
Get Page Map
(for the MS-DOS executive)
Set alt reg set
(for MS-DOS Executive)
160
Allocate alt reg set ; Start up Reversi
(for Reversi)
Set alt reg set
(for Reversi)
Map pages
(for Reversi)
Get Page Map
(for Reversi)
Set alt reg set ; Switch back to MS-DOS
(for MS-DOS Executive) ; Executive
161
GLOSSARY
The following terms are used frequently in this specification:
Allocate
To reserve a specified amount of expanded memory pages.
Application Program
An application program is the program you write and your customer
uses. Some categories of application software are word
processors, database managers, spreadsheet managers, and project
managers.
Conventional Memory
The memory between 0 and 640K bytes, address range 00000h thru
9FFFFh.
Deallocate
To return previously allocated expanded memory to the memory
manager.
EMM
See Expanded Memory Manager.
Expanded Memory
Expanded memory is memory outside DOS's 640K-byte limit (usually
in the range of C0000h through EFFFFH).
Expanded Memory Manager (EMM)
A device driver that controls the interface between DOS
application programs and expanded memory.
Extended Memory
The 15M-byte address range between 100000h thru FFFFFFh available
on an 80286 processor when it is operating in protected virtual
address mode.
Handle
A value that the EMM assigns and uses to identify a block of
memory requested by an application program. All allocated
logical pages are associated with a particular handle.
Logical Page
The EMM allocates expanded memory in units (typically 16K-bytes)
called logical pages.
Mappable Segment
A 16K-byte region of memory which can have a logical page mapped
at it.
Map Registers
The set of registers containing the current mapping context of
the EMM hardware.
Mapping
The process of making a logical page of memory appear at a
physical page.
162
Mapping Context
The contents of the mapping registers at a specific instant.
This context represents a map state.
Page Frame
A collection of 16K-byte contiguous physical pages from which an
application program accesses expanded memory.
Page Frame Base Address
A page frame base address is the location (in segment format) of
the first byte of the page frame.
Physical Page
A physical page is the range of memory addresses occupied by a
single 16K-byte page.
Raw Page
The smallest unit of mappable memory that an expanded memory
board can supply.
Resident Application Program
A resident application program is loaded by DOS, executes, and
remains resident in the system after it returns control to DOS.
This type of program occupies memory and is usually invoked by
the operating system, an application program, or the hardware.
Some examples of resident application programs are RAM disks,
print spoolers, and "pop-up" desktop programs.
Status Code
A code that an EMM function returns which indicates something
about the result of running the function. Some status codes
indicate whether the function worked correctly and others may
tell you something about he expanded memory hardware or software.
Transient Application
A transient application program is loaded Program by DOS,
executes, and doesn't remain in the system after it returns
control to DOS. After a transient application program returns
control to DOS, the memory it used is available for other
programs.
Unmap
To make a logical page inaccessible for reading or writing.
