
	     XDMA and XDMAJR -- DOS UltraDMA Disk Drivers, V3.1
	   ======================================================

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

   XDMA and XDMAJR are DOS drivers for UltraDMA hard-disks.    They handle
   regular "end user" PC mainboards, all of which use an Intel/VIA/SiS/ALi
   or other UltraDMA controller chip set by the BIOS in "Legacy IDE mode".
   XDMA/XDMAJR are NOT for Serial-ATA chips, "Native PCI mode" servers, or
   "add-on" IDE adapter cards offered by Promise, SiiG, etc.   XDMA/XDMAJR
   handle normal mainboard IDE chips and AVOID needing any "add-on" cards!

   XDMA/XDMAJR run up to 4 UltraDMA disks of any size, including new types
   over 128 gigabytes of storage.   They "intercept" DOS disk I-O requests
   issued as "Int 13h" calls for the BIOS; read/write requests are handled
   using UltraDMA.    All other "Int 13h" calls (seeks, requests for other
   device types, etc.) are "passed" back to the BIOS or to another driver.
   XDMA/XDMAJR accept 48-bit LBA mode I-O requests issued by MS-DOS V7.xx,
   FreeDOS, and other newer DOS systems that handle LBA mode I-O.   24-bit
   CHS mode requests issued by MS-DOS V6.xx or other "old" DOS systems are
   also accepted.   As CHS I-O has only 24-bit addresses, data accessed by
   CHS I-O must be in the first 8 gigabytes of a disk.    Other partitions
   may contain more data and may be accessed by operating systems that use
   48-bit LBA mode I-O.

   XDMA offers output overlap, which buffers all output and does NOT await
   output end, so user work may overlap the DMA!   Depending on the user's
   system and software, overlap can increase speed significantly!   For an
   output error or 400-msec output timeout, an error message will display,
   and a warning "beep" will sound.   Overlap requires XMS memory and must
   be enabled by a /O in the CONFIG.SYS command that loads XDMA (section 3
   below describes all switches).    Output overlap requires that each IDE
   channel CANNOT run an UltraDMA disk and an ATAPI drive (ZIP, CD-ROM) or
   any non-UltraDMA unit!   Other drivers are not aware XDMA leaves output
   "running", and such drivers may post a "controller busy" ERROR if using
   the same channel as XDMA.   If either IDE channel runs an UltraDMA disk
   with an ATAPI or non-UltraDMA unit, overlap may NOT be used EXCEPT with
   the XCDROM and XZIP drivers (available in 2006!), which DO check XDMA's
   "busy" and "overlap" flags and do not cause IDE channel errors!    XDMA
   is meant for most "home user" systems, which usually run their UltraDMA
   hard-disk(s) on the primary IDE channel, while ATAPI or other units run
   on the secondary IDE channel.   Systems configured this way do NOT need
   XCDROM or XZIP; they can achieve better speed IMMEDIATELY by using XDMA
   with output overlap!

   XDMA takes 1408 bytes of memory if output overlap is enabled, 992 bytes
   in "normal" mode with XMS memory and with its local-stack, or 656 bytes
   with XMS memory and /N requesting NO local-stack.   See section 3 below
   for driver switch options.   XDMA will use an XMS manager, HIMEM.SYS or
   similar, and 128K of XMS memory as its "local buffer".   For overlap or
   for any user I-O buffers not meeting UltraDMA alignment/boundary rules,
   UltraDMA I-O goes through the "local buffer", which acts as a middleman
   between the user buffer and the disk.    Almost all DOS systems do load
   HIMEM.SYS since it lets the DOS "kernel" reside in the high-memory area
   (HMA) and saves MUCH space below 640K!   On systems with no XMS memory,
   overlap is NOT enabled, and XDMA will run in "DMA only" mode.   In "DMA
   only" mode, I-O not suitable for UltraDMA will be "passed" to the BIOS.
   XDMA uses 992 bytes with its local-stack and only 592 bytes with /N (no
   local-stack) in "DMA only" mode.

   XDMAJR is a smaller driver, for systems where output overlap may not be
   used due to no XMS memory or IDE channel setup problems.   XDMAJR omits
   overlap, to minimize its file size, but it offers all other features of
   the larger XDMA.   XDMAJR also uses 992 bytes of memory in normal mode,
   656 bytes using /N (no local-stack) and XMS memory, and 592 bytes using
   /N and "DMA only" mode.   XDMAJR is designed similarly to XDMA and will
   handle up to 4 UltraDMA disks of any size, reserves a "local buffer" in
   XMS memory or will run in "DMA only" mode, offers a local-stack and has
   full "protection" logic, etc.


2. Revision History
   ----------------

   V3.1  26-Dec-05  XDMA with overlap is now named "XDMA1$", so other IDE
		      drivers can invoke its "OCheck" to monitor overlap.
		      Minor XDMA and XDMAJR updates.   NO changes in run-
		      time sizes.

   V3.0  15-Dec-05  XDMA/XDMAJR now set "XDMA_$" names (overlap XDMA sets
		      "XDMA$$") to confirm controller address valid.  All
		      other IDE drivers can set up UltraDMA easily if ANY
		      V3.0+ XDMA or XDMAJR driver is present!

   V2.9  14-Dec-05  XDMA output overlap "re-entry" routine corrected.  No
		      change to non-overlap XDMA nor to XDMAJR.

   V2.8  27-Nov-05  XDMA and XDMAJR "Internationalized"!    Init messages
		      are now a separate file, defaulting to XDMAMSGS.ENG
		      (English), but other files CAN be used on assembly.
		      Read XDMAMSGS.ENG for full details.

   V2.7  24-Nov-05  XDMA output-overlap now sets IDE channel busy/overlap
		      flags, so overlap WILL work using other IDE drivers
		      that check XDMA's flags (e.g. XCDROM or XZIP, ready
		      in 2006)!   NO non-overlap XDMA nor XDMAJR changes!

   V2.6  17-Nov-05  XDMA/XDMAJR now have a /N switch to request NO local-
		      stack.   With /N, each driver now uses 656 bytes if
		      XMS is available and 592 bytes for "DMA only" mode!
		      XDMA.ASM now has "common" code and assembles EITHER
		      driver!   "DRQ timeout" replaced with "DMA timeout"
		      code in both drivers' error handling.

   V2.5  10-Nov-05  Re-added /B, /S, "DMA only" mode to XDMA.    Re-added
		      /S to XDMAJR.   Except for no XDMA read-tests, XDMA
		      and XDMAJR are now EQUAL to the older UDMA2/UDMA2S!

   V2.4   5-Nov-05  README.TXT file updated with "advisory" RULES for use
		      of UMBPCI.   Minor XDMA and XDMAJR size reductions.

   V2.3   2-Nov-05  XDMA and XDMAJR have better messages, the full set of
		      error codes, and allow different CHS values for all
		      disks.   XDMAJR is also upgraded, with switches and
		      an 80386+ test; it now has ALL features of XDMA but
		      output-overlap!   XDMAJR now offers "DMA only" mode
		      and can run on systems with no XMS memory.

   V2.2  23-Oct-05  Fixed "NMI" stack-switching error in XDMA and XDMAJR.

   V2.1  21-Oct-05  Fixed XDMA /M error.  No changes to XDMAJR.

   V2.0  15-Oct-05  XDMA made smaller; re-added XDMAJR disk-name display.

   V1.9  10-Oct-05  Fixed XDMAJR "no disks" error.  Minor changes in both
		      drivers to improve subroutine reliability.

   V1.8   2-Oct-05  Re-added a load-time 80386+ test in XDMA only.   On a
		      lesser CPU, XDMA displays an error and merely exits
		      to avoid a system CRASH!   Re-added a hardware-only
		      disk scan in XDMAJR; removed its disk-name displays
		      to make room!   Corrected the EDD BIOS disk scan in
		      both drivers.

   V1.7  24-Sep-05  Re-added a hardware-only disk scan in XDMA, to handle
		      an IBM ThinkPad and other systems with a missing or
		      incomplete EDD BIOS (see section 6 below).   XDMAJR
		      unchanged.

   V1.6  15-Sep-05  Changed to NASM source format for both drivers, which
		      may now be reassembled using the NASM assemblers by
		      SourceForge.   Fixed an LBA-mode error in XDMAJR.

   V1.5  22-Aug-05  Added the smaller/simpler XDMAJR; no changes to XDMA.

   V1.4  18-Aug-05  Fixed ES-reg. saves/reloads and minimized init logic.

   V1.3   3-Aug-05  Added David Muller's EDD BIOS 30-byte "validity test"
		      and his class-codes to handle ALi controller chips.
		      THANK YOU, David!

   V1.2  30-Jun-05  Eliminated "forward code-modification" errors.
   V1.1  18-Jun-05  Simpler README file; added version number to title.
   V1.0  15-Jun-05  Original XDMA issue.


3. Switch Options
   --------------

   XDMA and XDMAJR switch options are as follows:

      /O    For XDMA only, enables output overlap.    This REQUIRES an XMS
	      manager and 128K of XMS memory.   If XMS is not available or
	      /B is also given, overlap will NOT be enabled.

      /L    Limits DMA to "low memory" below 640K.   /L is REQUIRED to use
	      UMBPCI or similar drivers whose upper-memory areas cannot do
	      DMA.   If /L is given, the driver must be in LOW memory (I-O
	      command lists use DMA), or driver loading ABORTS!   /L makes
	      the driver use its "local buffer" for I-O of data past 640K.
	      If XMS is unavailable or /B is also given, such I-O requests
	      are "passed" to the BIOS.   For "advisory" RULES about using
	      XDMA/XDMAJR with the UMBPCI driver, see section 6 below.

      /B    Causes XMS memory to be IGNORED, for "backward compatibility".
	      /B cancels /O, forces the driver to use "DMA only" mode, and
	      affects /L as noted above.

      /Mn   Specifies the MAXIMUM UltraDMA "mode" to be used by all disks,
	      where  n  is a number between 0 and 7, as follows:
		  0 = ATA-16, 16 MB/sec.     4 = ATA-66,   66 MB/sec.
		  1 = ATA-25, 25 MB/sec.     5 = ATA-100, 100 MB/sec.
		  2 = ATA-33, 33 MB/sec.     6 = ATA-133, 133 MB/sec.
		  3 = ATA-44, 44 MB/sec.     7 = ATA-166, 166 MB/sec.
	      Disks designed to a "mode" LESS than the given value will be
	      limited to their own highest "mode".   Every disk's designed
	      "mode" should be preset by the BIOS, even if the BIOS itself
	      does no UltraDMA I-O.   At present, "mode 7" ATA-166 has not
	      been implemented, but each driver can set it when available.

      /N    Requests NO driver local-stack.   /N is ignored if XDMA output
	      overlap will be enabled (overlap REQUIRES the local-stack!).
	      If both /N and /S are given, the FINAL one in the CONFIG.SYS
	      command that loads the driver shall take effect.   For other
	      than output-overlap use, both drivers default to SETTING the
	      local-stack with XMS memory and NOT setting a stack for "DMA
	      only" mode.    /N and /S can be given to change stack usage.
	      Note that without a local-stack, the drivers run on the USER
	      stack, to save memory.   This should be done ONLY on a well-
	      behaved system with NO "short stack" user programs!!

      /Q    For XDMA only, suppresses the "beep" for output-overlap errors
	      ("quiet" mode).

      /S    Requests a driver local-stack.   /S is ignored for XDMA output
	      overlap, as overlap already REQUIRES the local-stack!    See
	      the other comments about this switch in the /N notes, above.

   Most users need only /O to enable XDMA output-overlap, /L if the UMBPCI
   driver (or similar) will also be loaded, and /S to ensure a local-stack
   when "DMA only" mode could be used.   The other switches may be used as
   needed for diagnostic work or for other special situations.    For each
   switch, a dash may replace the slash, and lower-case letters are O.K.


4. Setup and Configuration
   -----------------------

   XDMA or XDMAJR is loaded by the CONFIG.SYS file, after any upper-memory
   manager such as EMM386.EXE, but BEFORE any "disk cache" program such as
   NCACHE2.   Your CONFIG.SYS file must have a command line similar to:

	    DEVICE[HIGH] = [path]XDMA.SYS [/O] [/L] [...]
			 = [path]XDMAJR.SYS [/L] [...]

   Examples:    DEVICE=C:\DOS\XDMA.SYS
		DEVICEHIGH=C:\BIN\XDMA.SYS /O

		DEVICE=C:\BIN\XDMAJR.SYS /L /M4
		DEVICEHIGH=C:\DRIVERS\XDMAJR.SYS

   Please be sure to set each hard disk's geometry correctly in your BIOS.
   Set it to "Auto", "LBA" or "LBA Assisted", but NOT to "None", "Normal",
   "CHS", "ECHS".   "User Cylinders/Heads/Sectors", "Revised ECHS" or "Bit
   Shift" should run but are NOT preferred.   If a BIOS has a setting like
   "UDMA Capable" for a disk, enable it.   Power-saving features such as a
   "drive spin-down timeout" should be DISABLED or driver I-O requests may
   time out!   Also, be sure to use an 80-connector cable for any UltraDMA
   disk operating in "mode 3" ATA-44 (44 MB/sec) or higher.   When cabling
   a single disk to an IDE channel,  note that you MUST use both "ends" of
   the cable, NOT one "end" and the middle connector!   This avoids ERRORS
   as an unused cable-end CAN pick up "noise", like a RADIO antenna!


5. Error Reporting
   ---------------

   On exit from a successful I-O request, the AH-register is zero, and the
   carry flag is reset.   When an I-O error occurs, the carry flag is SET,
   and the AH-register contains an error return code, as follows:

	  Code 08h - DMA timed out.
	       0Fh - DMA error.
	       20h - Controller busy before I-O.
	       21h - Controller busy after I-O.
	       AAh - Disk not ready before I-O.
	       ABh - Disk not ready after I-O.
	       CCh - Disk FAULT before I-O.
	       CDh - Disk FAULT after I-O.
	       E0h - Hard error at I-O end.
	       FFh - XMS memory error.

   When XDMA output overlap is enabled, a run-time output error will cause
   the following message to be displayed, along with a short "beep" sound:

	  XDMA:  Output ERROR eeh Disk=d LBA=aaaaaaaaaaaah!

   where eeh is one of the return codes listed above, d is the disk number
   (0 for primary-master, 1 if primary-slave, 2 if secondary-master, and 3
   for secondary-slave), and aaaaaaaaaaaah is the starting disk address of
   the output request, shown as a 12-digit "logical block address".   XDMA
   handles only BIOS Int 13h calls (not DOS "file I-O"), so it is NOT told
   and cannot display the DOS file/directory for an output overlap error.


6. SPECIAL NOTES
   -------------

   The UMBPCI upper-memory driver (or similar) "creates" upper-memory from
   system "shadow RAM", which CANNOT do UltraDMA!   If UMBPCI loads before
   XDMA/XDMAJR, the BIOS continues to load more programs, and a "new" BIOS
   may use UltraDMA to load programs in upper-memory.    If this is UMBPCI
   "shadow RAM", doing UltraDMA there will cause a CRASH!!   To avoid this
   and support "new" UltraDMA BIOS programs, using UMBPCI with XDMA/XDMAJR
   requires the following RULES:
     A) XDMA/XDMAJR must load BEFORE UMBPCI so the drivers can "take over"
	  UltraDMA disk I-O from the BIOS.   Loading before UMBPCI ensures
	  XDMA/XDMAJR load in LOW memory (upper-memory is not created yet)
	  so their I-O "command lists" can be accessed properly using DMA.
     B) XDMA/XDMAJR must load with their /L switch, so they limit UltraDMA
	  to memory below 640K and avoid accessing "shadow RAM".
     C) XMS memory must be available, so an XMS "local buffer" can be used
	  to handle I-O requests unsuitable for UltraDMA.
     D) If CHS I-O is used, all disks must have valid CHS parameters.
   Rules (C) and (D) ensure that NO I-O is "passed" to the BIOS when using
   UMBPCI (the BIOS may use UltraDMA with "shadow RAM" and cause a CRASH)!
   Note that these rules are only "advisory".    Except as noted above for
   the /L switch, these rules are NOT enforced by driver logic and are the
   USER'S responsibility, if UMBPCI will be run with XDMA or XDMAJR!

   The EDD BIOS of some "notebooks" (IBM ThinkPad, etc.) or mainboards may
   NOT offer the "DPTE" data needed in scanning for UltraDMA disks to use!
   Starting in V1.7 XDMA and in V1.8 XDMAJR, if the EDD BIOS is missing or
   incomplete, or if no UltraDMA disks are seen when scanning with the EDD
   BIOS logic, a hardware-only disk scan will then be done.    XDMA/XDMAJR
   assume, in this case, that the BIOS has assigned DEFAULT "unit numbers"
   to each UltraDMA disk, as follows:
       A) Primary-master   disk must be BIOS "unit 80h".
       B) Primary-slave    disk (if present) must be BIOS "unit 81h".
       C) Secondary-master disk (if present) must be BIOS "unit 82h".
       D) Secondary-slave  disk (if present) must be BIOS "unit 83h".
   The default BIOS assignments occur ONLY if the UltraDMA disks have been
   "cabled" to the system in the above order, i.e., the first disk MUST be
   primary-master, second must be primary-slave, etc.   Other drives (ZIP,
   CD-ROM etc.) must use the remaining IDE positions or another controller
   so the BIOS "finds" all UltraDMA disks first!    If SCSI disks are also
   present, their controller BIOS (if any) must be DISABLED, so SCSI disks
   will not get BIOS "unit numbers".    This means an IDE disk must "boot"
   such systems.   The controller's DOS driver can be used after "boot" to
   access SCSI disks.    Note that if a complete EDD BIOS is present and a
   hardware-only scan is not needed, SCSI and IDE disks may be "cabled" to
   the system in ANY order, and a SCSI controller's BIOS can be enabled.

   Some CD-ROM "boot" programs handle the CD-ROM as a "fake" hard disk and
   provide incorrect EDD BIOS data for it!   In scanning for disks to use,
   the drivers may display "EDD BIOS error!  Unit ignored.", then continue
   to scan for more UltraDMA disks.   Users who did NOT "boot" from CD-ROM
   need to check what disk was passed-over and why.   Users who DID "boot"
   from a CD-ROM, where all UltraDMA disks were found properly, may IGNORE
   this message!    It is caused by an ERROR in the CD-ROM "boot" program,
   NOT by a problem with XDMA/XDMAJR or their disks!

   Some BIOS programs may NOT "configure" the mainboard UltraDMA chip when
   no IDE devices are found!   If no UltraDMA disks are found, the drivers
   usually display "No disk to use" and abort loading.   But they look for
   controller chips to use first, and an "unconfigured" chip may give "BAD
   UltraDMA controller", then an abort.    If the latter message displays,
   users must first verify that every UltraDMA hard-disk was made "active"
   through the BIOS set-up routines.    If this WAS done, "BAD controller"
   means the UltraDMA chip was NOT given both "Bus Master" and "I-O Space"
   command bits, and the BIOS needs to be UPDATED!

