============================================================================
                EMS Magic :: LIM 4.0 Expanded Memory Emulator
                (C) Copyright 2003-2006 Jon Petrosky <Plasma>
                          http://www.phatcode.net/
----------------------------------------------------------------------------
                          Version 1.0 - Nov 6 2006
============================================================================


----------------------------------------------------------------------------
Getting Started
----------------------------------------------------------------------------

Introduction
============

EMS Magic is an expanded memory (EMS) emulator that installs as a removable
TSR and runs under DOS and Windows 9x/NTx. It provides a complete
implementation of the Lotus-Intel-Microsoft (LIM) 4.0 EMS specification,
including a contiguous 64K page frame.

Unlike EMM386 and NTVDM's EMM, EMS Magic will create the page frame wherever
there is room, including lower memory if necessary. This allows it to
provide EMS on systems where other expanded memory managers fail. EMS Magic
also patches the NTVDM expanded memory manager (XMM) to support XMS 3.0
functions and fix a bug regarding free XMS reported.


Why Is It Needed?
=================

In order to cut costs, newer motherboards feature a lot of integrated
devices. (LAN, RAID, SATA, etc.) The ROM for these devices is located in
the upper memory area (UMA), where the EMS page frame typically resides.
When EMM386 or the NTVDM EMM installs, it looks for a contiguous 64K block
of free space in the UMA for a page frame. If there is no room in the UMA
for a page frame, the EMM will not install and you have no EMS.

EMS Magic also tries to create a page frame in the UMA, but if there is no
space, it will create the page frame in conventional memory. This ensures
that all systems will have EMS support, at the expense of 64K conventional
memory.

EMS Magic also allows you to place the page frame manually. For example, if
you know you have space in the UMA for a page frame, but EMM386 or the NTVDM
EMM will not install, you can force EMS Magic to install with a page frame
at a set location in the UMA. (There must be RAM or unused UMBs at this
location.)


How It Works
============

EMS Magic emulates EMS completely in software using expanded memory (XMS).
Unlike EMM386, EMS Magic does not use Virtual 8086 (V86) mode to enable
hardware paging. Instead, data is copied to and from the page frame with
XMS moves. Because hardware paging is not used, the page frame does not have
to be aligned on a 4K/16K page boundary. Furthermore, because EMS Magic
itself operates entirely in real mode, it does not cause problems when the
CPU is already running in V86 or protected mode, as is the case with
Windows.


Limitations
===========

EMS Magic cannot support data aliasing due to the pure software approach.
According to the LIM EMS 4.0 specification, programs must check for hardware
support before using data aliasing. In practice, however, this is not always
the case. Fortunately, an intelligent page mapping algorithm is used which
eliminates most inconsistencies caused by data aliasing.

Another limitation caused by the software approach is that software page
mapping is significantly slower than hardware page mapping. When running a
very mapping-intensive program, such as Impulse Tracker playing a 32-channel
module, on a relatively slow CPU (200 MHz or less), slowdown may be
experienced. However, all modern CPUs (1 GHz+) should have no problem
keeping up with even the most demanding DOS applications.


XMS Fix
=======

Besides providing EMS emulation, EMS Magic can also patch XMS 2.0 drivers to
support XMS 3.0. The primary reason for this is that the HIMEM
implementation provided by Windows NTx supports XMS 2.0 only. Many programs
check for XMS 3.0, even though they use less than 64 MB XMS. In this case,
XMS 2.0 calls are sufficient. EMS Magic translates XMS 3.0 calls to XMS 2.0
calls, enabling these programs to run.

EMS Magic also patches a bug found in Windows NTx, where the amount of free
XMS can be incorrectly reported as more than 16/32 MB when only 16/32 MB is
actually free. (Windows XP supports 32 MB XMS; all other NTx supports 16 MB
XMS only.)


----------------------------------------------------------------------------
Getting Started
----------------------------------------------------------------------------

System Requirements
===================

The system requirements for the EMS Magic TSR (version 1.0) are:

  - 80386 or better CPU*
  - XMS 2.0 or better (HIMEM.SYS)
  - Operating system compatible with MS-DOS 5.0, including, but not
    limited to:
      - FreeDOS 1.0
      - DR-DOS 7.0
      - PC-DOS 6.3, 7.0
      - MS-DOS 5.0, 6.x
      - Windows 9x (95, 98, Me)
      - Windows NTx (NT 3.5, NT 4.0, 2000, XP, 2003, Vista**)

Resident conventional/upper memory, XMS fix only (/NOEMS):

  - 592 bytes for the program code

Resident conventional/upper memory, XMS fix and EMS 4.0 emulator (default):

  - 6848 bytes for the program code
  - 65552 bytes for the page frame, if allocated

  - 16 bytes + 14 bytes per handle for the handle table
    (default is 64 handles, which is 912 bytes)

  - 16 bytes + 18 bytes per handle for the save table
    (default is 4 saves, which is 88 bytes)

  - In addition, one free XMS handle is required, as well as a matching
    amount of free XMS memory for the amount of EMS memory you want to
    emulate.

Resident conventional/upper memory, XMS fix and EMS 3.2 emulator (/EMS32):

  - Same as the requirements for the EMS 4.0 emulator, except only 3120
    bytes are needed for the program code

The requirements for the Windows installer are:

  - Windows NT 4.0 or better
  - 1 MB free hard drive space


* Although EMS Magic is a real-mode program, it uses 32-bit registers
  which are only found in 386 or later CPUs. It may be possible to run EMS
  Magic on a 286 system with a 386 opcode trapping TSR such as EMU386
  (http://members.tripod.com/~survpc/emu386/), although this has not been
  tested. However, given the speed of 286-class CPUs, a hardware EMS board
  would be much faster.

** Only the 32-bit versions of Windows (x86) support MS-DOS emulation
   (NTVDM). Windows Vista x86 will run EMS Magic; however, the limitations
   of WDDM prevent graphical or full-screen DOS programs from running. This
   is a limitation of Windows Vista itself and not EMS Magic.


Installation
============

There are two ways to install EMS Magic: Using the automated Windows
installer (Windows NT 4.0 or later), or manually (DOS and earlier versions
of Windows). Both installation packages can be downloaded from
http://emsmagic.phatcode.net/.

Automated Installation
----------------------

  1. Run emsmagic10.exe to start the setup program.
  2. Follow the on-screen instructions to complete the setup.

     Note:

     If you are running Windows NTx, you need to be logged in with an
     administrator account. This is required for the setup program to be
     able to modify your PATH environment variable.

     If you are using Windows 9x, you will be prompted to restart after the
     installation. In this case, you must restart before running EMS Magic,
     otherwise the changes to your PATH environment variable will not be
     updated, and the shortcuts will not work properly.

Manual Installation
-------------------

  1. Create a new directory for EMS Magic.
  2. Extract the contents of emsmagic10.zip to this directory.
  3. If you want to be able to run EMS Magic from any directory, you will
     need to modify your PATH environment variable to include the directory
     EMS Magic is located in.

     Here is an example of the manual installation steps for DOS, assuming
     PKUNZIP is installed:

     C:\>md c:\emsmagic
     C:\>cd \emsmagic
     C:\EMSMAGIC>pkunzip -d c:\emsmagic10.zip
     C:\EMSMAGIC>echo SET PATH=%PATH%;C:\EMSMAGIC >temp
     C:\EMSMAGIC>copy /a c:\autoexec.bat+temp c:\autoexec.bat /y
     C:\EMSMAGIC>del temp
     CTRL+ALT+DEL to restart


Uninstallation
==============

If you installed EMS Magic using the automated Windows installer, you can
use the provided uninstall program to remove it. Otherwise, you can
uninstall it manually.

Automated Uninstallation
------------------------

  1. Start the EMS Magic uninstall program one of the following ways:
      - Start Menu -> Programs -> EMS Magic -> Uninstall EMS Magic
      - Control Panel -> Add/Remove Programs -> EMS Magic 1.0 -> Remove
  2. Follow the on-screen instructions to complete the removal.

Manual Uninstallation
---------------------

  1. Delete the directory containing EMS Magic.
  2. Remove this directory from your PATH environment variable.
  3. Remove the EMSMagic environment variable, if it exists.
     (This is created by the Windows automated installation only.)


----------------------------------------------------------------------------
Operation
----------------------------------------------------------------------------

Start Menu
==========

EMS Magic can be launched from the Start Menu in Windows only if the
automated installer is used. If you installed EMS Magic manually, follow the
operation instructions in the Command Line section.

There should be six items listed in the EMS Magic program group in the
Start Menu:

  1. EMS Magic User's Manual
         Launches your default browser to view the HTML version of the
         User's Manual.

  2. Command Prompt with XMS
         Starts a full-screen command prompt with maximum XMS memory, and no
         EMS memory. If using Windows NTx, EMS Magic will be loaded to
         provide XMS 3.0 support.

  3. Command Prompt with XMS and VDMSound
         Same as "Command Prompt with XMS", except VDMSound* is also loaded
         if it is installed.

  4. Command Prompt with XMS & EMS
         Starts a full-screen command prompt with maximum XMS memory, and
         attempts to provide maximum EMS via Windows' EMM. If this is
         successful, EMS Magic will provide XMS 3.0 support only. If Windows
         is unable to provide EMS, EMS Magic will provide XMS 3.0 support as
         well as EMS 4.0 support.

  5. Command Prompt with XMS & EMS and VDMSound
         Same as "Command Prompt with XMS & EMS", except VDMSound* is also
         loaded if it is installed.

  6. Uninstall EMS Magic
         Uninstalls EMS Magic from your system. See the Uninstallation
         section for more details.

You can type EXIT in any command prompt to close the prompt and return to
Windows. You can also switch from full-screen to windowed mode by pressing
ALT+ENTER. Note, however, that some DOS programs (most notably games) may
not run properly when started from a windowed command prompt.

* VDMSound is a Sound Blaster emulator for DOS programs running under
  Windows NTx, which greatly increases compatibility when running DOS
  programs with sound card support. VDMSound is an entirely separate
  program which is not part of EMS Magic, and must be installed separately.
  (See http://www.phatcode.net/downloads.php?id=198 for more information.)


Command Line
============

EMS Magic can be loaded manually from the command line in DOS or Windows. To
start EMS Magic from the command line, type:

emsmagic

This will load EMS Magic with the default options. (See the Advanced section
for a complete listing of all command-line options.)

Once EMS Magic is loaded, it will remain resident in memory, providing XMS
and EMS services, until it is unloaded. To unload EMS Magic, type:

emsmagic /u

If running in Windows, EMS Magic will automatically be unloaded when you
close or exit the command prompt window.

Unlike most memory managers, EMS Magic is a dynamic device driver. This
means you can load and unload it whenever you want, without needing to
restart your computer.

Note:

The above examples assume your EMS Magic directory is in your PATH
environment variable. If you installed EMS Magic manually and chose not to
modify your PATH, you will have to change to (or specify) the full path
containing emsmagic.com.


Advanced
========

EMS Magic supports several command line options (or "switches") that may be
useful for advanced users who need more control. Switches are entered on the
command line, after emsmagic but before pressing the enter key. Both DOS
(/xxx) and Unix (-xxx) style switches are supported. They are not case
sensitive; i.e. both /EMS32 and /ems32 are acceptable. Below is an
explanation of the switches supported:

  /NOXMS
      Do not load the XMS fix.

  /NOEMS
      Do not load the EMS emulator.

  /FORCEXMS
      Load the XMS fix, even if an existing XMS 3.0 driver is detected.
      Default behavior is to load the XMS fix only if XMS 3.0 is not
      detected.

  /FORCEEMS
      Load the EMS emulator even if expanded memory already exists. Default
      behavior is to load the EMS emulator only if no EMM is found.

  /EMS32
      Load EMS 3.2 functions only. Without this switch, all EMS 4.0
      functions are loaded. Loading only EMS 3.2 functions saves about 4K
      conventional/upper memory, but some programs may not run properly.

  /HIGHSCAN or /HI
      Try to use any writeable 64K block in the upper memory area (UMA) for
      the page frame, possibly without allocating it first. Normally the
      page frame is allocated in either an upper memory block (UMB) or
      conventional memory. With the /HIGHSCAN switch, UMB allocation is
      attempted first, and if that fails, then the UMA is scanned for a
      writeable 64K contiguous block of memory. If no writeable block is
      found, then the page frame is allocated in conventional memory. May
      cause memory corruption; use with caution.

  /LOW or /L
      Always allocate the page frame in conventional memory, even if free
      UMBs are available.

  /FRAME=hhhh
      Sets the segment of the page frame without allocating it. hhhh
      specifies the page frame segment in hex. Valid segments are 0001 to
      FFFF. Very likely to cause memory corruption if set incorrectly; use
      with caution.

  /NOFRAME
      Do not allocate or set a page frame. Use this switch only if the
      program you trying to run specifically states it does not require an
      EMS page frame.

  /RAM=xxxxx
      Amount of expanded memory desired. xxxxx specifies the amount of
      memory, in KB. Valid range is 0 to 65520. Amount of EMS specified
      cannot exceed amount of free XMS currently available. If this switch
      is not used, the amount of EMS created will be about half of the free
      XMS available.

  /HANDLES=xxx
      Number of EMM handles. xxx is the number of handles, ranging from 2
      to 255. One handle is always reserved for DOS. The default number of
      handles is 64.

  /SAVES=xxx
      Number of context saves. xxx is the number of saves, ranging from 0
      to 255 The default number of saves is 4.

  /QUIET or /Q
      Suppress all output.

  /UNLOAD or /U
      Unload XMS fix and/or EMS emulator.

  /HELP or /?
      Show command line help.


----------------------------------------------------------------------------
Troubleshooting
----------------------------------------------------------------------------

FAQ
===

Q: When I have EMS Magic loaded, I don't have enough free conventional
   memory to run my program/game.

A: See the Tips section for advice on freeing up conventional memory.


Q: I'm trying to load EMS Magic in my CONFIG.SYS/CONFIG.NT but it's not
   working. Why?

A: EMS Magic is a self-loading dynamic device driver. This means that it
   must be run as a program and not loaded as a device driver, as opposed to
   EMM386. If you want to load EMS Magic at startup, add the line:

   emsmagic

   to your AUTOEXEC.BAT/AUTOEXEC.NT with the appropriate switches.


Q: Can EMS Magic backfill conventional memory?

A: At this time, no. EMS Magic currently supports a single 64K page frame
   only. If there is a demand for it, backfilling support may be added in
   future versions.


Q: Can EMS Magic provide UMBs like EMM386?

A: No. UMB support may be obtained with an alternative driver, such as
   UMBPCI (http://www.uwe-sieber.de/umbpci_e.html), or EMM386 with the NOEMS
   parameter. (This applies to DOS or Windows 9x only; the NTVDM in Windows
   NTx automatically provides UMBs.)


Q: My program/game starts, but the text is all scrambled. Help!

A: This is actually not related to EMS Magic, but it's an easy problem to
   fix. Your video card does not have an 8x14 (EGA) ROM font. Many
   manufacturers leave out this font to save ROM space for other functions.
   A freeware TSR called FIX8X14 can provide an 8x14 font in this case.
   (http://www.bttr-software.de/products/fix8x14/)


Q: Hasn't this been done before?

A: To be honest, when I started this project, I had never heard of an
   existing program that emulated EMS entirely in software using XMS. Of
   course I was wrong. A couple weeks in, I stumbled upon EMS40.SYS
   (Douglas Boling) on Simtel, and then later I found EMSimulator
   (Karlton W. Kam), EMM.SYS (Mike H. Greve), and EMM286 (Jjex Software).

   However, after I tried them out, I found that the existing EMS emulators
   weren't very satisfactory. Most of them take over extended memory
   completely, meaning they won't work HIMEM/XMS. In addition, they support
   only EMS 3.2 functions, or a subset of EMS 4.0 functions. All except
   EMM286 are SYS device drivers, which means they cannot be loaded and
   unloaded dynamically. And none of them managed to work properly with all
   the programs I tested. Actually, most crashed under Windows XP.

   So I decided to continue my project, and I have to say the result is much
   better than any of the previous solutions. But don't take my word for it;
   try out the alternatives for yourself. ;)


Q: How can I contact the author of EMS Magic?

A: Email plasma@phatcode.net or post a message at
   http://forum.phatcode.net/.


Tips
====

Increasing Free Conventional Memory
-----------------------------------

If the page frame cannot be placed in the UMA, typically only 530K to 570K
conventional memory will be free after EMS Magic is loaded, because the 64K
page frame must be placed in conventional memory. If your program needs more
conventional memory, you can try one of the following:

  - Disable unneeded onboard devices in your BIOS setup. This includes
    integrated LAN, RAID, SATA, and legacy USB mouse/keyboard support. This
    will remove ROM mapped to the UMA, possibly freeing up room for a page
    frame in the UMA.

  - Remove unnecessary TSRs or device drivers. Under Windows NTx, CD-ROM
    extensions (mscdexnt), DPMI support (dosx), and the network redirector
    (redir) can all be disabled in AUTOEXEC.NT to save conventional memory.
    Note that dosx and redir are already disabled when an EMS Magic shell is
    launched from the Start Menu.

  - Load the EMS Magic TSR into a UMB with LOADHIGH or LH. Although EMS
    Magic uses UMBs when possible for the handle and save tables, it does
    not load itself into a UMB. This will save 4K to 7K conventional memory.

  - Disable the page frame with the /NOFRAME switch. This is not recommended
    unless the program you trying to run specifically states it does not
    require an EMS page frame.

  - Attempt to place the page frame in any writeable 64K block in the UMA
    with the /HIGHSCAN switch. This is potentially unsafe and could cause
    programs in your DOS session to lock up or crash. Use this with caution.

  - Set the location of the page frame manually with the /FRAME switch. This
    is potentially unsafe and is for advanced users only. Use a utility such
    as MSD to see what areas of the UMA are free.

If none of the above works, then there's not much else you can do, short of
using a full system emulator such as DOSBox (http://dosbox.sourceforge.net/)
or Virtual PC (http://www.microsoft.com/windows/virtualpc/).


Compatibility
=============

An online database is maintained detailing the compatibility of EMS Magic
with various applications.
(http://www.phatcode.net/projects.php?id=102&show=stuff)

Additional programs will be added as they are tested. If you would like to
submit your own test information for one or more programs, please email
plasma@phatcode.net.


----------------------------------------------------------------------------
Reference
----------------------------------------------------------------------------

Real Mode PC Memory Map
=======================

                  ... ... ... ... ... ... ... ... ... ...
                  |                                     | ?????
                  |        Extended Memory (XMS)        |
                  |                                     |
            10FFF +-------------------------------------+
                  |        High Memory Area (HMA)       | 10FFE
                  |                 64K                 |
            10000 +-------------------------------------+
                  |        System Bios ROM - 32K        | FFFF
             F800 +-------------------------------------+
                  |    System BIOS ROM or UMBs - 32K    | F7FF
             F000 +-------------------------------------+
                  |                                     | EFFF
                  |    ROM, UMBs, or EMS Page Frame     |
                  |                160K                 |
                  |                                     |
                  |                                     |
             C800 +-------------------------------------+
                  |           Video ROM - 32K           | C7FF
             C000 +-------------------------------------+
                  |                                     | BFFF
                  |              Video RAM              |
                  |                128K                 |
                  |                                     |
             A000 +-------------------------------------+
                  |                                     | 9FFF
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |         Conventional Memory         |
                  |                639K                 |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
                  |                                     |
             0050 +-------------------------------------+
                  |     BIOS Data Area - 256 Bytes      | 004F
             0040 +-------------------------------------+
                  |     Interrupt Vector Table - 1K     | 003F
             0000 +-------------------------------------+


----------------------------------------------------------------------------
About
----------------------------------------------------------------------------

Development
===========

EMS Magic was written over a three year period, from fall 2003 to fall 2006.
Being a one-man part-time project, actual time spent was probably closer to
6-8 months total. It was completely rewritten about halfway through, to
allow for more flexibility.

The entire program is written in real-mode 386 assembly, using TASM's IDEAL
mode. There are over 4500 lines of code, not including comments or
whitespace.

Main program development was done on an Athlon 2800+ running Windows XP.
Turbo Assembler 5.0 and WarpLink 2.7 were used to assemble and link EMS
Magic via ConTEXT 0.9x.

An EMS "torture test" program was written in QuickBASIC 4.5 to test every
LIM EMS 4.0 function and subfunction. Debugging was done on a networked
K6-233, running MS-DOS 6.22. Initially debugging information was output on
a monochrome monitor. Later an IPX interface was added to permit debug
output logging. SoftICE 2.8 and Turbo Debugger 5.0 were also used
occasionally for debugging.

The automated Windows installer was created with Inno Setup 5.


Testers
=======

Special thanks to the following testers for their help with testing EMS
Magic during the beta stage:

                 Robert Braun            Janne Koponen
                 David Chaney            Claire Lonnen
                 Mike Fraley             George Marinov
                 Stefan Hendriks         Jesse Perez
                 Steven Hidy             Michael Romanovsky
                 Jeremy Holt             Tim Smith
                 Alan Huseby             Marshall Wilson


License
=======

EMS Magic is freeware. It may be legally copied and distributed without
limitation, provided the following two conditions are met:

  1. All the original files are included in their unmodified form.

  2. It is not sold. That is, no amount whatsoever may be charged for this
     software, even if it is only for the distribution media. It may not be
     bundled with any software that is not available completely free of
     charge, including shareware and commercial demos.

EMS Magic is provided AS IS, without any warranty, either expressed or
implied. In no event shall the author be liable for damages of any type
caused by the use or inability to use the software.

EMS Magic is not designed for use in high risk activities, in which the
failure of the software could lead directly to critical data loss, death,
personal injury, or severe physical or environmental damage.

EMS Magic is copyright (c) 2003-2006 Jon Petrosky. All rights reserved.
