                       XMGR -- DOS Device Driver
          ===========================================================

1. Description
   -----------

   XMGR is an Open Source DOS "XMS manager" for a PC system with an
   80386+ CPU and using FreeDOS, supporting up to 4-GB of XMS memory,
   with support for V3.70+ UMBPCI by Uwe Sieber. XMGR can load directly to
   UMBPCI "Shadow RAM" upper memory, and it can "boot" into regular upper
   memory if using JEMM386.
   See the example FDCONFIG.SYS files in Section 5 below.


2. NO Warranties
   -------------

   XMGR is offered at no cost, as-is, "Use at your own risk", and with
   NO warranties, not even an implied warranty of FITNESS for any
   purposes, nor an implied warranty of MERCHANTABILITY!


3. Revision Summary
   ----------------

   15-Apr-20   XMGR updated from the 5-Mar-2015 version as follows:

        The "I-O Catcher" now handles a maximum of 16 BIOS hard disks.

        Real-mode and /Z protected-mode XMS move sections are 4K bytes
          for faster speed (was 2K).

        The /B "boot" option now permits /N32 to set 32 XMS "Handles",
          saving 160 low-memory bytes versus the 48 "Handles" default.

        The 80386 "errata" commands recommended by Ninho are included.

        The HIMEM de-facto standard driver name of "XMSXXXX0" is used.

   28-Nov-10   Minor updates:  XMGR faster in protected-mode. Added /Z.

    4-Jul-10   README file update -- XMGR can use "Native IDE" mode, same
                 as "Legacy"/"Compatibility", for AHCI mainboards.

   28-Jun-10   XMGR updated for AHCI, see section 5 for details.

    1-May-09   Fixed XMGR "Port 92h" logic error.  Added XMGR /PA and /PN
                 switches to control use of "Port 92h".

   25-Apr-09   XMGR license and FreeDOS prohibition deleted, drivers and
                 sources are again available to all.


4. Switch Options
   --------------

   XMGR usually needs only its /B switch, if "booting" with an EMM driver.
   All XMGR switch options are as follows:

      /B     Specifies "boot" mode.   XMGR loads in temporary memory until
                JEMM386 enables upper memory.    Without /B, XMGR loads in
                UMBPCI "Shadow RAM" or in low memory if UMBPCI is unused.

      /Mn    Specifies a temporary area for loading XMGR in "boot" mode or
                for UMBPCI "Shadow RAM" DMA before a workspace buffer gets
                posted.   Values for /M are:

                    /M1 = 64K.    /M3 = 192K.   /M5 = 320K.   /M7 = 448K.
                    /M2 = 128K.   /M4 = 256K.   /M6 = 384K.   /M8 = 512K.

                Without /M, /M5 is assumed and the 320K area will be used.
                Temporary system data may be put anywhere in memory!   /Mn
                helps to find a safe area for XMGR to use.

      /Nnn   Sets how many XMS "Handles" are available.   The value nn may
                be 48, 80, or 128.   The /B "boot" option now accepts /N32
                to save low memory, but 32 "Handles" may be not-enough and
                should be tested.   Without /N, 48 "Handles" are set.

      /PA    Specifies use or non-use of PS/2 Port 92h logic to handle the
      /PN       system's "A20" line.   /PA indicates "Always" use Port 92h
                logic.   /PN indicates "Never" use it and handle "A20" via
                standard keyboard-port logic.   Without /P, XMGR "asks the
                BIOS" if the system supports Port 92h.   If not, XMGR uses
                keyboard-port logic.    If "A20" is found to be on as XMGR
                loads, XMGR does not handle it at all.

      /Tn    Specifies the BIOS calls to use in getting extended memory:

                   /T0   No "E820h" or "E801h" requests.
                   /T1   Memory-list requests only (Int 15h, AX=E820h).
                   /T2   A dual-area request only  (Int 15h, AX=E801h).
                   /T3   "E820h" requests first, then an "E801h" request.

                /T can usually be omitted, causing a /T3 default.   An old
                64-MB request is also used to get /T0 memory or if the /T1
                to /T3 requests are unsuccessful.   Users may need to test
                /T1 and /T2, as a pre-1996 BIOS might not handle them O.K.
                If so, /T0 will be required.

      /W     Requests using the kernel workspace buffer for UMBPCI "Shadow
                RAM" DMA.   If /W is omitted, XMGR sets its own low memory
                buffer.   /W is ignored if UMBPCI is not used.

      /Z     Moves protected-mode XMS data in 4K blocks (not 64K).    With
                JEMM386, /Z is unneeded.    If other EMM/VCPI/DPMI drivers
                are used, PCs must be tested to see if /Z is needed.   BAD
                schemes, that allow too few interrupts during an XMS move,
                may still be in use!

             --------------------

   For all switches, a dash may replace the slash and lower
   case letters may be used if desired.


5. Example Configuration Files
   ---------------------------

   A) Small real-mode systems that need only XMS may use this FDCONFIG.SYS
      example file:

          ..
          ..
      DOS=HIGH
      DEVICE=C:\BIN\XMGR.SYS
          ..
          ..  Etc.
          ..

   B) Real-mode systems with V3.70+ UMBPCI and XMGR do not need the LOWDMA
      driver, as XMGR sets an "I-O Catcher" for UMBPCI.   This scheme uses
      NO low memory, if /W is given; XMGR and other drivers go directly to
      UMBPCI "Shadow RAM" upper memory!   An example FDCONFIG.SYS file is:

          ..
          ..
      DOS=HIGH,UMB
      DOSDATA=UMB
      DEVICE=C:\BIN\UMBPCI.SYS
      DEVICE=C:\BIN\XMGR.SYS /W
          ..
          ..  Etc.
          ..

   C) A protected-mode system with XMGR and JEMM386 can use XMGR's "boot",
      taking only 384 low memory bytes as its 32-entry "XMS Handles" table
      (used early by JEMM386).   See Section 6 below for other notes about
      protected-mode!   An example FDCONFIG.SYS file is:

          ..
          ..
      DOS=HIGH,UMB
      DOSDATA-UMB
      DEVICE=C:\BIN\XMGR.SYS /B /N32             ;32 Handle XMGR "boot"
      DEVICE=C:\BIN\JEMM386.EXE I=B000-B7FF ...
      DEVICEHIGH=C:\BIN\XMGR.SYS                 ;Loads the runtime XMGR
          ..
          .. Etc.
          ..

   When all above drivers are loaded, other needed FDCONFIG.SYS files such
   as SETVER, ANSI.SYS, etc. can then load in any desired order.

   For each of the above examples, FDAUTO.BAT can then load UHDD and UDVD2
   (or just UIDE) using the DEVLOAD program.   This permits the drivers to
   use "free HMA" and save low memory.   UDVD2 must load after UHDD, so it
   will find UHDD in memory and "link" to it for CD/DVD data file caching.
   Example FDAUTO command lines are:

          ..
          ..  Int 13h drivers cached thru UHDD/UIDE
          ..  load now and can load in upper memory.
          ..
      DEVlOAD /H C:\BIN\UHDD.SYS /S500 /H /O     ;Or UIDE alone
      DEVLOAD /H C:\BIN\UDVD2.SYS /D:BLURAY1 /H
      LH C:\BIN\RDISK.COM /S250                  ;Optional
          ..
          ..  Etc.
          ..


6. Technical Notes
   ---------------

   Protected-mode users must pretest "I=nnnn-nnnn" or "X=nnnn-nnnn" values
   for JEMM386, as its "I=TEST" or "X=TEST" options may fail on newer PCs.
   Protected-mode is unrecommended with old DOS games needing reserved XMS
   as JEMM386 takes some XMS memory first.   Newer "cheap BIOS" mainboards
   now OMIT logic used only by DOS and need an UltraDMA disk driver loaded
   before JEMM386 sets V86 protected-mode!   For such boards, FDCONFIG.SYS
   example C above requires drivers cached thru UHDD, then UHDD itself, to
   load only in LOW memory directly after XMGR sets up XMS for the system.
   UIDE is unrecommended in this case as it will take FAR more low memory!
   JEMM386 can then load and set V86 protected-mode, and UDVD2 (if wanted)
   can be loaded later from FDAUTO.   2015 or older PCs with a normal BIOS
   usually do not need this and can use example C as shown above.   Use of
   JEMMEX or other "EMM" drivers but JEMM386 must now be avoided.    Other
   "EMM" drivers got dropped long ago, some with leftover ERRORS!   JEMMEX
   has caused crashes on newer PCs due to OBSOLETE XMS detection code, and
   it cannot work with UIDE/UHDD on a "cheap BIOS" board as neither driver
   can load O.K. if the other is absent!   To run protected-mode on "cheap
   BIOS" boards, use FDCONFIG.SYS example C with UHDD/UDVD2 (not UIDE) and
   the changes noted herein, and be aware that JEMM386 will be REQUIRED!

   XMGR and UIDE/UHDD/UDVD2 will return normal XMS and CD/DVD error codes,
   as needed.   They are listed in the "V3.0 XMS Specification" and in the
   Microsoft "MS-DOS CD-ROM Extensions 2.1" document.   Both are available
   from Microsoft or from other Internet sources.

   UIDE and UHDD work as "BIOS drivers" and return whichever codes are set
   for diskettes and hard-disks handled by the BIOS.    For their SATA and
   IDE hard-disks, UIDE/UHDD can post the following error codes:

       Code 0Fh - DMA error.           CCh - Disk is FAULTED.
            20h - Controller busy.     E0h - Hard I-O error.
            AAh - Disk not ready.      FFh - XMS memory error.

   Many DOS programs display only "Disk Error" messages with NO code, thus
   disk errors may require running a diagnostic to get better information!

   UIDE/UHDD handle only "Legacy" or "Native PCI" IDE controllers.   RAID-
   only chipsets, port multiplier chips, or ADMA chipsets are unsupported.
   UIDE/UHDD must use "Legacy", "Compatibility", or "Native IDE" mode with
   AHCI controllers.    For mainboards with no such controller settings, a
   Sabrent or similar SATA-to-IDE card can let UIDE/UHDD/UDVD2 handle SATA
   disks/CDs/DVDs from parallel-port IDE controllers (80-pin cable) at DMA
   speeds.   "Add on" PCI-bus adapter cards that can be detected by normal
   PCI-bus routines may also be used for disks/CDs/DVDs.

   XMGR loads in UMBPCI upper memory that is not "provided" to the system.
   With UMBPCI, a "MEM" list may begin with a block having a 00A5h offset,
   or greater with 80 or 128 XMS "Handles".    The upper memory skipped by
   this offset contains XMGR.

   The UMBPCI upper memory manager uses system "Shadow RAM" that cannot do
   DMA.    A newer BIOS may use UltraDMA to load programs in upper memory.
   If this is "Shadow RAM", a HANG can occur!    These two rules apply, if
   using UMBPCI with XMGR and UIDE/UHDD:

     A) V3.70+ UMBPCI must load before XMGR, so XMGR finds UMBPCI and sets
        its "I-O Catcher", to handle diskette "Shadow RAM" DMA forever and
        to do disk "Shadow RAM" UltraDMA until UIDE/UHDD can load.   Older
        UMBPCI drivers, or other UMBPCI load schemes, are not recommended!

     B) When CHS I-O is done, each disk must have valid CHS parameters set
        in the BIOS.   If not, the "I-O Catcher" or UIDE/UHDD let the BIOS
        handle CHS I-O.   If BIOS UltraDMA is left enabled, a "Shadow RAM"
        HANG can occur!

   Old BIOS programs may not configure a mainboard controller when no user
   drives are on it!   The drivers then display "BAD controller" and go on
   looking for others to use.   If this message is given, users must check
   that all SATA/IDE drives are set "active" with the BIOS setup routines.
   If so, "BAD controller" means a chip is not using "Bus Master" and "I-O
   Space" modes, and a BIOS update is needed!
