   Fdutils Copyright (C) 1993-1999 Alain Knaff

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Printing current settings
-------------------------

`-T'
`--type'
     Print out the drive name of a floppy device. This is used by the
     `MAKEFLOPPIES' script. The drive name is a letter (describing the
     drive type) followed by the capacity of the format in bytes. The
     letter is E for 3.5 ED drives, H for 3.5 HD drives, D for 3.5 DD
     drives, h for 5.25 HD drives and d for 5.25 DD drives. The drive
     type letter corresponds to the oldest drive type supporting the
     format of this device node (not necessarily the type of the drive
     refered by this node.)  For the generic format nodes (/dev/fd0 et
     al.)  the name of "native format" of the drive is printed, and for
     the default formats, if a generic format has been redefined, its
     name becomes `(null)'.

`-p'
`--print'
     Prints out the configuration of the drive. The names of the various
     fields are the same as the names of the option to set them, see
     below.

`-P'
`--printstate'
     Prints out the cached internal state of the driver. The first line
     lists various attributes about the disk:
    `drive present'
    `disk present'
    `disk writable'
          These are only updated when the drive is accessed.

    `spinup'
          is the time when the motor became switched on for the last
          time.

    `select'
          is the time when the drive became selected for the last time

    `first_read'
          is the time when the first read request after the last spin up
          completed.

    `probed_fmt'
          is the the index of the autodetected format in the
          autodetection sequence for this drive.

    `cylinder'
          is the cylinder where the drive head currently sits.  If this
          number is negative, it has the following meaning:
             * -1 means that the driver doesn't know, but the
               controller does (a seek command must be issued).

             * -2 means that the controller doesn't know either, but is
               sure that it not beyond the 80th track.  The drive needs
               a recalibration.

             * -3 means that the head may be beyond the 80th track.
               The drive needs two successive recalibrations, because
               at each recalibration, the controller only issues 80
               move head commands per recalibration.

    `maxblock'
          is the highest block number that has been read.

    `maxcylinder'
          is a boolean which is set when a sector that is not on
          cylinder 0/head 0 has been read.  These are used for smart
          invalidation of the buffer cache on geometry change.  The
          buffer cache of the drive is only invalidated on geometry
          change when this change actually implies that a block that
          has already been read changes position. This optimization is
          useful for mtools which changes the geometry after reading
          the boot sector.

    `generation'
          is roughly the number of disk changes noticed since boot.
          Disk changes are noticed if the disk is actually changed, or
          if a flush command is issued and for both cases if any I/O
          to/from the disk occurs. (i.e. if you insert several disks,
          but don't do any I/O to them, the generation number stays the
          same.)

    `refs'
          is number of open file descriptors for this drive. It is
          always at least one, because floppycontrol's file descriptor
          is counted too.

    `device'
          is format type (as derived from the minor device number)
          which is currently being used.

    `last_checked'
          is date (in jiffies) when the drive was last checked for a
          disk change, and a disk was actually in the drive.

`--pollstate'
     Polls the drive and then prints out the internal state of the
     driver.(`--Printstate' only prints out the cached information
     without actually polling the drive for a disk change.)

`--printfdcstate'
     Prints out the state of the controller where the target drive is
     attached to.
    `spec1'
    `spec2'
          are the current values of those registers.

    `rate'
          is current data transfer rate

    `rawcmd'
          is true if a raw command has been executed since the last
          reset. If this is the case, a reset will be triggered when a
          drive on the same FDC is next opened.

    `dor'
          is the value of the digital output register. The 4 high bits
          are a bit mask describing which drives are spinning, the 2
          low bits describe the selected drive, bit 2 is used to reset
          the FDC, and bit 3 describes whether this FDC has hold of the
          interrupt and the DMA. If you have two FDCs, bit 3 is only
          set on one of them.

    `version'
          is the version of the FDC. See `linux/include/linux/fdreg.h'
          for a listing of the FDC version numbers.

    `reset'
          is true if a reset needs to be issued to the FDC before
          processing the next request.

    `need_configure'
          is true if this FDC needs configuration by the `FD_CONFIGURE'
          command.

    `has_fifo'
          is set if the FDC understands the `FD_CONFIGURE' command.

    `perp_mode'
          describes the perpendicular mode of this FDC. 0 is
          non-perpendicular mode, 2 is HD perpendicular mode, 3 is ED
          perpendicular mode, and 1 is unknown.

    `address'
          is the address of the first I/O port of the FDC.  Normally,
          this is 0x3f0 for the first FDC and 0x370 for the second.

Drive type configuration and autodetection
------------------------------------------

   The following options handle the different available drive types,
such as double density vs. high density vs. extra density drives, and 5
1/4 drives vs 3 1/2 drives.  Usually the drive type is stored in a
non-volatile memory, called CMOS, under the form of an integer ranging
from 1 to 6.

   Different drive types are able to handle and autodetect different
formats (different autodetection lists). They also have different
"native format name". The native format is the "usual" format with the
highest capacity supported by the drive. (For example 720KB on a double
density 3 1/2 drive, and 1.2MB on a high density 5 1/4 drive.)

   These settings are only changeable by the super user.

`-c CMOS-TYPE'
`--cmos  CMOS-TYPE'
     Set the virtual CMOS type of the floppy drive. This is useful if
        * the physical CMOS type is wrong (this may happen with BIOSes
          which use a non-standard mapping),

        * you have more than two drives (the physical CMOS may only
          describe up to two drives).

        * you have a BIOS that allows swapping drives A: and B: for DOS.

     Right now, this CMOS parameter is not used by the kernel, except
     for feeding it back to other applications (for instance
     `superformat', `floppymeter' or `MAKEFLOPPIES').  It is also
     possible to supply a virtual CMOS type with the `cmos' boot option
     (see Boottime configuration).  If possible, I recommend you
     use the boot option, rather than `floppycontrol', because the boot
     option also sets any parameters derived from the CMOS type, such
     as the autodetection list and the native format, whereas
     `floppycontrol' does not.

`-A  AUTODETECT-SEQ'
`--autodetect  AUTODETECT-SEQ'
     Set the autodetection sequence (see Autodetection) The
     autodetection sequence is a comma-separated list of at most eight
     format descriptors. Each format descriptor is a format number
     optionally followed by the letter `t'.  For drive 0, the format
     number is the minor device number divided by 4.  The autodetection
     sequence is used by the driver to find out the format of a newly
     inserted disk. The formats are tried one after the other, and the
     first matching format is retained. To test the format, the driver
     tries to read the first sector on the first track on the first
     head when `t' is not given, or the whole first track when `t' is
     given. Thus, autodetection cannot detect the number of tracks.
     However, this information is contained in the boot sector, which
     is now accessible. The boot sector can then be used by mtools to
     configure the correct number of tracks.

     Example:
          7,4,24t,25
     means to try out the formats whose minor device numbers are 28
     (1.44M), 16 (720KB), 96 (1.76MB), and 100 (1.92MB), in this order.
     For the 1.76MB format, try to read the whole track at once.

     Reading the whole track at once allows you to distinguish between
     two formats which differ only in the number of sectors. (The
     format with the most sectors must be tried first.)  If you use
     mtools(1), you do not need this feature, as mtools can figure out
     the number of sectors without any help from the floppy driver, by
     looking at the boot sector.

     Reading the whole track at once may also speed up the first read
     by 200 milliseconds. However, if, on the other hand, you try to
     read a disk which has less sectors than the format, you lose some
     time.

     I suggest that you put the most often used format in the first
     place (barring other constraints), as each format that is tried
     out takes 400 milliseconds.

`-n NATIVE-FORMAT'
`--native_format  NATIVE-FORMAT'
     Set the native format of this drive. The native format of a drive
     is the highest standard format available for this drive. (Example:
     For a 5 1/4 HD drive it is the usual 1200K format.) This is format
     is used to make up the format name for the generic device (which
     is the name of the native format). This drive name is read back
     from the kernel by the `MAKEFLOPPIES' script which uses it to
     decide which device nodes to create.

   ---------- Footnotes ----------

   (1) Version 3.0 or higher

Configuration of the disk change line
-------------------------------------

`--broken_dcl'
     Assumes that the disk change line of the drive is broken.  If this
     is set, disk changes are assumed to happen whenever the device
     node is first opened. The physical disk change line is ignored.

     This option should be used if disk changes are either not detected
     at all, or if disk changes are detected when the disk was actually
     not changed.  If this option fixes the problem, I'd recommend that
     you try to trace the root cause of the problem.  Indeed, this
     options results in reduced performance due to spurious cache
     flushes.

     The following hardware problems may lead to a bad disk change line:
        * If the floppy cable is not inserted straight, or if it is
          kinked, the disk change line is likely to suffer, as it is on
          the edge of the cable.  Gently press on both connectors of
          the cable (drive and controller) to insure that all wires
          make contact.  Visually inspect the cable, and if it shows
          obvious traces of damage, get a new one.

        * On some drives, the locations disk change line may be chosen
          by jumper. Make sure that your floppy controller and your
          drive agree on which line is the disk change line.

        * Some older drives (mostly double density 5 1/4 drives) don't
          have a disk change line.  In this case, you have no choice
          other than to leave the `broken_dcl' option on.

`--working_dcl'
     Assumes that the disk change line works all right. Switching from
     broken to working may lead to unexpected results after the first
     disk change.

`--inverted_dcl'
     Assumes that this disk drive uses an inverted disk change line.
     Apparently this is the case for IBM thinkpads.

`--no_inverted_dcl'
     Assumes that this drive follows the standard convention for the
     disk change line.

`--noisy_dcl_clear'
     Switches off silent disk change line clearing for this drive.

Timing Parameters
-----------------

   This section describes how to configure drive timings.  To set these
parameters, you need superuser privileges. All times are in "jiffy"
units (10 milliseconds), unless otherwise specified.

`--hlt  HLT'
     Set the head load time (in microseconds) for this floppy drive.
     The head load time describes how long the floppy controller waits
     after seeking or changing heads before allowing access to a track.

`--hut  HUT'
     Set the head unload time (in microseconds) for this floppy drive.
     The head unload time describes how long the floppy controller
     waits after an access before directing its attention to the other
     head, or before seeking.

`--srt  SRT'
     Set the step rate (in microseconds) for this floppy drive.  The
     step rate describes how long the drive head stays on one cylinder
     when seeking.  Setting this value to low (too fast seeks) may make
     seeks fail, because the motor doesn't follow fast enough.

`-u SPINUP-TIME'
`--spinup  SPINUP-TIME'
     Set the spinup time of the floppy drive. In order to do read or
     write to the floppy disk, it must spin. It takes a certain time
     for the motor to reach enough speed to read or write. This
     parameter describes this time. The floppy driver doesn't try to
     access the drive before the spinup time has elapsed. With modern
     controllers, you may set this time to zero, as the controller
     itself enforces the right delay.

`-o SPINDOWN-TIME'
`--spindown  SPINDOWN-TIME'
     Set the spindown time of this floppy drive. The motor is not
     stopped immediately after the operation completes, because there
     might be more operations following. The spindown time is the time
     the driver waits before switching off the motor.

`-O SPINDOWN-OFFSET'
`--spindown_offset  SPINDOWN-OFFSET'
     Set the spindown offset of this floppy drive. This parameter is
     used to set the position in which the disk stops. This is useful to
     minimize the next access time. (If the first sector is just near
     the head at the very moment at which the disk has reached enough
     speed, you win 200 milliseconds against the most unfavorable
     situation).

     This is done by clocking the time where the first I/O request
     completes, and using this time to calculate the current position of
     the disk.

`-s SELECT-DELAY'
`--select_delay  SELECT-DELAY'
     Set the SELECT DELAY of this floppy drive. This is the delay that
     the driver waits after selecting the drive and issuing the first
     command to it. For modern controllers/drives, you may set this to
     zero.

`-C CHECK-INTERVAL'
`--checkfreq  CHECK-INTERVAL'
     Set the maximal disk change check interval.  The disk change line
     is checked whenever a read or write to the device is issued, and
     it has not been checked for more than INTERVAL jiffies.

Debugging messages
------------------

   This subsection describes how to switch the available debugging
messages on and off.

`--debug'
     Switch debugging output on. The debugging information includes
     timing information. This option might be useful to fine-tune the
     timing options for your local setups. (But for most normal
     purposes, the default values are good enough.)

`--nodebug'
     Switch debugging output off.

`--messages'
     Print informational messages after autodetection, geometry
     parameter clearing and dma over/underruns.

`--nomessages'
     Don't print informational messages after these events.

Error Handling Options
----------------------

   The following options configure the behavior of the floppy driver in
case of read/write errors. They may be used by any user who has write
privileges for the drive. Whenever the floppy driver encounters an
error, a retry counter is incremented. If the value of this counter gets
bigger than the thresholds described below, the corresponding actions
are performed at the next retry. The counter is reset when the read or
write finally terminates, whether successfully or not.
`-a OPERATION-ABORT-TRSHLD'
`--abort  OPERATION-ABORT-TRSHLD'
     Tell the floppy driver to stop trying to read/write a sector after
     OPERATION-ABORT-TRSHLD retries, and signal the I/O error to the
     user.

`-t READ-TRACK-TRSHLD'
`--readtrack  READ-TRACK-TRSHLD'
     Tell the floppy driver to switch from track-reading mode to
     sector-at-a-time-mode after READ-TRACK-TRSHLD retries.

`-r RECALIBRATE-TRSHLD'
`--recalibrate  RECALIBRATE-TRSHLD'
     Tell the floppy driver to recalibrate the drive after
     RECALIBRATE-TRSHLD retries.

`-R RESET-TRESHOLD'
`--reset  RESET-THRESHOLD'
     Tell the floppy driver to reset the controller after
     RESET-THRESHOLD retries. After a controller reset, the floppy
     driver also recalibrates all drives connected to that controller.

`-e ERROR-REPORT-TRSHLD'
`--reporting  ERROR-REPORT-TRSHLD'
     Tell the floppy driver to start printing error messages to the
     console after ERROR-REPORT-TRSHLD retries.

Write error reporting
---------------------

   Due to the buffer cache, write errors cannot always be reported to
the writing user program as soon as the write system call returns.
Indeed, the actual writing may take place much later. If a write error
is encountered, the floppy driver stores information about it in its per
drive write error structure.  This write error structure stays until
explicitly cleared.  It can for example be queried by a backup program
which wants to make sure that the data has been written successfully.

`--clrwerror'
     Clears the write error structure.

`--printwerror'
     Prints the contents of the write error structure:
    `write_errors'
          is a count of how many write errors have occurred since the
          structure was last cleared.

    `badness'
          is the maximal number of retries that were needed to complete
          an operation (reads, writes and formats).

    `first_error_sector'
          is where the first (chronologically) write error occurred.

    `first_error_generation'
          is the disk change generation in which did the first write
          error occurred.  The disk change generation is a number which
          is incremented at each disk change.

    `last_error_sector'
          and

    `last_error_generation'
          are similar.

Other drive configuration options
---------------------------------

   This subsection lists per drive configuration options, which don't
fit in any other category.  They are available only to the superuser:

`--tracks  MAX-TRACKS'
     Set the maximal numbers of physical tracks that this drive may
     handle. If you have a drive which is only able to handle 80 tracks
     (making strange noises when you try to format or read a disk with
     more than 80 tracks), use this option to prevent unprivileged
     users of damaging your drive by repeatedly reading disks with more
     than 80 tracks.

     If you trust your users and your disks, you don't need this. With
     most drives you don't need to worry anyways. See More cylinders
     for details.

`-i SECTOR-INTERLEAVE'
`--interleave SECTOR-INTERLEAVE'
     Set the number of sectors beyond which sector interleaving will be
     used.  This option will only be used by the `FDFMTTRK' ioctl.  The
     `fdformat' command, which is now considered obsolete, uses
     `FDFMTTRK' ioctl, but `superformat' does not.

floppymeter
===========

     `floppymeter' [`-f'] [`-w' WARMUP-DELAY] [`-W' WINDOW]
     [`-c' CYCLES] [`-h'] DRIVE

   The `floppymeter' program measures characteristic parameters of a
floppy drive and floppy controller, such as the rotation speed of the
drive, the data transfer rate of the controller, and the resulting raw
capacity of a disk track.  To use this program, insert a disposable
floppy in the drive, and type `floppymeter --'DENSITY, where density
describes the density of the disk used for the test. (Should be one of
`dd, hd' or `ed'). *CAUTION: the data on the disk will be erased*.
This program should be used to verify whether the drive and controller
are out of tolerance if you experience problems with some high capacity
formats.  It only needs to be run once per drive: although a disk is
needed to perform the measurements, the measured data only depend on
the drive and the controller, and not on the disk.

   To measure the raw capacity of the disk track, the floppymeter
program formats the first track of the drive in a special way that
allows it to read the raw data (gaps and headers) of the disk. *Thus,
all data previously stored on that disk is lost*.

   The rotation speed is measured by timing the return time of a
`readid' command.  In order to gain more precision, the command is
issued many times in a row. During this phase, the number of rotations
til the start of the test, the average time per rotation til the start,
and a sliding average of the times of the last 30 rotations is printed,
and updated continously.

   The data transfer rate is deduced from the two parameters above.

   At the end of the program, all parameters (raw capacity, duration of
one rotation, and data transfer rate) are printed again, as well as
their relative deviation to the standard value.  Finally, it suggests a
capacity deviation description line, which can be directly pasted into
the drive definition file (see Drive descriptions).

   Usually, the data transfer rate should not deviate more than 150 ppm
from the expected value, and the rotation speed of the drive should not
deviate more than 3000 ppm from the expected value.  If these deviations
are bigger, you may get problems with certain high capacity formats.

   If the raw capacity of the drive is too small, some high capacity
formats may become unformattable on this drive/controller combo.

   If on the other hand, the raw capacity of the drive is too big, you
may get problems when writing to a disk formatted by this drive on
another drive with a smaller raw capacity. In order to avoid this,
increase superformats gap parameter (`-G').

`-h'
     Prints a short help

`--dd'
     Tells the program that we use a Double Density disk.

`--hd'
     Tells the program that we use a High Density disk.

`--ed'
     Tells the program that we use an Extra Density disk.

`-f'
     Runs the measurement non interactively.  With this option, the
     program doesn't ask for confirmation, and doesn't display the
     continously updated values during the rotation speed measurement.

`-W WINDOW'
     This value describes how many rotations are used for the
     computation of the sliding average. Default is 30.

`-c CYCLES'
     Describes the number of rotations clocked during the rotations
     speed determination test. Default is 1000.

Bugs
----

   This program is quite new, and may have bugs. Here are a few
suggested tests to check its sanity:
   * The deviation of the data transfer rate solely depends on the
     controller. It should not be different between two drives
     connected to the same controller. However, the drive rotation
     speed may be different for different drives.

   * All data transfer rates (for double, high and extra density) are
     derived from a same master frequency. Thus the _deviation_ of the
     data transfer rate should be independant of the density used.

getfdprm
========

     `getfdprm' [DRIVE]

   `getfdprm' prints the current geometry information for DRIVE .  This
information can be set using `setfdprm'

makefloppies
============

     `MAKEFLOPPIES' [`-tlvng'] [DRIVES]

   The `MAKEFLOPPIES' shell script creates the new floppy block device
node.  It uses the floppycontrol program to translate the minor device
numbers into meaningful names. It also uses these names to decide
whether to create a given block device file or not, depending on the
type of the physical drive (for instance, for a 3 1/2 drive, the formats
corresponding to a 5 1/4 drive are not created).

   If you have more than two floppy drives, you need to tell the kernel
the CMOS types of those additional drives using the
`floppy='DRIVE`,'TYPE`,cmos' lilo option.

   If the DRIVES  parameter is given, only the device nodes for the
listed drives are made. By default, all only the two first drives are
tried.

   `MAKEFLOPPIES' does not work if you redefine your default formats.

   *Caution*: `MAKEFLOPPIES' removes already existing floppy device
nodes.

Options
-------

`-t'
     Use the old naming convention for 3 1/2 devices (e.g. `fd0H720'
     instead of `fd0u720').

`-m'
     Base the name for the created devices on the type of the media
     (e.g. `fd0h720' instead of `fd0u720').

`-l'
     Local. Creates device nodes in the local directory, not /dev

`-v'
     Verbose

`-n'
     Dry run. (just report what would be done, do not do anything)

`-g'
     Group.  Allow read/write access to floppy devices only for group
     `floppy'

Bugs
----

   The Makefloppies script does not work on redefined "default"
formats, If you redefine default formats, you need to create the needed
device nodes manually.

setfdprm
========

     `setfdprm' [`-p'] DEVICE MEDIA-DESCRIPTION

     `setfdprm' [`-c' | `-y' | `-n'] DEVICE

   `setfdprm' is a utility that can be used to load disk parameters
into the auto-detecting floppy devices and "fixed parameter" floppy
devices, to clear old parameter sets and to disable or enable diagnostic
messages.  These parameters are derived from a media-description, see
Media description for more details.

   Without any options, `setfdprm' loads the DEVICE (for example
`/dev/fd0' or `/dev/fd1') with a new parameter set with the NAME entry
found in `/etc/fdprm' (usually named 360/360, etc.).  For autodetecting
floppy devices, these parameters stay in effect until the media is
changed. For "fixed parameter" devices, they stay in effect until they
are changed again.

   `Setfdprm' can also be used by the superuser to redefine the default
formats.

Options
-------

`-p DEVICE NAME'
     Permanently loads a new parameter set for the specified
     auto-configuring floppy device for the configuration with NAME in
     `/etc/fdprm'. Alternatively, the parameters can be given directly
     from the command line.

`-c DEVICE'
     Clears the parameter set of the specified auto-configuring floppy
     device.

`-y DEVICE'
     Enables format detection messages for the specified
     auto-configuring floppy device.

`-n DEVICE'
     Disables format detection messages for the specified
     auto-configuring floppy device.

Bugs
----

   This documentation is grossly incomplete.

superformat
===========

     `superformat' [`-D' DOS-DRIVE] [`-v' VERBOSITY-LEVEL] [`-b' BEGIN-TRACK]
     [`-e' END-TRACK] [`--superverify'] [`--dosverify']
     [`--noverify'] [`--verify_later']
     [`-G' FORMAT-GAP] [`-F' FINAL-GAP] [`-i' INTERLEAVE] [`-c' CHUNKSIZE]
     [`-g' GAP] [`--absolute-skew' ABSOLUTE-SKEW] [`--head-skew' HEAD-SKEW]
     [`--track-skew' TRACK-SKEW] [`--biggest-last'] DRIVE [MEDIA-DESCRIPTION]

   `superformat' is used to format disks with a capacity of up to 1992K
HD or 3984K ED.  See Extended formats for a detailed description of
these formats. See Media description for a detailed description of
the syntax for the media description.  If no media description is
given, superformat formats a disk in the highest available density for
that drive, using standard parameters (i.e. no extra capacity formats).

   When the disk is formatted, `superformat' automatically invokes
`mformat' in order to put an MS-DOS filesystem on it. You may ignore
this filesystem, if you don't need it.

   Supeformat allows to format 2m formats.  Be aware, however, that
these `2m' formats were specifically designed to hold an MS-DOS
filesystem, and that they take advantage of the fact that the MS-DOS
filesystem uses redundant sectors on the first track (the FAT, which is
represented twice). The second copy of the FAT is _not_ represented on
the disk.

   High capacity formats are sensitive to the exact rotation speed of
the drive and the resulting difference in raw capacity.  That's why
`superformat' performs a measurement of the disks raw capacity before
proceeding with the formatting.  This measurement is rather time
consuming, and can be avoided by storing the relative deviation of the
drive capacity into the drive definition file file. See Drive descriptions
for more details on this file. The line to be inserted
into the drive definition file is printed by superformat after
performing its measurement.  However, this line depends on the drive and
the controller.  Do not copy it to other computers.  Remove it before
installing another drive or upgrade your floppy controller.  Swap the
drive numbers if you swap the drives in your computer.

Common Options
--------------

   Many options have a long and a short form.

`-h'
`--help'
     Print the help.

`-D DRIVE'
`--dosdrive DOS-DRIVE'
     Selects DOS drive letter for `mformat' (for example `a:' or `b:').
     The colon may be omitted.  The default is derived from the minor
     device number.  If the drive letter cannot be guessed, and is not
     given on the command line, `mformat' is skipped.

`-v VERBOSITY-LEVEL'
`--verbosity VERBOSITY-LEVEL'
     Sets the verbosity level. 1 prints a dot for each formatted track.
     2 prints a changing sign for each formatted track (- for
     formatting the first head, = for formatting the second head, x for
     verifying the first head, and + for verifying the second head). 3
     prints a complete line listing head and track. 6 and 9 print
     debugging information.

`--superverify'
     Verifies the disk by first reading the track, than writing a
     pattern of U's, and then reading it again.  This is useful as some
     errors only show up after the disk has once been written.
     However, this is also slower.

`-B'
`--dosverify'
     Verifies the disk using the `mbadblocks' program.  `mbadblocks'
     marks the bad sectors as bad in the FAT.  The advantage of this is
     that disks which are only partially bad can still be used for
     MS-DOS filesystems.

`-V'
`--verify_later'
     Verifies the whole disk at the end of the formatting process
     instead of at each track. Verifying the disk at each track has the
     advantage of detecting errors early on.

`-f'
`--noverify'
     Skips the verification altogether.

Advanced Options
----------------

   Usually, superformat uses sensible default values for these options,
which you normally don't need to override.  They are intended for expert
users.  Most of them should only be needed in cases where the hardware
or superformat itself has bugs.

`-b BEGIN-TRACK'
`--begin_track  BEGIN-TRACK'
     Describes the track where to begin formatting.  This is useful if
     the previous formatting failed halfway through.  The default is 0.

`-e END-TRACK'
`--end_track END-TRACK'
     Describes where to stop formatting. END_TRACK is the last track to
     be formatted plus one. This is mainly useful for testing purposes.
     By default, this is the same as the total number of tracks.  When
     the formatting stops, the final skew is displayed (to be used as
     absolute skew when you'll continue).

`-S SIZECODE'
`--sizecode SIZECODE'
     Set the sector size to be used. The sector size is 128 * (2 ^
     SIZECODE).  Sector sizes below 512 bytes are not supported, thus
     sizecode must be at least 2. By default 512 is assumed, unless you
     ask for more sectors than would fit with 512 bytes.

`--stretch STRETCH'
     Set the stretch factor. The stretch factor describes how many
     physical tracks to skip to get to the next logical track (2 ^
     STRETCH).  On double density 5 1/4 disks, the tracks are further
     apart from each other.

`-G FMT-GAP'
`--format_gap FMT-GAP'
     Set the formatting gap. The formatting gap tells how far the
     sectors are away from each other. By default, this is chosen so as
     to evenly distribute the sectors along the track.

`-F FINAL-GAP'
`--final_gap FINAL-GAP'
     Set the formatting gap to be used after the last sector.

`-i INTERLEAVE'
`--interleave INTERLEAVE'
     Set the sector interleave factor.

`-c CHUNKSIZE'
`--chunksize CHUNKSIZE'
     Set the size of the chunks. The chunks are small auxiliary sectors
     used during formatting. They are used to handle heterogeneous
     sector sizes (i.e. not all sectors have the same size) and negative
     formatting gaps.

`--biggest-last'
     For MSS formats, make sure that the biggest sector is last on the
     track.  This makes the format more reliable on drives which are
     out of spec.

Sector skewing options
----------------------

   In order to maximize the user data transfer rate, the sectors are
arranged in such a way that sector 1 of the new track/head comes under
the head at the very moment when the drive is ready to read from that
track, after having read the previous track. Thus the first sector of
the second track is not necessarily near the first sector of the first
track.  The skew value describes for each track how far sector number 1
is away from the index mark. This skew value changes for each head and
track. The amount of this change depends on how fast the disk spins,
and on how much time is needed to change the head or the track.

`--absolute_skew ABSOLUTE-SKEW'
     Set the absolute skew. (The skew value used for the first formatted
     track)

`--head_skew HEAD-SKEW'
     Set the head skew. (The skew added for passing from head 0 to head
     1)

`--track_skew TRACK-SKEW'
     Set the track skew. (The skew added for seeking to the next track)

   Example: (absolute skew=3, head skew=1, track skew=2)

     track 0 head 0: 4,5,6,1,2,3	(skew=3)
     track 0 head 1: 3,4,5,6,1,2	(skew=4)

     track 1 head 0: 1,2,3,4,5,6	(skew=0)
     track 1 head 1: 6,1,2,3,4,5	(skew=1)

     track 2 head 0: 4,5,6,1,2,3	(skew=3)
     track 2 head 1: 3,4,5,6,1,2	(skew=4)

Examples
--------

   In all the examples of this section, we assume that drive 0 is a 3
1/2 and drive 1 a 5 1/4.

   The following example shows how to format a 1440K disk in drive 0:
     superformat /dev/fd0 hd

   The following example shows how to format a 1200K disk in drive 1:
     superformat /dev/fd1 hd

   The following example shows how to format a 1440K disk in drive 1:
     superformat /dev/fd1 hd sect=18

   The following example shows how to format a 720K disk in drive 0:
     superformat /dev/fd0 dd

   The following example shows how to format a 1743K disk in drive 0 (83
cylinders times 21 sectors):
     superformat /dev/fd0 sect=21 cyl=83

   The following example shows how to format a 1992K disk in drive 0 (83
cylinders times 2 heads times 12 KB per track)
     superformat /dev/fd0 tracksize=12KB cyl=83 mss

   The following example shows how to format a 1840K disk in drive 0. It
will have 5 2048-byte sectors, one 1024-byte sector, and one 512-byte
sector per track:
     superformat /dev/fd0 tracksize=23b mss 2m ssize=2KB

   All these formats can be autodetected by mtools, using the floppy
driver's default settings.

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

`FDC busy, sleeping for a second'
     When another program accesses a disk drive on the same controller
     as the one being formatted, `superformat' has to wait until the
     other access is finished.  If this happens, check whether any
     other program accesses a drive (or whether a drive is mounted),
     kill that program (or unmount the drive), and the format should
     proceed normally.

`I/O errors during verification'
     Your drive may be too far out of tolerance, and you may thus need
     to supply a margin parameter.  Run `floppymeter' (see
     floppymeter) to find out an appropriate value for this
     parameter, and add the suggested `margin' parameter to the command
     line

Bugs
----

   Opening up new window while `superformat' is running produces
overrun errors. These errors are benign, as the failed operation is
automatically retried until it succeeds.

xdfcopy
=======

     `xdfcopy' [`-'FORMAT-ID] [`-d'] [`-n'] [`-h' HEAD-SKEW] [`-t' CYLINDER-SKEW] [`-T'
     END-CYLINDER] [SOURCE] TARGET

   `Xdfcopy' is a utility to copy and format XDF disks. XDF (eXtended
Density Format) is a format used by OS/2 which can hold 1840KB of data
(on a 3 1/2 high density disk). Its advantage over 2m formats is that it
is faster: 38KB/s. Because of this fast speed, I extended the XDF
standard to higher capacities (1992KB) with a transfer rate of 45KB/s. I
called the new formats XXDF.

   This program works best with kernels newer than 2.0.0.

   If both source and target are given, xdfcopy copies the disk image
from file to floppy disk or vice-versa. When copying to a floppy disk,
the disk is first formatted, unless the `-n' option is given.

   If no source is given, the target is only formatted. In this case,
the target must be a floppy drive.

Options
-------

Selecting a format
..................

   Formats are selected by the format_id. The following formats are
understood:

`0'
     Formats a 5 1/4 XDF disk (1520 KB, 45.6 KB/s).

`1'
     Formats a 3 1/2 high density XDF disk (1840 KB, 38.3 KB/s).

`2'
     Formats a 3 1/2 extra density XDF disk (3680 KB, 102 KB/s)

`3'
     Formats a 3 1/2 high density XXDF disk (1920 KB, 45 KB/s)

`4'
     Formats a 3 1/2 extra density XXDF disk (3840 KB, 90 KB/s)

Misc options
------------

`-D DOSDRIVE'
     Describes the DOS drive letter for mformat. If this option is
     given, an MS-DOS filesystem is automatically installed on the disk
     after the low-level format is complete. In order for this to work,
     the drive has to be configured to accept the 23x2x80 geometry in
     your /etc/mtools or your ~/.mtoolsrc file. Moreover, this only
     works with a version of mtools that is more recent than 3.0.

     Example of a working mtoolsrc line:
          A /dev/fd0  0  0 0  0

     Examples of a non-working mtoolsrc line:
          A /dev/fd0 12 80 2 18

`-n'
     Don't format the disk before copying the disk image to the disk.

Options for power users
-----------------------

`-t CYLINDER SKEW'
     Uses a different track skew than the default (14). For more
     details on skews, see superformat. In this version of xdfcopy,
     the `-t' parameter is ignored.

`-h HEAD SKEW'
     Uses a different head skew than the default (0) In this version,
     this parameter is ignored

`-d'
     Debugging. For each read or write operation, the time it took to
     complete the operation is printed (in milliseconds). This can be
     used to optimize the skews.

`-T END-CYLINDERS'
     Tells how many cylinders to format.  With the XXDF formats, it is
     actually possible to format up to 83 cylinders, yielding a format
     of up to 1992KB on a 3 1/2 high density disk.

Compile-time configuration via GNU autoconf
*******************************************

   Before it can be compiled, fdutils must be configured using the GNU
autoconf script `./configure'.  In most circumstances, running
`./configure' without any parameters is enough. However, you may
customize fdutils using various options to `./configure'. The following
options are supported:
`--prefix DIRECTORY'
     Prefix used for any directories used by fdutils.  By default, this
     is `/usr/local'.  Fdutils is installed in `$prefix/lib', looks for
     its system wide configuration file in `$prefix/etc'.  Man pages are
     installed in `$prefix/man', info pages in `$prefix/info' etc.

`--sysconfdir DIRECTORY'
     Directory containing the system-wide configuration files such as
     `mediaprm' and `driveprm'.  By default, this is derived from
     `prefix' (see above).  N.B. For backward compatibility reasons, the
     old-style floppy parameter file `fdprm' is always in `/etc',
     regardless of the setting for `sysconfdir'

`--enable-fdmount-floppy-only'
     Allows usage of the `fdmount' program only to members of the group
     `floppy'

   In addition to the above-listed options, the other standard GNU
autoconf options apply.  Type `./configure --help' to get a complete
list of these.

Acronyms
********

_SD (Single density)_
     Single density disks use a data transfer rate of 125 kb/s and are
     no longer in use today, because of their low capacity.

_DD (Double density)_
     Double density disks normally hold 360KB (5 1/4) or 720KB (3 1/2)
     of data per disk.

     Double density disks have only a hole on one side (for write
     protection).

     Double density uses a data transfer rate of 250 kb/s or 300 kb/s
     depending on the drive type: 5 1/4 high density drives use 300
     kb/s when writing to a double density diskm 250 kb/s is used in
     all other circumstances. The reason why double density disks in
     high density drives need a higher data transfer rate is because
     these drives rotate faster (360 rpm instead of 300 rpm).

_HD (High density)_
     High density disks normally hold 1200KB (5 1/4) or 1440KB (3 1/2)
     of data per disk.  High density 3 1/2 disks are marked as such by
     the presence of a second square hole, just opposed to the write
     protect hole.  3 1/2 high density disks are the most commonly used
     type of disks today.

_QD (Quad density)_
     Quad density is a hybrid between double and high density.  It only
     exists for 5 1/4 disks, and holds 720KB of data.  It can be
     obtained by formatting DD disks in a HD drive.  QD uses double
     density for the density along the tracks (data transfer rate), and
     high density for the density perpendicular to the tracks (spacing
     between tracks, and thus number of tracks).  This came to
     existence because these two aspects are limited by two different
     factors: the density along the track is limited by the quality of
     the media, whereas the density perpendicular to the tracks is
     mainly limited by the drive mechanism (this density, expressed in
     bits per inch comes nowhere near the limits of the media, even with
     HD).  Thus quad density is an easy way to double the capacity of an
     ordinary double density disk, just by formatting it in a HD drive.

_ED (Extra density)_
     Extra density refers to a disk density that can normally hold
     2880KB of data per disk.  Extra density disks only exist as 3 1/2
     disks.  ED disks are marked with a second squared hole opposed to
     the square hole, which is a little bit closer to the middle of the
     edge than that of HD disks.  This format never really took off,
     because it only was released when storage media with a much higher
     capacity, such as CD-Roms, tapes and Zip disks became popular.

     ED uses a data transfer rate of 250 kb/s.

_DS (Double sided)_
     Self explanatory.

_SS (Single sided)_
     Self explanatory

_MSS (Mixed size sectors)_
     Mixed sector size formats are formats which use sectors of several
     different sizes on a single track. See Mixed size sectors for
     details.

_2M (2 Megabytes)_
     2M is a high capacity format developped by Ciriaco de Celis.  The
     basic principle is the same as MSS: mix sectors of several sizes
     on a same track, in order to minimize both slack space and header
     overhead.  2M is different from MSS in that it uses a normal 18
     sector format on its first track. See 2M for details.

_rpm (Rotations per minute)_
     All 3 1/2 drives and 5 1/4 DD drives run at 300 rotations per
     minute, whereas 5 1/4 HD drives run at 360 rotations per minute.

_rps (Rotations per second)_
     See above.

_tpi (tracks per inch)_
     Expresses how close cylinders are to each other.  Usually, 5 1/4
     double density disks have 48 tpi, whereas 5 1/4 high density and
     quad density disks have 96 tpi.  3 1/2 disks use 135.5 tpi.

_XDF (eXtended Density Format)_
     XDF is a disk format used for the OS/2 distribution disks.  Its
     operating systems are similar to 2M and MSS disk, but it is faster
     due to a more creative arrangement of sectors. See XDF for
     details.

_XXDF (eXtended XDF)_
     XXDF is an Linux enhancement for XDF. It can store 1992 KB of data
     on an ED disk instead of just 1840 available with the regular XDF
     format. See XXDF for details.

_MFM (Multi Frequency Modulation)_
     MFM is a low level encoding of disk data. It is used for DD, HD
     and ED disks, i.e. virtually all disks that are available today.
     The PC hardware can only read MFM and FM disks.  The doc at:
          ftp://cantor.informatik.rwth-aachen.de/pub/linux/floppy.ps
     contains more detailed information about FM and MFM encoding.

_FM (Frequency modulation)_
     FM is a low level encoding of disk data. It was used for SD disks,
     and is now considered to be obsolete.  The doc at:
          ftp://cantor.informatik.rwth-aachen.de/pub/linux/floppy.ps
     contains more detailed information about FM and MFM encoding.

_kb (kilobit)_
     1000 bits

_kb/s (kilobit per second)_
     We express the raw data throughput to and from the disk in this
     unit, which is also used in the documentation of the floppy disk
     controller.

_B_
     Byte. A byte is 8 bits, and is the smallest individually
     addressable unit of data.

_KB (K-Byte)_
     1024 bytes. Sometimes also noted K.

_KB/s (K-Byte)_
     We express the usable data throughput to and from the disk in KB/s.
     Roughly, 1 KB/s = 8 kb/s. However, the usable data throughput is
     always lower than the raw throughput due to header overhead,
     interleaving and seek overhead.

_MB (Megabyte)_
     Initially, 1 megabyte was 1024*1024 bytes (i.e. 1048576 bytes).
     However, when talking of floppy disk capacity, we understand it as
     1000KB, that is 1000*1024 bytes, i.e. 1024000 bytes.

_MB/s (million bytes per second)_
     We express (high) raw data throughput to and from the disk in kb/s,
     which is also used in the documentation of the floppy disk
     controller.