
             XMGR, UHDD, UDVD2 and RDISK -- FreeDOS Device Drivers
           =========================================================

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

   XMGR, UHDD, UDVD2 and RDISK are Open Source device drivers for PCs with
   an 80386+ CPU and using FreeDOS.

   XMGR is an "XMS manager" for 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.

   UHDD is a disk caching driver that runs up to 10 BIOS disks of any type
   or size using up to 4 "Legacy" or Native-PCI UltraDMA controllers.   It
   traps Int 13h I-O calls and caches data for disks, A: and B: diskettes,
   and other Int 13h drivers which load first.   If loaded after UHDD, the
   UDVD2 driver (below) will call UHDD to cache CD/DVD data files.    UHDD
   uses Read-Ahead for UltraDMA disks, and its /O switch will overlap disk
   UltraDMA and caching tasks.   Using both is up to 20% faster than older
   "UIDE" drivers!   Write-Through caching is done (NO "delayed" output!).
   UHDD's cache uses XMS memory and holds up to 4 Gigabytes of data.   Its
   /B switch also sets a basic UltraDMA disk driver (no cache) taking 128K
   of XMS as its buffer for I-O unsuited to UltraDMA.   The basic UHDD can
   handle tests and other noncached work.

   UDVD2 is a CD/DVD driver for up to 4 SATA, IDE, or old PIO-mode drives.
   It reads CD/DVD data files, plays audio CDs, and can read "raw" (track-
   writer) data.   UDVD2 can work alone; or if the caching UHDD is in use,
   UDVD2 calls it to cache CD/DVD data files and directories (audio/track-
   writing is uncached).   UDVD2 takes 128K of XMD as its buffer for input
   unsuited to UltraDMA.   It shares UHDD's buffer, or it will set its own
   buffer if UHDD is unused.

   RDISK is a RAM-disk driver.   It creates a fast "disk" using up to 2-GB
   of XMS memory.   Files can be uploaded using FDAUTO to the RAM-disk and
   accessed at memory speeds.    RDISK is a simple RAM-disk driver with no
   resizing or other options.

   The small RDISKON.COM program will re-enable an RDISK drive if a format
   command is issued to it by mistake!   Entering  RDISKON L  at a command
   prompt, where L is the drive letter (A to Z), re-enables the drive.

   The small CC.COM "Clear Cache" program can help verify files written by
   UHDD.   Entering  CC  at a command prompt makes UHDD "flush" its cache.
   Disk data (NOT cache data) can then be compared to the original output.
   Some disks (CompactFlash cards, etc.) may cause CC to run very slowly.

   NOTE:  Due to the 2019-21 UHDD updates, UIDE is now obsolete and is not
          included with these drivers.   Use UHDD with UDVD2 instead.


2. NO Warranty
   -----------

   XMGR, UHDD, UDVD2 and RDISK are offered at no cost, as-is, "Use at your
   own risk" and with NO warranty, not even an implied warranty of FITNESS
   for any specific purpose, nor an implied warranty of MERCHANTABILITY!


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

   30-Oct-21   UHDD uses mostly caching logic for noncached work, saving
                 650+ bytes!    UHDD.SYS is now less than 5K, for "boot"
                 diskettes etc.    All UHDD features, switches and cache
                 speeds remain UNCHANGED!    [The /B noncached UHDD, not
                 often used, is ~ 300 bytes larger than before].

   15-Jun-21   UHDD runs up to 10 BIOS disks of all types and size using
                 up to 4 "Legacy" and "Native PCI" UltraDMA controllers.
                 All caches from 5-MB to 4093-MB (4-GB) are now allowed.
                 All caches do Read-Ahead and can do DMA/Caching Overlap
                 (with /O), for faster speed with old small-memory PCs.

   14-Jul-20   UHDD's /O switch now enables DMA/Caching Overlap!    It and
                 Read-Ahead allow UHDD up to 20% faster caching speed than
                 UIDE on V6.22 MS-DOS and similar speed gains for FreeDOS.
                 See the comments about UHDD /O in Section 5, below.   Due
                 to Overlap, UHDD now runs up to 20 BIOS disks (was 22).

    7-Jul-20   UHDD allows all 10-MB+ caches to help old small-memory PCs.
                 For 10-MB+ caches, Read-Ahead is used for UltraDMA disks.
                 Default cache size is 20-MB, if /S is omitted or invalid.
                 BUG fixes:  Controller-number mask is now 03Ch (not 01Ch)
                 to handle 9 controllers properly, and Init logic does not
                 clobber disk "LBA48" flags.

   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 used by Ninho on his 386/SX are added.

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

   31-Mar-19   UHDD uses Read-Ahead for UltraDMA disks with 20-MB+ caches.

   15-Feb-19   UHDD updated from the 5-Mar-2015 version as follows:

        10-MB and all 20-MB+ cache sizes added, for old systems with small
        memory.   Default is still 80-MB if UHDD's /S switch is omitted or
        invalid.

        The 5-MB cache has 16K cache blocks, the 10- and 15-MB caches have
        32K blocks, and the 20-MB+ caches use 64K blocks for faster speed.

        Maximum cache size is still 4 Gigabytes (really 4093-MB; 3-MB held
        for UHDD's cache tables [max. 1-MB] and mainboard control regs.).

        The 5-Mar-2015 UDVD2 can still call this UHDD to cache CD/DVD data
        files; no UDVD2 changes needed.

        If LBACache is wanted, the non-cached UHDD /B can still load first
        to provide disk UltraDMA.

        The 80386 "errata" commands used by Ninho on his 386/SX are added.

        SSDs and CompactFlash cards with an ATAPI flag are run as UltraDMA
        disks, not as slower "Call the BIOS" drives like before.

        Disks over 128-GB now use only LBA48 commands, to stop disk ERRORS
        at exactly 128-GB when an LBA28 command "crosses OVER" that limit!
        All disks less than 128-GB still use LBA28 commands.

   For earlier revision notes, see the 5-Mar-2015 README file.


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

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

      /B     Specifies "boot" mode.   XMGR loads in a temporary area 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, allowing too few interrupts during XMS moves, may
                still be in use!

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

   UHDD usually needs only a /H switch to load in the HMA, a /S switch to
   set a cache size, and a /O switch to enable DMA/Caching Overlap (best,
   for most systems!).   All UHDD switches are:

      /A     Requests "alternate" addressing for "legacy" IDE controllers,
                01E8h/0168h for the first one, 01F0h/0170h for the second.
                /A is rarely needed.   Without /A, the first "legacy" con-
                troller will use 01F0h/0170h and a second uses 01E8h/0168h
                as is usual for PC mainboards.

      /B     Sets a "basic" UltraDMA disk driver (no cache), using 128K of
                XMS as its buffer for I-O unsuited to UltraDMA.   With /B,
                the /E /O and /S switches are ignored.

      /E     Does not use UltraDMA, for old 80386/80486 PCs that never had
                UltraDMA!    UHDD "calls the BIOS" for disk I-O and caches
                data (as needed) after the BIOS is done.   With /E, the /A
                /Q and /Z switches are ignored.

      /H     Puts most of the driver in "free HMA" space.   To use /H, the
                driver must load from FDAUTO.BAT (not FDCONFIG.SYS), since
                FreeDOS provides no "free HMA" until FDAUTO is run.

      /O     Overlaps disk UltraDMA with caching tasks, for faster speed.
                Although preferred, /O may NOT work on old/odd/"cheap" PC
                mainboards unable to do UltraDMA and access XMS memory at
                the same time!   Systems should be tested, using /O.   If
                disk errors occur, but CD/DVD input via UDVD2 works fine,
                /O must NOT be used!

      /Q     Awaits "data request" before starting UltraDMA I-O transfers.
                /Q is rarely needed, only for old systems where the driver
                loads O.K. but seems unable to transfer data.    /Q is NOT
                for use with Sabrent or other SATA-to-IDE adapters that do
                not emulate "data request"!

      /R15   "Reserves" 15-MB or 63-MB of XMS, for old DOS "game" programs
      /R63      which require XMS memory below 16- or 64-MB.   The drivers
                must be able to reserve this memory, reserve their own XMS
                memory beyond that, and then "free" the 15/63-MB XMS.   If
                not, the drivers display "XMS init error" and abort!    /R
                for UDVD2 is ignored if it loads after UHDD, as UDVD2 will
                then share UHDD's XMS memory.

      /Snn   Requests the desired cache size, in megabytes of XMS memory.
                Values are any number from 5 to 4093 (4-GB).    A minimum
                20-MB cache is recommended when possible, for best speed.
                If /S is omitted or invalid, a 20-MB cache is set.   UHDD
                displays "XMS init error" and aborts, when not-enough XMS
                is free!   If so, request a smaller cache.

      /Z     Moves protected-mode XMS data in 8K blocks (not 64K) for 486+
                CPUs and 4K blocks for slow 386 CPUs.   For more /Z notes,
                see /Z for XMGR, above.

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

   UDVD2 normally needs only a /H switch to use HMA space and a /D: switch
   to set a "device name" for SHSUCDX/MSCDEX.   All UDVD2 switches are:

      /A     See /A for UHDD, above.

      /D:    Specifies the "device name" used by the CD/DVD Redirector to
                access CD/DVD drives, e.g.   /D:CDROM1   /D:SANYO1   etc.
                If /D: is omitted, or the name following a /D: is missing
                or invalid,  UDVD1  is set by default.

      /H     See /H for UHDD, above.

      /Rnn   See /R for UHDD, above.

      /UX    Disables all CD/DVD UltraDMA, even for units that can do it.
                All CD/DVD data input then uses PIO-mode.   /UX is rarely
                needed, only for odd drives that do not obey ATAPI rules.

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

   RDISK uses only /S size and /: drive-letter switches:

      /Sn    Specifies a desired RAM-disk size in megabytes of XMS memory.
                Values are any number from 2 to 2047 (2-GB).    When /S is
                omitted or invalid, a 25-MB RAM-disk is set by default.

      /:L    Specifies the DOS drive letter desired to access RDISK files.
                L may be any available drive letter from A to Z, e.g.  /:N
                assigns drive N: to all RDISK files.   If the drive letter
                is too high or already in use, RDISK will abort, and users
                will need "LASTDRIVE=" in FDCONFIG.SYS to set more drives.
                If RDISK loads from FDCONFIG.SYS, or if /: is omitted, the
                next free drive letter will be used.

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

   For all switches in each driver, 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, NANSI.SYS, etc. can then load in any desired order.

   For each of the above examples, FDAUTO.BAT can then load UHDD and UDVD2
   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" with it to do CD/DVD data file caching.    Example
   FDAUTO command lines are:

          ..
          ..  Int 13h drivers cached via UHDD load
          ..  now and can be loaded in upper memory.
          ..
      DEVlOAD /H C:\BIN\UHDD.SYS /S250 /H /O     ;Min. 20 MB recommended
      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.
   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 and other "EMM" drivers except JEMM386 must be avoided!    Other
   "EMM" drivers got dropped long ago, some with remaining ERRORS, and may
   not work on new "fragmented XMS" mainboards.   JEMMEX or other combined
   EMM + XMS drivers CANNOT be used with a "cheap BIOS" mainboard, as UHDD
   cannot be loaded before JEMMEX (no XMS) nor after it (the BIOS fouls-up
   UltraDMA)!   To run in protected-mode on newer "cheap BIOS" boards, use
   FDCONFIG.SYS example C with the changes noted herein, and be aware that
   JEMM386 or a similar UP-TO-DATE "EMM" driver will be REQUIRED!

   XMGR.SYS uses file-compression to reduce its size, as it loads first in
   an "empty" system.    But UHDD.SYS or UDVD2.SYS can load via FDAUTO.BAT
   into small "vacant" memory areas left by "transient" programs that have
   been unloaded.   Uncompression of UHDD/UDVD2 can then overwrite what is
   in memory ABOVE them and cause a CRASH!   To prevent this, UHDD.SYS and
   UDVD2,SYS must NEVER be compressed by "UPX" or other similar programs!

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

   UHDD works as a "BIOS driver" and returns whatever codes are set by the
   BIOS for diskettes and hard disks handled by it.   For its own SATA and
   IDE disks, 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!

   UHDD handles only "Legacy" or "Native PCI" IDE controllers.   RAID-only
   chipsets, "port multiplier" chips, and ADMA chipsets are not supported.
   UHDD must use "Legacy", "Compatibility", or "Native IDE" mode with AHCI
   controllers.   For mainboards with no such controller settings, Sabrent
   or similar SATA-to-IDE adapters will let UHDD/UDVD2 run SATA disks/CDs/
   DVDs from a parallel-port IDE controller (80-pin cable), at DMA speeds.
   "Add on" PCI-bus adapter cards, that can be detected via normal PCI-bus
   logic, 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 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 UHDD can be loaded.   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 UHDD will 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!

