xms-specification.txt

dos xms ems386 standard

Query A20 (Function 07h)
ARGS:

AH = 07h 
RETS:

AX = 0001h if the A20 line is physically enabled, 0000h otherwise 
ERRS:

BL = 00h if the function succeeds 
BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
This function checks to see if the A20 line is physically enabled. It does this in a hardware independent manner by seeing if "memory wrap" occurs. 

Query Free Extended Memory (Function 08h)
ARGS:

AH = 08h 
RETS:

AX = Size of the largest free extended memory block in K-bytes 
DX = Total amount of free extended memory in K-bytes 
ERRS:

BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
BL = A0h if all extended memory is allocated 
This function returns the size of the largest available extended memory block in the system. 

NOTE: The 64K HMA is not included in the returned value even if it is not in use. 

Allocate Extended Memory Block (Function 09h)
ARGS:

AH = 09h 
DX = Amount of extended memory being requested in K-bytes 
RETS:

AX = 0001h if the block is allocated, 0000h otherwise 
DX = 16-bit handle to the allocated block 
ERRS:

BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
BL = A0h if all available extended memory is allocated 
BL = A1h if all available extended memory handles are in use 
This function attempts to allocate a block of the given size out of the pool of free extended memory. If a block is available, it is reserved for the caller and a 16-bit handle to that block is returned. The handle should be used in all subsequent extended memory calls. If no memory was allocated, the returned handle is null. 

NOTE: Extended memory handles are scarce resources. Programs should try to allocate as few as possible at any one time. When all of a driver's handles are in use, any free extended memory is unavailable. 

Free Extended Memory Block (Function 0Ah)
ARGS:

AH = 0Ah 
DX = Handle to the allocated block which should be freed 
RETS:

AX = 0001h if the block is successfully freed, 0000h otherwise 
ERRS:

BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
BL = A2h if the handle is invalid 
BL = ABh if the handle is locked 
This function frees a block of extended memory which was previously allocated using Function 09h (Allocate Extended Memory Block). Programs which allocate extended memory should free their memory blocks before exiting. When an extended memory buffer is freed, its handle and all data stored in it become invalid and should not be accessed. 

Move Extended Memory Block (Function 0Bh)
ARGS:

AH = 0Bh 
DS:SI = Pointer to an Extended Memory Move Structure (see below) 
RETS:

AX = 0001h if the move is successful, 0000h otherwise 
ERRS:

BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
BL = 82h if an A20 error occurs 
BL = A3h if the SourceHandle is invalid 
BL = A4h if the SourceOffset is invalid 
BL = A5h if the DestHandle is invalid 
BL = A6h if the DestOffset is invalid 
BL = A7h if the Length is invalid 
BL = A8h if the move has an invalid overlap 
BL = A9h if a parity error occurs 
Extended Memory Move Structure Definition: 

        ExtMemMoveStruct    struc
            Length              dd  ?   ; 32-bit number of bytes to transfer
            SourceHandle        dw  ?   ; Handle of source block
            SourceOffset        dd  ?   ; 32-bit offset into source
            DestHandle          dw  ?   ; Handle of destination block
            DestOffset          dd  ?   ; 32-bit offset into destination block
        ExtMemMoveStruct    ends

This function attempts to transfer a block of data from one location to another. It is primarily intended for moving blocks of data between conventional memory and extended memory, however it can be used for moving blocks within conventional memory and within extended memory. 

NOTE: If SourceHandle is set to 0000h, the SourceOffset is interpreted as a standard segment:offset pair which refers to memory that is directly accessible by the processor. The segment:offset pair is stored in Intel DWORD notation. The same is true for DestHandle and DestOffset. 

SourceHandle and DestHandle do not have to refer to locked memory blocks. 

Length must be even. Although not required, WORD-aligned moves can be significantly faster on most machines. DWORD aligned move can be even faster on 80386 machines. 

If the source and destination blocks overlap, only forward moves (i.e. where the source base is less than the destination base) are guaranteed to work properly. 

Programs should not enable the A20 line before calling this function. The state of the A20 line is preserved. 

This function is guaranteed to provide a reasonable number of interrupt windows during long transfers. 

Lock Extended Memory Block (Function 0Ch)
ARGS:

AH = 0Ch 
DX = Extended memory block handle to lock 
RETS:

AX = 0001h if the block is locked, 0000h otherwise 
DX:BX = 32-bit physical address of the locked block 
ERRS:

BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
BL = A2h if the handle is invalid 
BL = ACh if the block's lock count overflows 
BL = ADh if the lock fails 
This function locks an extended memory block and returns its base address as a 32-bit physical address. Locked memory blocks are guaranteed not to move. The 32-bit pointer is only valid while the block is locked. Locked blocks should be unlocked as soon as possible. 

NOTE: A block does not have to be locked before using Function 0Bh (Move Extended Memory Block). 

"Lock counts" are maintained for EMBs. 

Unlock Extended Memory Block (Function 0Dh)
ARGS:

AH = 0Dh 
DX = Extended memory block handle to unlock 
RETS:

AX = 0001h if the block is unlocked, 0000h otherwise 
ERRS:

BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
BL = A2h if the handle is invalid 
BL = AAh if the block is not locked 
This function unlocks a locked extended memory block. Any 32-bit pointers into the block become invalid and should no longer be used. 

Get EMB Handle Information (Function 0Eh)
ARGS:

AH = 0Eh 
DX = Extended memory block handle 
RETS:

AX = 0001h if the block's information is found, 0000h otherwise 
BH = The block's lock count 
BL = Number of free EMB handles in the system 
DX = The block's length in K-bytes 
ERRS:

BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
BL = A2h if the handle is invalid 
This function returns additional information about an extended memory block to the caller. 

NOTE: To get the block's base address, use Function 0Ch (Lock Extended Memory Block). 

Reallocate Extended Memory Block (Function 0Fh)
ARGS:

AH = 0Fh 
BX = New size for the extended memory block in K-bytes 
DX = Unlocked extended memory block handle to reallocate 
RETS:

AX = 0001h if the block is reallocated, 0000h otherwise 
ERRS:

BL = 80h if the function is not implemented 
BL = 81h if a VDISK device is detected 
BL = A0h if all available extended memory is allocated 
BL = A1h if all available extended memory handles are in use 
BL = A2h if the handle is invalid 
BL = ABh if the block is locked 
This function attempts to reallocate an unlocked extended memory block so that it becomes the newly specified size. If the new size is smaller than the old block's size, all data at the upper end of the old block is lost. 

Request Upper Memory Block (Function 10h)
ARGS:

AH = 10h 
DX = Size of requested memory block in paragraphs 
RETS:

AX = 0001h if the request is granted, 0000h otherwise 
BX = Segment number of the upper memory block 
If the request is granted, 
DX = Actual size of the allocated block in paragraphs 
otherwise, 
DX = Size of the largest available UMB in paragraphs 
ERRS:

BL = 80h if the function is not implemented 
BL = B0h if a smaller UMB is available 
BL = B1h if no UMBs are available 
This function attempts to allocate an upper memory block to the caller. If the function fails, the size of the largest free UMB is returned in DX. 

NOTE: By definition UMBs are located below the 1MB address boundary. The A20 Line does not need to be enabled before accessing an allocated UMB. 

UMBs are paragraph aligned. 

To determine the size of the largest available UMB, attempt to allocate one with a size of FFFFh. 

UMBs are unaffected by EMS calls. 

Release Upper Memory Block (Function 11h)
ARGS:

AH = 11h 
DX = Segment number of the upper memory block 
RETS:

AX = 0001h if the block was released, 0000h otherwise 
ERRS:

BL = 80h if the function is not implemented 
BL = B2h if the UMB segment number is invalid 
This function frees a previously allocated upper memory block. When an UMB has been released, any code or data stored in it becomes invalid and should not be accessed. 

Reallocate Upper Memory Block (Function 12h)
ARGS:

AH = 12h 
BX = New size for UMB in paragraphs 
DX = Segment number of the UMB to reallocate 
RETS:

AX = 1 if the block was reallocated, 0 otherwise 
ERRS:

BL = 80h if the function is not implemented 
BL = B0h if no UMB large enough to satisfy the request is available. In this event, DX is returned with the size of the largest UMB that is available. 
BL = B2h if the UMB segment number is invalid 
This function attempts to reallocate an Upper Memory Block to a newly specified size. If the new size is smaller than the old block's size, all data at the upper end of the block is lost. 

SUPER EXTENDED MEMORY SUPPORT
These changes are intended to provide support for extended memory pools up to 4 Gb in size. The current XMS API, since it uses 16-bit values to specify block sizes in Kb, is limited to 64 Mb maximum block size. Future machines are expected to support memory above 64 MB. 

This support is implemented in the form of extensions to existing functions, rather than entirely new entry points, to allow for more efficient implementations. 

Programs should generally use the existing functions, instead of these extended ones, unless they have an explicit need to deal with memory above 64 Mb. 

Query Any Free Extended Memory (Function 88h)
Entry: 

AH = 88h 
Exit: 

EAX = Size of largest free extended memory block in Kb. 
BL = 0 if no error occurs, otherwise it takes an error code. 
ECX = Highest ending address of any memory block. 
EDX = Total amount of free memory in Kb. 
Errors: 

BL = 80h if the function is not implemented. 
BL = 81h if a VDISK device is detected. 
BL = A0h if all extended memory is allocated. 
This function uses 32-bit values to return the size of available memory, thus allowing returns up to 4GByte. Additionally, it returns the highest known physical memory address, that is, the physical address of the last byte of memory. There may be discontinuities in the memory map below this address. 

The memory pool reported on is the same as that reported on by the existing Query Free Extended Memory function. If the highest memory address is not more than 64 Mb, then these two functions will return the same results. 

Because of its reliance on 32-bit registers, this function is only available on 80386 and higher processors. XMS drivers on 80286 machines should return error code 80h if this function is called. 

If error code 81h is returned, the value in ECX will still be valid. If error code A0h is returned, EAX and EDX will be 0, and ECX will still be valid.