ELKS XT MFM hard disk driver
============================

The CONFIG_BLK_DEV_MFMHD driver provides direct access to Xebec-style
command-block controllers used with ST-506/412 MFM hard disks in IBM PC/XT
class systems.  Supported profiles cover WD1002A-WX1-compatible controllers
and Seagate ST11M/ST11R or FileCard-class controllers.  It does not drive
IDE/ATA, ESDI, or generic RLL controllers; ST11R support is limited to the
documented Seagate command profile.

Hardware resources
------------------

One controller with up to two drives is supported.  The controller normally
occupies I/O ports 0x320 through 0x323; jumper W4 can select 0x324 instead
(set mfm= in /bootopts to match).

Command, status, sense, and controller-parameter bytes use programmed I/O.
Sector payloads use 8237 DMA channel 3, the standard IBM XT hard-disk DMA
channel.  The driver reserves a fixed 1024-byte buffer below the first 64 KiB
physical boundary, so an 8237 transfer cannot wrap.  Normal transfers are
therefore limited to two 512-byte sectors per command.  The controller IRQ is
kept masked and completion polled unless flag 8 asks for the interrupt; the
driver is synchronous either way.  DMA channel 3 must not be shared with
another active device.

Configuration
-------------

Enable "XT MFM hard drive support" under block device drivers and set the
controller profile.  The controller exposes /dev/mfma and /dev/mfmb;
partition minors follow each whole-disk minor.

The port, IRQ and flags come from "mfm=irq,port,,flags" in /bootopts, in the
form used by the ISA network and audio cards; the third field is the card RAM
and is unused here, but has to be present to reach the flags.  Trailing fields
may be left out and keep the MFM_ default from elks/include/arch/ports.h, so
"mfm=5,0x324" only moves the port.  "mfm=off" skips the driver entirely.

Less common tunables are source defines at the top of
elks/arch/i86/drivers/block/mfmhd.c rather than .config options:

  MFMHD_DRIVES          units to probe (default 2; must be 1 for the
                        FileCard 20 split-unit geometry)
  MFMHD_WD1002_BIOS     Super, G, or H controller-ROM geometry table
  MFMHD_STEP_CODE       WD1002/Xebec command step-rate code
  MFMHD_DRIVEn_*        fixed cylinder/head/sector geometry overrides;
                        zero uses the controller table, geometry command,
                        WD sector-0 values, or FAT BPB probing
  MFMHD_DIAG_IOCTLS     optional maintenance/diagnostic ioctls
  MFMHD_TRACE           command handshake tracing for bring-up

Standard MFM media normally uses 17 sectors per track.

Booting and recovery
--------------------

Use "root=mfma" (or mfmb) in /bootopts to mount a whole device, or use the
normal partition device name for a partition.  The flags field of "mfm=" is a
small bit mask:

  1   conservative controller deadlines
  2   sector payloads over programmed I/O instead of DMA channel 3
  4   driver request tracing to the console
  8   interrupt-driven command completion instead of polling the status
      port for the whole transfer
  16  8237 DMA controller Extended Write strobe

PIO is required on machines whose chipset does not service DRQ3 like a true
IBM XT (the Amstrad PC1512/PC1640 among them); the driver also switches itself
to PIO after a failed DMA transfer.  Extended Write is needed on machines such
as the Amstrad PC1512/1640 whose DMA write pulse is shorter than 8-bit cards
expect.  So "mfm=5,0x320,,18" polls over PIO with the strobe widened.  The
driver retries failed commands, recalibrates the affected unit, and falls back
to single-sector transfers after repeated errors.

Maintenance ioctls, including format and long-sector commands, are optional
and disabled by default.  Formatting destroys data and should be enabled only
for a dedicated maintenance build.
