EMS 4.0 Driver Test Program
Preliminary release Version 1.02


Written by Douglas Boling
Copyright (c)1988 - Ziff Davis Publishing Co.




Description

The LIM EMS 4.0 Driver test program is designed to test the correct
implimentation of the EMS 4.0 spec from the aspect of the documented
software interface. Each of the functions of the EMS driver is called
and the results of the function are verified with the expected result.
When the test program detects an error, the tests for the function
function currently being tested is stopped, and an error message is
printed. Codes are printed with the error message to assist in the
localization of the error.

The tests in this program are based on information in the 'Lotus/
Intel/Microsoft Expanded memory Specification version 4.0' dated
October 1987.

The error code is a 4 digit code that indicates the reason for
the error message. The first two digits indicate the test routine
currently being executed. The number matches the function being
tested. For example, error code 1704 is an error in testing
function 17. Some error codes do not coorspond to a specific
functional test. Codes can also be the result of errors in the
setup and initialization routines.

When an error is detected in routines vitial to the continued
testing of the driver, the test program prints the error message
and program itself terminates without testing any other part of
the driver.

Two types of error messages are printed. The first type is printed
when the EMS driver returns an error though its return code. The
test program prints a message indicating that an EMS function
has failed to execute. The return code from the EMS driver is
included in the error message. It is important to note that
testing of one function involves the use of other EMS functions.
It is quite possible that an error will be returned on a function
not being tested, but rather, a function being used to test some
other part of the driver.

The second type of error message is printed when the test program
detects an error due to an unexpected result of a function. For
example, if the test program mapped an EMS page to the page frame
but the driver did not map the correct page. In this case an
error code is printed indicating the reason for the failure.

An index to the error codes is in this document. The codes are
listed by functional tests. All error codes the test program
prints should be in this index. Errors that cause the test
program to terminate completely are indicated be the note
'Terminal error.' For all other errors the test program will
stop testing the function that failed. The other functions
will be tested.


Limitations and Exclusions

The EMS 4.0 test program does not test parts of the LIM 4.0
specification. A list of the untested functions is given
below.
Non volatile handles - Testing for this function
requires the rebooting of the computer.

Function 25 - Get mappable page array - Since
the page array varies from machine to
machine there is no way to verify the
correctness of the information. The
function is called, but the data is
not interpeted.

Function 26 - Get hardware information - Since
this information varies from driver to
driver, there is no way to verify the
correctness of the information. The
function is called, but the data is
not interpeted. Another progarm,
EMSINFO.COM is included with this
test program. The EMSINFO program
prints various information available
to software to the screen in an
organized manner.

DMA alternate register sets. - The program does
not test this aspect of the LIM 4.0 spec.



Error Code Reference for EMS 4.0 driver test.

This refrence is composed of a section for each aspect of
the test program. Each section contains a paragraph describing
how the function is tested, along with a list of the possible
error codes. Errors marked 'Termination error' cause the program
to abort all testing and terminate.


Search for EMS driver
Driver is detected by the two recommended methods of detection,
the 'Get interrupt technique' and the 'Open handle technique.'
If the driver is not found by both methods, the test is terminated.
Possible error codes:
9900 : Driver could not be found by Get interrupt technique.
(Termination error)
9901 : Driver could not be found by Open handle technique.
(Termination error)


Function 01 ;Get status
Function 1 is tested to assure a returned status of 0.
Possible error codes:
0000 : Return code not zero. (Termination error)


Function 02 ;Get page frame segment address
Function 2 is called to get the page frame address. The validity
of the page frame is not tested, however, the remainder
of the EMS tests depend on this address and will fail
if the page frame returned is not accurate.
Possible error codes:
0003 : Return code not zero. (Termination error)


Function 03 ;Get unallocated page count
Function 3 is called to get determine the number of unallocated
pages in the system. The number of pages are checked
to assure that there are enough free pages to complete
the tests.
Possible error codes:
0004 : Return code not zero. (Termination error)
0005 : Not enough free pages to complete test (Termination
error.)


Function 04 ;Allocate pages
Function 4 is called to allocate handles and pages for the test.
Any error detected during the allocation of pages
terminates the test.
Possible error codes:
0010 : Return code not zero during first handle allocation.
(Termination error)
0013 : Return code not zero during handle 2 - 9 allocation.
(Termination error)


Function 05 ;Map/unmap handle pages
Function 5 is called to initially map the pages so they can be
initialized. If an error occurs during this part of the
test the test terminates.
The function is tested for by mapping pages to physical
pages in the page frame and comparing the data to the
initialized data for the specific handle and logical
page.
Possible error codes:
0011 : Return code not zero during map of first handle
pages. (Termination error)
0013 : Return code not zero during map of handles 2 - 9
pages. (Termination error)
0500 : Data in physical page 0 does not match expected data
0501 : Data in physical page 1 does not match expected data
0502 : Data in physical page 2 does not match expected data
0503 : Data in physical page 3 does not match expected data


Function 06 ;Deallocate pages



Function 07 ;Get version
Function 7 is tested to confirm version 4.0 or greater.
Possible error codes:
0001 : Return code not zero. (Termination error)
0002 : EMM version less than 4.0. (Termination error)


Function 08 ;Save page map
Function 8 and 9 are tested in the same routine. Refer to function
9 for error codes.


Function 09 ;Restore page map
Functions 8 and 9 are tested in the same routine. The page frame
is initialized. Function 8 is called to save the mapping context.
Different pages are mapped into the page frame. Function 9 is called
to restore the original context. The pages are read to confirm the
restoration.
Possible error codes:
0800 : Function 8 return code not zero.
0801 : Function 9 return code not zero.
0802 : Restored physical page 0 does not match expected data
0803 : Restored physical page 1 does not match expected data
0804 : Restored physical page 2 does not match expected data
0805 : Restored physical page 3 does not match expected data


Function 10 ;reserved
Function 10 is not tested.


Function 11 ;reserved
Function 11 is not tested.


Function 12 ;Get handle count
Function 12 is called to get determine the number of unallocated
handles in the system. The number of handles are checked
to assure that there are enough free handles to complete
the tests.
The function is tested after the handles for the test
have been allocated. The returned value is compared to
the original value plus the number of handles requested
by the test program.
Possible error codes:
0005 : Return code not zero. (Termination error)
0006 : Not enough free handles to complete test (Termination
error.)
1200 : Return code not zero on test.
1201 : The handle count did not match expected number.


Function 13 ;Get handle pages
Function 13 is called to get the number of pages allocated to
handle index 1 and handle index 2. The number of pages is compared
to what is expected. (handle index 0 should have 8 pages allocated,
handle index 1 should have 1 page allocated.
Possible error codes:
1300 : Function 13 return code not zero on call for
handle index 0.
1301 : Number of pages returned does not match expected
number of pages for handle index 0.
1302 : Function 13 return code not zero on call for
handle index 1.
1303 : Number of pages returned does not match expected
number of pages for handle index 1.


Function 14 ;Get all handle pages
Function 14 is called the handle page array. The total number
of open handles is compared to a maximum of 64. The 64 handle
limit is due to the space allocated to the data area for the
function 14 test. The total handles returned is compared to
the expected number. The array is then searched for the handles
allocated by the test. Each handle is searched for in the array,
and the resulting page allocation is compared to what is expected.
Possible error codes:
1400 : Function 14 return code not zero.
1401 : Number of open handles does not match expected.
1402 : Handle index 0 page allocation does not match
expected value.
1403 : Handle index 1 - 8 page allocations do not match
expected values.


Function 15 ;Page map functions
Function 15.3 is called to get the size of the save area needed.
If the size is larger than 128 bytes the test is ended. The page
frame is initialized by mapping pages to physical pages 0 through
3. Function 15.0 Get page map is called. The page frame context
is changed by mapping different pages into the frame. The new

context is saved using a different save area. The page map is
restored using function 15.1. The page frame data is checked to
see if it matches the original context. Function 15.2, Get and
Set page map is called. The page frame context is then tested
for the restoration of the second mapping context. Function 15.1
Set page map is called again using the saved context from the
Get and Set function. The page map is checked to see if the
original context is restored.
Possible error codes:
1500 : Function 15.3 return code not zero.
1501 : Size of save array larger than 128 bytes.
1502 : Function 15.0 return code not zero on first call.
1503 : Function 15.0 return code not zero on second call.
1504 : Function 15.1 return code not zero on first call.
1505 : Set page 0 does not match expected data
1506 : Set page 1 does not match expected data
1507 : Set page 2 does not match expected data
1508 : Set page 3 does not match expected data
1509 : Function 15.2 return code not zero.
1510 : Get and Set page 0 does not match expected data
1511 : Get and Set page 1 does not match expected data
1512 : Get and Set page 2 does not match expected data
1513 : Get and Set page 3 does not match expected data
1514 : Function 15.1 return code not zero on second call.
1515 : Set page 0 does not match expected data
1516 : Set page 1 does not match expected data
1517 : Set page 2 does not match expected data
1518 : Set page 3 does not match expected data


Function 16 ;Partial page map functions
Function 16.2 is called to get the size of the save area needed.
If the size is larger than 128 bytes the test is ended. The page
frame is initialized by mapping pages to physical pages 0 through
3. The mapping structure is initialized using page frame segment.
Function 16.0 Get partial page map is called to save mapping of
physical pages 0 and 2. The page frame context is changed
by mapping different pages into the frame. The original context
is restored for pages 0 and 2 using function 16.1. The resulting
context is checked to see if the result is a combination of the
original context and of the modified context.
Possible error codes:
1600 : Function 16.2 return code not zero.
1601 : Size of save array larger than 128 bytes.
1602 : Function 16.0 return code not zero.
1603 : Function 16.1 return code not zero.
1604 : Restored page 0 does not match expected data
1605 : Unchanged page 1 does not match expected data
1606 : Restored page 2 does not match expected data
1607 : Unchanged page 3 does not match expected data


Function 17 ;Map/unmap multiple handle pages
Function 17.0 is called to map the full four pages of the page
frame. The mapping is checked to confirm it matches what is in
the mapping structure. Segment addresses for the page frame
physical pages are written into a second mapping structure.
Function 16.1 is called to map the new pages into the page frame.
The mapping is checked to see if it matches what is in the
second mapping structure.
Possible error codes:
1700 : Function 17.0 return code not zero.
1701 : Mapped page 0 does not match expected data
1702 : Mapped page 1 does not match expected data
1703 : Mapped page 2 does not match expected data
1704 : Mapped page 3 does not match expected data
1705 : Function 17.1 return code not zero.
1706 : Mapped page 0 does not match expected data
1707 : Mapped page 1 does not match expected data
1708 : Mapped page 2 does not match expected data
1709 : Mapped page 3 does not match expected data


Function 18 ;Reallocate pages
Function 18 is called to increase handle index 0 allocated
pages from 8 to 10. The pages are initialized, then mapped
to the page frame. The data for these new pages is checked.
Function 13 is called to confirm that handle index 0 has
10 pages allocated. Function 18 is called again to reduce
the allocated pages for handle index 0 back to 8. An attempt
to map pages 9 and 10 is made to confirm that the pages no
longer exist.
Possible error codes:
1800 : Function 18 return code not zero on first call.
1801 : New logical page 9 cannot be mapped and initialized.
1802 : New logical page 10 cannot be mapped and initialized.
1803 : New logical page 9 cannot be mapped to be read.
1804 : New logical page 10 cannot be mapped to be read.
1805 : Logical page 9 does not match expected data.
1806 : Logical page 10 does not match expected data.
1807 : Function 13 return code not zero.
1808 : Number of pages for handle index 0 not correct.
1809 : Function 18 return code not zero on second call.
1810 : Accessing illegal page 9 does not cause illegal
page error.


Function 19 ;Handle attribute
Function 19.2 is called to see if nonvolatile handles are
supported.
if nonvolatile handles are not supported, function 19.0 get
handle attribute is called to confirm that the function call
causes a nonsupported return code. Function 19.1 is called
to confirm that the function call returns a nonsupported
return code.
If nonvolatile handles are supported, function 19.0 get
handle attribute is called. The returned attribute is tested
to to see if valid type. Function 19.1 is called to set the
attribute to volatile. Function 19.0 is called to confirm that
the handle attribute is now volatile. Function 19.1 is called to
set the attribute to nonvolatile. Function 19.0 is called to
confirm that the attribute is now nonvolatile. Function 19.1
is called with the illegal attribute value of 2 to confirm
the return of an illegal attribute return code.
Regardless of if volatile handles are supported or not, a message
is printed to the screen indicating the driver support for this
function.
The test does not confirm that nonvolatile handles actually
are nonvolatile.
Possible error codes:
1900 : Function 19.2 return code not zero.
1901 : No unsupported return code for unsupported
function 19.0.
1902 : No unsupported return code for unsupported
function 19.1.
1903 : Function 19.0 return code not zero on first call.
1904 : Illegal value for attribute for supported function.
1905 : Function 19.1 return code not zero on first call.
1906 : Function 19.0 return code not zero on second call.
1907 : Supported attribute could not be set to 0.
1908 : Function 19.1 return code not zero on second call.
1909 : Function 19.0 return code not zero on third call.
1910 : Supported attribute could not be set to 1.
1911 : Illegal attribute return code not returned for
an attempted set to an illegal attribute.


Function 20 ;Handle name
Function 20.0 is called to see if a non-null handle name
is set for a handle that has not has a name assigned. Function
20.1 is called to assign a handle name. Function 20.0 is called
to confirm the handle name just set. Function 6 is called to
deallocate named handle. Function 4 is called to reallocate
a handle to replace the handle. The new handle page is reinitialized.
Function 20.0 is called to confirm that the new handle does not
have a name assigned.
Possible error codes:
2000 : Function 20.0 return code not zero for first call.
2001 : A non-null name is assigned to a new handle.
2002 : Function 20.1 return code not zero for first call.
2003 : Function 20.0 return code not zero for second call.
2004 : Retrieved handle name does not match set handle name.
2005 : Function 6 return code not zero.
2006 : Function 4 return code not zero.
2007 : Initialization of new handle page failed.
2008 : Function 20.0 return code not zero on third call.
2009 : Non_null name assigned to new handle.


Function 21 ;Handle directory
Function 21.2 is called to get the total number of handles
supported by the driver. This number is checked to see if
a minimum of 64 and a maximum of 255 handles are supported. Handle
names for 2 handles are set using function 20.1. Function 21.0
is called to get the handle directory. The returned directory is
scanned to check for the two handle names just assigned. Function
21.1 is called to search for the handle name of one of the handles
just assigned a name. Function 21.1 is called again to search for
a handle not in the directory. Function 21.1 is called for a third
time to search for a handle with a null name.
Possible error codes:
2100 : Function 21.2 return code not zero.
2101 : Less than 64 handles supported by driver
2102 : More than 255 handles supported by driver.
2103 : Number of open handles is not what is expected.
2104 : Function 20.1 return code not zero for first call.
2105 : Function 20.1 return code not zero for second call.
2106 : Function 21.0 return code not zero.
2107 : Active handle not found in handle directory.
2108 : Handle name not correct for handle in directory.
2109 : Function 21.1 return code not zero for first call.
2110 : Search for handle name function returned wrong handle.
2111 : Return code not 'not found' for search of a nonexistent
handle name.
2112 : Return code not 'Null handle name' for search of a
null handle name.


Function 22 ;Alter page map and jump
The page frame is initialized. The function 22 data structure
is initialized. The state of the stack pointer and the flags register
is saved. Function 22.0, Alter page map and jump is called.
The state of the stack pointer and the flags register is compared
to their states before the jump. The state of the page frame is
compared to the expected mapping configuration.
Possible error codes:
2200 : Function 22.0 jump not taken.
2201 : Function 22.0 return code not zero.
2202 : Stack pointer corrupted across jump
2203 : Flags register corrupted across jump
2304 : Mapped page 0 does not match expected data
2305 : Mapped page 1 does not match expected data
2306 : Mapped page 2 does not match expected data
2307 : Mapped page 3 does not match expected data


Function 23 ;Alter page map and call
The page frame is initialized. The function 23 data structure
is initialized. The state of the stack pointer and the flags register
is saved. Function 23.0, Alter page map and call is called.
In the called routine, a flag is set to indicate the routine
has been called. The state of the page frame is checked.
The state of the the flags register is saved. The called
routine calls the EMS driver for the version number and returns
using a far return. On return to the calling procedure,
the state of the stack pointer is compared to its state before
the call. The save states of the flags register are comared. The
state of the page frame is compared to the expected mapping
configuration.
Possible error codes:
2300 : Mapped page 0 does not match expected data for subroutine.
2301 : Mapped page 1 does not match expected data for subroutine.
2302 : Mapped page 2 does not match expected data for subroutine.
2303 : Mapped page 3 does not match expected data for subroutine.
2304 : Function 7 Get version failed when called from subroutine.
2305 : Function 23.0 return code not zero.
2306 : Subroutine not called by EMS driver.
2307 : Stack pointer corrupted across call
2308 : Flags register corrupted across call
2309 : Original page 0 not restored on return from subroutine.
2310 : Original page 1 not restored on return from subroutine.
2311 : Original page 2 not restored on return from subroutine.
2312 : Original page 3 not restored on return from subroutine.


Function 24 ;move/exchange memory region
The page frame is initialized. The function 24 data structure
is initialized. Function 24.0 Move memory is called. The move
is from expanded memory to conventional memory. The data
read from the expanded memory is compared to twhat is expected.
The page frame is checked to verify that the mapping context
did not change during the move.
Possible error codes:
2400 : Function 24.0 return code not zero.
2401 : First half of data moved from Expanded memory not accurate.
2402 : Second half of data moved from Expanded memory not accurate.
2403 : Original page 0 corrupted by move.
2404 : Original page 1 corrupted by move.
2405 : Original page 2 corrupted by move.
2406 : Original page 3 corrupted by move.


Function 25 ;Get mappable physical addr array
Function 25.1 is called to get the size of the physical address
page array. If the array is larger than 128 bytes the test is
terminated. Functoin 25.0 is called to copy the page array into
a data buffer. The number of entries retruned by functon 25.0
is compared to the number returned in 25.1.
Possible error codes:
2500 : Function 25.1 return code not zero.
2501 : Data from the physical page map will not fit in the
test program buffer.
2502 : Function 25.0 return code not zero.
2502 : The number of pages returned by 25.1 is different than
the number returned by 25.0.


Function 26 ;Hardware configuration
Function 26.0 is called to get the hardware configuration
information. Function 26.1 is called to get the raw page
count. The data is formatted so it can be printed, but the
test progam print statement is disabled.
Possible error codes:
2600 : Function 26.0 return code not zero.
2601 : Function 26.1 return code not zero.


Function 27 ;Allocate standard pages
Function 27.0 allocate standard pages with a requested
page count of zero. Function 13 is called to confirm that
no pages are allocated to the new handle. Function 6 is
called to deallocate the new handle. Function 27.1 is
called to allocate a handle with one raw page. Function 5
is called to map the page to the page frame. Function 6
is called to deallocate the page.
Possible error codes:
2700 : Function 27.0 return code not zero.
2701 : Function 13.0 return code not zero.
2702 : Handle count returned not equal to zero.
2703 : Function 6 return code not zero.
2704 : Function 27.1 return code not zero.
2705 : Map of raw page failed, Function 5 return code not zero.
2706 : Map of page to replace raw page failed, Function 5 return
code not zero.
2707 : Deallocate of raw page failed, Function 6 return code not zero.


Function 28 ;Alternate map register set
The page frame is initialized. Function 28.2 is called to
get the size of the save array. If the array is too large the
test is terminated. Function 28.3 is called to allocate an
alternate register set. If hardware register sets are not
supported, the software emulation functon is tested. The
page map is changed. Function 28.0 is called to get the
current register set. Function 28.1 is called to invoke the
alternate register set reserved earlier. The page map
is checked. Functoin 28.1 is called to restore th orginal
map register set. Function 28.4 is called to deallocate the
alternate register set. The page frame is checked.
For simulated register sets, Function 15.0 is called to
initialize the save area. The page map is changed. Function
28.1 is called to restore the page map. The page map is
checked. The page map is modified. Function 28.0 is called
to save the page map. The page map is modified. Function 28.1
is called to restore the page map. The page map is checked.
Possible error codes:
2800 : Function 28.2 return code not zero.
2801 : Save array size too large.
2802 : Function 28.3 return code not zero.
2803 : Function 28.0 return code not zero.
2804 : Function 28.1 return code not zero.
2805 : Original page 0 not restored by alt register map.
2806 : Original page 1 not restored by alt register map.
2807 : Original page 2 not restored by alt register map.
2808 : Original page 3 not restored by alt register map.
2809 : Restore of original reg set fail, Function 28.1
return code not zero.
2810 : Function 28.4 return code not zero.
2811 : Page 0 not restored by orginal register map.
2812 : Page 1 not restored by orginal register map.
2813 : Page 2 not restored by orginal register map.
2814 : Page 3 not restored by orginal register map.
2819 : Function 15.0 return code not zero.
2820 : Function 28.1 return code not zero.
2821 : Original page 0 not restored by alt register map.
2822 : Original page 1 not restored by alt register map.
2823 : Original page 2 not restored by alt register map.
2824 : Original page 3 not restored by alt register map.
2825 : Function 28.0 return code not zero.
2826 : Function 28.1 return code not zero.
2827 : Page 0 not restored by orginal register map.
2828 : Page 1 not restored by orginal register map.
2829 : Page 2 not restored by orginal register map.
2830 : Page 3 not restored by orginal register map.


Function 29 ;Warmboot preparation
Function 29 is not tested.


Function 30 ;OS/E functions
Function 30.0 is called to get the OS/E password. Function
30.0 is called again with a bad password. Function 30.1 is
called to disable the OS/E function set. Function 26.2 is
called to see if a disabled function can be accessed.
Function 30.0 is called to enable the OS/E function set.
Function 26.2 is called to access an OS/E function. Function
30.2 is called with a bad password to return the password.
Function 30.2 is called again with the correct password.
Possible error codes:
3000 : Function 30.0 return code not zero.
3001 : Bad password return code not returned when Function 30.0
called with a bad password.
3002 : Function 30.1 return code not zero.
3003 : Function 26.2 did not return access denied return code
when disabled.

3004 : Function 30.0 return code not zero.
3005 : Function 26.2 return code not zero.
3006 : Function 30.2 did not return bad password return code.
3007 : Function 30.2 return code not zero.