21.1  HOW TO USE XMS

XMS usage - short recipe:
1.  Verify have at least 286 (pushf; pop AX; test AX,AX; js error).
2.  Verify vector 2Fh set (DOS 3+ sets it during boot).
3.  AX=4300h, Int 2Fh, verify AL=80h (means XMS installed).
4.  AX=4310h, Int 2Fh, save ES:BX as dword XmsDriverAddr.
5.  AH=8, call [XmsDriverAddr] - returns ax=largest free XMS memory
    block size in kB (0 if error).
6.  AH=9, DX=required size in kB, call [XmsDriverAddr] - allocates
    memory (returns handle in DX - save it).
7.  AH=0Bh, DS:SI->structure {
        dword size (in bytes and must be even),
        word source_handle,
        dword source_offset,
        word destination_handle,
        dword destination_offset }
    (if any handle is 0, the "offset" is Real Mode segment:offset)
8.  AH=0Fh, BX=new size in kB, DX=handle, call [XmsDriverAddr] - changes
    memory block size (without losing previous data).
9.  AH=0Ah, DX=handle, call [XmsDriverAddr] - free handle and memory.

Initially, should process #1-#6, then can use #7 to put data in/get data
from XMS memory, or #8 to change XMS memory block size.  On exit, use #9
to free allocated memory and handle.

Hint:  handle cannot be 0, since zero is used as "no handle allocated"
value.
Errors for XMS calls (except AH=7 - Query A20) are signaled by AX=0.
Error code returned in BL, few codes can check for are:
    80h - not implemented,
    81h - VDISK detected (and it leaves no memory for XMS),
    82h - A20 error (e.g., fail to enable address line A20),
    A0h - all allocated,
    A1h - all handles used,
    A2h - invalid handle,
    A3h/A4h - bad source handle/offset,
    A5h/A6h - bad destination handle/offset,
    A7h - bad length,
    A8h - overlap (of source and destination areas on copy),
    A9h - parity error (hardware error in memory),
    Abh - block is locked,
    00h - OK

For more info read INT 2Fh, AH=43h in Ralf Brown interrupt list.

21.2  WHAT IS THE 'LINEAR BLOCK ADDRESS' RETURNED BY LOCK MEM BLOCK?

When you lock mem block, XMS driver arranges memory governed by it in a
way the locked block forms one contiguous area in linear address space
and returns you starting address of the memory.  Linear address is base
address of segment + offset in segment, in Real Mode it is
segment*16+offset, in Protected Mode the base address is kept in LDT or
GDT; note offset can be 32-bit on 386+.  If paging is not enabled,
linear address = physical address.  You do not need the linear address
unless you use 32-bit offsets in Real Mode or you use Protected Mode
(see previous answer for explanation of how you can access XMS memory).

Contributor: Jerzy Tarasiuk, JT@zfja-gate.fuw.edu.pl
Last Changed: 30 Jan 95

Some parts © 2009 Advameg, Inc.