   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.

Smart use of the data transfer rate
===================================

   Due to different drive rotations speeds, 5 1/4 double density disks
and 3 1/2 double density disks are accessed using different raw data
transfer rates (300 kb/s for the faster spinning 5 1/4 disks, and only
250 kb/s for the slower spinning 3 1/2 disks).  The method described in
this section consists in using the faster data transfer rate intended
for 5 1/4 disks on 3 1/2 disks, and thus boost the raw capacity per
track of these disks.  This is possible because 300 kb/s is still low
enough not to excede the specification of the disk surface of a double
density disk (which 500 kb/s would).

   *Usage: this method is only available for 3 1/2 double density
disks.  The disk obtained cannot be booted from by LILO, and are
inaccessible from MS-DOS.*

   The following table shows the media description for a format using
this method in conjuncion with the previous methods:
     density     tot. cap.    throughput    media description
     3 1/2 DD     1120KB         17KB/s     qd tracksize=7KB mss

   We use the `QD' density selector to describe this particular DTR
set-up, although the acronym `QD' is already taken to name 96tpi double
density 5 1/4 disks.  However, as this dtr trickery is only meaningful
for 3 1/2, we hope that there will be no ambiguity.

2M formats
==========

   2M formats use a standard geometry (18 normal sized sectors) on the
first side of the first cylinder, and an MSS geometry on the rest of the
disk.  They are inspired for Ciriaco Garcia de Celis' 2M utility for
MS-DOS.

   The advantage of 2M disks over simple MSS disks is twofold:
   * They can be accessed from DOS

   * They do not need an autodetect entry, as the boot sector is
     readable using a standard geometry.  Mtools can then use the
     information contained in the boot sector to configure the floppy
     driver to read the rest of the disk.

   Although 2m disk have less sectors on the first track than on the
others, the Linux floppy driver, and 2M's low level floppy access
routines pretend that it contains the same number of sectors.  The
missing sectors are called phantom sectors.  Writes to these sectors are
ignored, and reads return random data.  In order to make up for this, 2M
and mtools pretend that there is a duplicate FAT in the missing sectors,
which is simulated by using data from the first (real) FAT.  Thus 2M
disks work fine for their intended purpose, which is to hold an MS-DOS
filesystem.  *Never use 2M disks for anything other than a MS-DOS
filesystem.  For example, never make an ext2 filesystem on a 2M disk.
If you need a high capacity ext2 filesystem (or minix fs, raw tar or
cpio archive), use the corresponding MSS format instead*

   *Usage:* 2M disks are not bootable by LILO. They can be accessed in
MS-DOS using the 2M utility. 2M can be found at
ftp://FTP.Coast.NET/SimTel/msdos/diskutil/2m30.zip or at any other
simtel mirror. *2M disks are not suitable for non MS-DOS filesystems*.

   *Performance:* Just as with MSS disks, performance is bad for small
reads and writes.

   To describe a 2M format, add the keyword `2m' to its media
description:
     density     tot. cap.    throughput    media description
     3 1/2 HD    1840KB        28KB/s       hd tracksize=23b mss 2m

XDF formats
===========

   XDF is the format used for OS/2 installation floppies.

   Just like 2M, XDF uses mixed sector sizes on "generic tracks".  The
first cylinder uses 512 byte sectors.

   However, for XDF disks, the logical order of the sectors on a given
track, and their physical order is not the same.  This allows a faster
access, in a similar way that interleaving does for disk with normal
sized sectors and too small gaps.  XDF's sector arrangement allows it to
read sectors alternatively from both sides, i.e. the first sector from
side 0, the second from side 1, and the third from side 0 again.  This
differs from the usualy formats, where first the entire side 0 is read,
and then the entire side 1.  This technique allows to read both sides of
a disk in roughly three rotations.

   The following example illustrates how this is done.  In our example
we use the XDF format used for 3 1/2 HD disks, which contains one 8KB
sector, one 2KB sector, one 1KB sector, and one 512 byte sector per
track.  The upper line represents the sectors on side 0, and the lower
line represents the sectors on side 1.  Different numbers represent
different sectors.  Repeated identical numbers represent a single larger
sector.  As the disk is circular, some sectors wrap around at the end:
we find parts of the 8KB sector, represented by 6, both at the beginning
and at the end of each track.

     position:|          1         2         5         4
              | 1234567890123456789012345678901234567890
              |==========================================
     side 0:  | 6633332244444446666666666666666666666666
     side 1:  | 6666444444422333366666666666666666666666

     2   512 byte sector
     3   1KB sector
     4   2KB sector
     6   8KB sector

   When reading a track, sectors are read in the following order:
     sector id    head    position at start     position at end
     ----------------------------------------------------------
         3          0               3                 7
         4          0               9                16
         6          1              18                 5    (1st wrap around)
         2          0               7                 9
         2          1              12                14
         6          0              16                 3    (2nd wrap around)
         4          1               5                12
         3          1              14                18

   We notice that the start of each sector happens at least 2 units of
position (around 300 bytes), after the end of the previously read
sector, thus allowing the floppy disk controller sufficient time to
rest.  Moreover, we notice two wrap-arounds, yielding three rotations to
read the whole cylinder (the third rotation is due to the fact that we
stop at a higher position than we started, and that we also need to
allow some time for seeking to the next track).

   MSS or 2M formats of the same capacity nead at least 2 rotations per
side (i.e. 4 per track), yielding a lower throughput.

   *Usage:* XDF disks are not bootable by LILO.  They can be accessed
from MS-DOS and OS/2 using `xdfcopy.exe' or `xdf.com'.  They are only
suitable for MS-DOS filesystems.  The floppy driver has no direct
support for this format yet, but `mtools' is able to read them using
the `FDRAWCMD' ioctl.

   *Interesting Formats:*

     density     tot. cap.    throughput    formatting command
     5 1/4 HD    1600KB        46KB/s       xdfcopy -0 /dev/fd0
     3 1/2 HD    1840KB        38KB/s       xdfcopy -1 /dev/fd0
     3 1/2 ED    3840KB       102KB/s       xdfcopy -2 /dev/fd0

   The options `-1', `-2' and `-3' descibre one out of the five formats
understoood by `xdfcopy' (3 XDF formats and 2 XDF formats).

XXDF formats
============

   These use the simple principle as XDF, but use a higher geometry.  No
new principle is used, these formats are simply more daring (smaller
gaps, and smaller margin at the end of the sector).

   *Usage:* XXDF disks are not bootable by LILO, and can't be accessed
by MS-DOS.  They are only suitable for MS-DOS filesystems.  The floppy
driver has no direct support for this format yet, but `mtools' is able
to read them using the `FDRAWCMD' ioctl.  Due to their smaller
tolerances, XXDF formats may not work on all drives. Problems may also
occur if you write to XXDF disks using a different drive than the one
you used to format the disk.

   *Interesting Formats:*

     density     tot. cap.    throughput    formatting command
     3 1/2 HD    1920KB        45KB/s       xdfcopy -3 /dev/fd0
     3 1/2 ED    3840KB        90KB/s       xdfcopy -4 /dev/fd0

How autodetection works
***********************

   The principle of autodetection is rather simple. When a floppy disk
is first accessed, and its geometry is not yet known, the floppy driver
tries out a list of up to 8 geometries (format descriptions) until one
is found that matches (i.e. that makes it possible to read the first
sector or track).  This list of geometries is called the _autodetection
list_.  There is one autodetection list per drive type (as indicated in
the cmos).

   The autodetection list doesn't contain the geometry descriptions
themselves, but rather references to entries in the _geometry list_
(see geometry list).  Each list may contain up to 8 such references.
Each reference can be tagged with a `t' flag.  If this tag is set, the
floppy driver tries to read the whole track when trying out that
description; if it is not set, it only tries to read the boot sector.

   Reading the whole track is useful to distinguish among geometries
which differ only in the amount of sectors per track.  In order to do
this, put the geometry with the most sectors first in the list, and set
its `t' tag.  Use the `t' tag only in this case, as it makes
autodetection slower.

   Autodetection cannot distinguish between geometries that only differ
in the number of heads or in the number of tracks.

   Autodetection is meant to supply only a first approximation of the
actual format of the disk.  It supplies enough information to enable a
program such as `mtools' to read the boot sector, which contains the
exact information.  `Mtools' then uses the information contained in the
boot sector to set the exact geometry.

   The autodetection list is set using the following command:
     floppycontrol --autodetect LIST

Example
=======

   The following example restores the default autodetection sequence
for a 3 1/2 ED drive:

     floppycontrol --autodetect 7,8,4,25,28,22,31,21

   The following example changes this sequence, so as to add the 1680KB
format (number 11).  As only 8 formats are allowed in the autodetection
list, we have to dump one entry (we chose the last, which is numbered
21).  The 1680KB format is identical with the default 1440KB format
except for the number of sectors.  Thus we must read the whole track in
order to distinguish it from the 18 sector format (`t' flag).
Furthermore, the the 1680KB sector format should be detected first, as
an 21 sector disk would also matches the standard format with its 18
sectors.

     floppycontrol --autodetect 11t,7,8,4,25,28,22,31

   The following example attempts to autodetect CBM 1581 disks along
with the more usual formats.  CBM 1581 disks are not among the
predefined formats.  Thus we first have to pick one of the predefined
formats and change it so it fits our needs.  We may for example pick
one of the rarely used 5 1/4 formats, such as h880, which bears number
20).  We first make a device node bearing the requested number (so that
we have a filename to pass to setfdprm), then we chmod it so it becomes
accessible to mortal users, finally we configure the geometry of the
new node, and enter it into the autodetection list.  We place it at the
4th position, just behind the usual ED, HD and DD formats, and before
the more exotic extended formats.  Indeed, formats which are nearer to
the head of the list are autodetected faster, and hence more commonly
used formats should be put nearer to the beginning (1).

     mknod /dev/fd0cbm1581 b 2 80
     chmod 666 /dev/fd0cbm1581
     setfdprm /dev/fd0cbm1581 DD DS sect=10 cyl=80 swapsides
     floppycontrol --autodetect 7,8,4,20,25,28,22,31

   Some formats use more than 80 tracks. It is not possible for the
kernel to autodetect the number of tracks in a reasonable time, so you
have to use a sufficiently recent version of mtools to set the number
of tracks according to the boot sector of the disk. Mtools 3.0 and up
are ok. This doesn't obviously work with disks containing something
else than a MS-DOS filesystem.

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

   (1) except of course if several formats only differ in the number of
sectors per track, in which case the formats with the most sectors
should come first

Configuring the floppy driver via lilo or insmod
************************************************

   The floppy driver is configured using the `floppy=' options in lilo.
These options can be typed at the boot prompt, or entered in the lilo
configuration file.

   Example: If your kernel is called `linux-2.0', type the following
line at the lilo boot prompt (if you have a thinkpad):
     linux-2.0 floppy=thinkpad
   You may also enter the following line in `/etc/lilo.conf', in the
description of `linux-2.0':
     append = "floppy=thinkpad"

   Several floppy related options may be given, example:
     linux-2.0 floppy=daring floppy=two_fdc
     append = "floppy=daring floppy=two_fdc"

   If you give options both in the lilo config file and on the boot
prompt, the option strings of both places are concatenated, the boot
prompt options coming last. That's why there are also options to
restore the default behaviour.

   If you use the floppy driver as a module, use the following syntax:
`insmod floppy 'floppy="OPTIONS"''. (This line may be unreadable in the
info version of this document. If so, please refer to the printed
version).

   Example:
     insmod floppy 'floppy="daring two_fdc"'

   Note that in this case `floppy=' should only be typed out once, and
not once for each option. You need at least modules-1.3.57 for this
method.  However, the older environment variable based syntax is still
available:
Bourne (sh, bash, ksh, zsh) syntax:
     `floppy="daring two_fdc" insmod floppy'

C-shell (csh, tcsh) syntax:
     `setenv floppy "daring two_fdc" ; insmod floppy'

   Some versions of insmod are buggy in one way or another. If you have
any problems (options not being passed correctly, segfaults during
insmod), first check whether there is a more recent version. If there
isn't, use the old method using environment variables.  Problems with
`insmod' happen mostly for options involving both a number and a
string, such as `floppy=0,4,cmos'.  Options only involving strings,
such as `floppy=daring' are not affected.

   The floppy related options include:

`floppy=daring'
     Tells the floppy driver that you have a well behaved floppy
     controller.  This allows more efficient and smoother operation,
     but may fail on certain controllers.

`floppy=0,daring'
     Tells the floppy driver that your floppy controller should be used
     with caution.

`floppy=one_fdc'
     Tells the floppy driver that you have only floppy controller
     (default)

`floppy=two_fdc'

`floppy=ADDRESS,two_fdc'
     Tells the floppy driver that you have two floppy controllers. The
     second floppy controller is assumed to be at ADDRESS. If ADDRESS is
     not given, 0x370 is assumed. two_fdc is implied if you use the cmos
     option with a drive of id 4 to 7.

`floppy=thinkpad'
     Tells the floppy driver that you have a Thinkpad. Thinkpads use an
     inverted convention for the disk change line.

`floppy=0,thinkpad'
     Tells the floppy driver that you don't have a Thinkpad.

`floppy=omnibook'
`floppy=nodma'
     Tells the floppy driver not to use Dma for data transfers.  This is
     needed for instance on some HP Omnibooks, which don't have a
     workable DMA channel for the floppy driver. This option is also
     useful if you frequently get "Unable to allocate DMA memory"
     messages.  Indeed, dma memory needs to be continuous in physical
     memory, and is thus harder to find, whereas non-dma buffers may be
     allocated in virtual memory.  However, I advise against this if
     you have an FDC without a FIFO (8272A or 82072). 82072A and later
     are OK. You also need at least a 486 to use nodma.  If you use
     nodma mode, I suggest you also set the FIFO threshold to 10 or
     lower, in order to limit the number of data transfer interrupts.

`floppy=dma'
     Tells the floppy driver that a workable DMA channel is available
     (the default).

`floppy=nofifo'
     Disables the FIFO entirely. This is needed if you get "Bus master
     arbitration error" messages from your ethernet card (or from other
     devices) while accessing the floppy.

`floppy=fifo'
     Enables the FIFO (default)

`floppy=THRESHOLD,fifo_depth'
     Sets the FIFO threshold. This is mostly relevant in DMA mode. If
     this is higher, the floppy driver tolerates more interrupt
     latency, but it triggers more interrupts (i.e. it imposes more
     load on the rest of the system). If this is lower, the interrupt
     latency should be lower too (faster processor). The benefit of a
     lower threshold is less interrupts.

     To tune the fifo threshold, switch on over/underrun messages using
     `floppycontrol --messages'. Then access a floppy disk. If you get a
     huge amount of `Over/Underrun - retrying' messages, then the fifo
     threshold is too low. Try with a higher value, until you only get
     an occasional Over/Underrun.  It is a good idea to compile the
     floppy driver as a module when doing this tuning. Indeed, it
     allows to try different fifo values without rebooting the machine
     for each test. Note that you need to do `floppycontrol --messages'
     every time you re-insert the module.

     Usually, tuning the fifo threshold should not be needed, as the
     default (0xa) is reasonable.

`floppy=DRIVE,TYPE,cmos'
     Sets the cmos type of DRIVE to TYPE. Additionnaly, this drive is
     allowed in the bitmask. This is useful if you have more than two
     floppy drives (only two can be described in the physical cmos), or
     if your BIOS uses non-standard CMOS types. The CMOS types are:
    `0'
          unknown or not installed

    `1'
          5 1/4 DD

    `2'
          5 1/4 HD

    `3'
          3 1/2 DD

    `4'
          3 1/2 HD

    `5'
          3 1/2 ED

    `6'
          3 1/2 ED

     Note that there are two valid types for ED drives. This is because
     5 was initially chosen to represent floppy tapes, and 6 for ED
     drives.  AMI ignored this, and used 5 for ED drives. That's why
     the floppy driver handles both) Setting the CMOS to 0 for the
     first two drives (default) makes the floppy driver read the
     physical cmos for those drives.

`floppy=unexpected_interrupts'
     Print a warning message when an unexpected interrupt is received
     (default behaviour)

`floppy=no_unexpected_interrupts'
`floppy=L40SX'
     Don't print a message when an unexpected interrupt is received.
     This is needed on IBM L40SX laptops in certain video modes. (There
     seems to be an interaction between video and floppy. The
     unexpected interrupts only affect performance, and can safely be
     ignored.)

`floppy=broken_dcl'
     Don't use the disk change line, but assume that the disk was
     changed whenever the device node is reopened. Needed on some boxes
     where the disk change line is broken or unsupported.  This should
     be regarded as a stopgap measure, indeed it makes floppy operation
     less efficient due to unneeded cache flushings, and slightly more
     unreliable. Please verify your cable, connection and jumper
     settings if you have any DCL problems.  However, some older
     drives, and also some Laptops are known not to have a DCL.

`floppy=debug'
     Print debugging messages

`floppy=messages'
     Print informational messages for some operations (disk change
     notifications, warnings about over and underruns, and about
     autodetection)

`floppy=silent_dcl_clear'
     Uses a less noisy way to clear the disk change line (which doesn't
     involve seeks). Implied by daring.

     (There are other options as well, but they are considered
     obsolete, and thus they are not documented here)

Floppy ioctls
*************

   All these ioctl's may be issued using the floppycontrol program. (See
also floppycontrols man page)

`FDSETPRM'
     sets the geometry (number of tracks, heads and sectors, etc) of a
     drive.

`FDDEFPRM'
     sets the geometry in a permanent way (not cleared after a disk
     change)

`FDGETPRM'
     read a previously set drive geometry (or an autodetected geometry)
     back.

`FDCLRPRM'
     makes the driver forget the geometry for a given drive (to trigger
     autodetection)

`FDFLUSH'
     forgets the contents of the floppy buffers. CAUTION: This doesn't
     write dirty buffers to the disk. Use fsync first.

`FDGETDRVTYP'
     displays the type of a drive (name parameter). This is used by
     `MAKEFLOPPIES'. For the naming convention, see the description of
     the `MAKEFLOPPIES' script. For formats which work in several drive
     types, `FDGETDRVTYP' return a name which is appropriate for the
     oldes drive type which supports this format.

`FDSETDRVPRM'
     sets various drive parameters.

`FDGETDRVPRM'
     reads these parameters back.

`FDGETDRVSTAT'
     gets the cached drive state (disk changed, write protected et al.)

`FDPOLLDRVSTAT'
     polls the drive and return its state.

`FDGETFDCSTAT'
     gets the floppy controller state.

`FDRESET'
     resets the floppy controller under certain conditions.

`FDRAWCMD'
     sends a raw command to the floppy controller.

`FDWERRORCLR'
     clear the write error stats.

`FDWERRORGET'
     gets the write error stats.

`FDSETMAXERRS'
     sets the error thresholds (when to display error messages on the
     console, and when to abort operations). The maxerror structure is
     part of the drive parameters, but this ioctl is needed in addition
     to `FDSETDRVPRM' because `FDSETDRVPRM' is only accessible to the
     superuser whereas `FDSETMAXERRS' is accessible to whoever has
     write access to the floppy device.

`FDMSGON/FDMSGOFF'
     switch informational messages on/off. This flag is part of the
     drive parameters as well, but `FDMSGON/FDMSGOFF' don't need
     superuser status.

   There are other ioctls as well, but they are considered obsolete and
their use is discouraged.

Command list
************

   This section describes the available fdutils commands, and the
command line parameters that each of them accepts.

diskd
=====

   The diskd command has the following syntax:

     `diskd' [`-d' DRIVE] [`-i' MSDOSFILES] [`-e' COMMAND]

   Diskd waits for a disk to be inserted into a given DRIVE, and then
either executes the COMMAND or exits. This program can be used to
automatically mount a disk as soon as it is inserted.

Warning
-------

   This program works by switching the motor on for a very short
interval, and then seeking to track -1. This might damage hardware in
the long run. Amigas, which also use these techniques, are known for
having problems with their disk drives no longer spinning up properly
after a few month of usage.

Options
-------

`-d DRIVE'
     Selects the drive to observe for disk insertion. By default, drive
     0 (`/dev/fd0') is observed.

`-i INTERVAL'
     Selects the polling interval. The interval is given in tenths of
     seconds. Default is 10 (one second).

`-e COMMAND'
     Gives the command to be executed when a disk is inserted. If no
     command is given the program simply exits. Typically, the command
     mounts the disk. It can be a shell scripts which probes for several
     filesystems and disk geometries until it succeeds.

Bugs
----

   * Automatic unmounting cannot yet be handled. It is indeed not
     enough to scan for disk removal, because when the disk is removed,
     it is already too late: There might be some buffers needing
     flushing.  However, the `fdmountd' program allows automatic
     unmounting by using the `SYNC' mount options, which switches off
     write buffering (see fdmount).

   * The drive motor is running all the time, and on some computers, the
     drive led flickers at each time the drive is polled.

diskseekd
=========

   Several people have noticed that Linux has a bad tendency of killing
floppy drives. These failures remained completely mysterious, until
somebody noticed that they were due to huge layers of dust accumulating
in the floppy drives. This cannot happen under Messy Dos, because this
excuse for an operating system is so unstable that it crashes roughly
every 20 minutes (actually less if you are running Windows).  When
rebooting, the BIOS seeks the drive, and by doing this, it shakes the
dust out of the drive mechanism. `diskseekd' simulates this effect by
seeking the drive periodically.  If it is called as `diskseek', the
drive is seeked only once.

Options
-------

   The syntax for `diskseekd' is as follows:
     `diskseekd' [`-d' DRIVE] [`-i' INTERVAL] [`-p' PIDFILE]

`-d DRIVE'
     Selects the drive to seek.  By default, drive 0 (`/dev/fd0') is
     seeked.

`-i INTERVAL'
     Selects the cleaning interval, in seconds.  If the interval is 0, a
     single seek is done. This is useful when calling diskseek from a
     crontab.  The default is 1000 seconds (about 16 minutes) for
     `diskseekd' and 0 for `diskseek'.

`-p PIDFILE'
     Stores the process id of the diskseekd daemon into PIDFILE instead
     of the default `/var/run/diskseekd.pid'.

Bugs
----

  1. Other aspects of Messy Dos' flakiness are not simulated.

  2. This section lacks a few smileys.

fdmount
=======

     `fdmount' [`-l'] [`--list'] [`-d'] [`--daemon'] [`--detach']
     [`-i' INTERVAL] [`--interval' INTERVAL] [`-o' MOUNT-OPTIONS]
     [`-r'] [`-readonly'] [`-s'] [`--sync'] [`--nosync'] [`--nodev']
     [`--nosuid'] [`--noexec'] [`-f'] [`--force'] [`-h'] [`--help']
     [DRIVENAME] [MOUNTPOINT]

     `fdumount' [`-f'] [`--force'] [DRIVENAME]

     `fdlist'

     `fdmountd' [`-i' INTERVAL] [`--interval' INTERVAL] [`-r']
     [`-readonly'] [`-s'] [`--sync'] [`--nosync'] [`--nodev']
     [`--nosuid'] [`--noexec'] [`--help'] [DRIVENAME] [MOUNTPOINT]]

   The `fdmount' program mounts a floppy disk in the specified drive.
It tries to figure out the exact format and filesystem type of the disk
from data in the disk's boot sector or super block and the
auto-detected track layout.

   Currently, fdmount supports the filesystems `minix', `ext', `ext2',
`xia', and `msdos', and includes special support for disks formatted by
the `2M' utility for MS-DOS.

   It also checks whether the disk is write protected, in which case it
is mounted read-only.

   The symbolic DRIVENAME is (currently) one of `fd[0-7]',
corresponding to the special device files `/dev/fd[0-7]'. If DRIVENAME
is not specified, `fd0' is assumed.

   The disk is mounted on the directory MOUNTPOINT, if specified, or on
`/fd[0-7]'.  In either case, the mount point must be an existing,
writable directory.

   *Due to a bug in the floppy driver (?), the polling interval (-i
flag) must be longer than the spindown offset. Thus you need to do (for
example) floppycontrol -spindown 99 before starting fdmountd in daemon
mode*

Options
-------

`-l -LIST'
     List all known drives with their symbolic name, type, and mount
     status.

`-d -DAEMON'
     Run in daemon mode (see below).

`--detach'
     Runs daemon in background, and detaches it from its tty. Messages
     produced after the fork are logged to syslog.

`-p FILE'
`--pidfile FILE'
     Dumps the process id of the daemon to FILE. This makes killing the
     daemon easier: `kill -9 `cat FILE`'

`-i INTERVAL'
`--interval INTERVAL'
     Set the polling interval for daemon mode. The unit for INTERVAL is
     0.1 seconds, the default value is 10 (i.e. 1 second).

`-o OPTIONS'
`--options OPTIONS'
     Sets filesystem-specific options. So far, these are only available
     for DOS and Ext2 disks. The following DOS options are supported:
     `check', `conv', `dotsOK', `debug', `fat', `quiet', `blocksize'.
     The following Ext2 options are supported: `check', `errors',
     `grpid', `bsdgroups', `nogrpid', `sysvgroups', `bsddf', `minixdf',
     `resgid', `debug', `nocheck'.  When running as a daemon, options
     not applying to the disk that is inserted (because of its
     filesystem type) are not passed to mount.

`-r -READONLY'
     Mount the disk read-only. This is automatically assumed if the
     disk is write protected.

`-s -SYNC'
     Mount with the `SYNC' option.

`--nosync'
     Mounts without the `SYNC' option, even when running as daemon.

`--nodev'
     Mount with the `NODEV' option. Ignored for `msdos' filesystems,
     otherwise always set for non-root users.

`--nosuid'
     Mount with the `NOSUID' option. Ignored for `msdos' filesystems,
     otherwise always set for non-root users.

`--noexec'
     Mount with the `NOEXEC' option.

`-f -FORCE'
     Attempt a mount or unmount operation even `/etc/mtab' says that
     the drive is already mounted, or not mounted, respectively.  This
     option is useful if `/etc/mtab' got out of sync with the actual
     state for some reason.

`-h -HELP'
     Show short parameter description

Security
--------

   When mounting on the default mount point, the mount points' owner is
set to the current user, and the access flags according to the user's
umask.  For a specified mountpoint, owner and permissions are left
unchanged. Default mount points are called `/fd0', `/fd1', ... , `/fd7'.

   The user running fdmount must have read access to the floppy device
for read only mounts, and read/write access for read/write mounts.

   Fdmount can be run suid root, allowing users to mount floppy disks.
The following restrictions are placed upon non-root users:

   * If a mountpoint is specified explicitly, it must be owned by the
     user.

   * A user may only unmount a disk if the mount point is owned by the
     user, or if it the disk has been mounted by the same user.

   * Non-msdos disks are automatically mounted with the `nodev' and
     `nosuid' flags set.

   However, *do not rely on fdmount being secure at the moment*.

Daemon mode
-----------

   In daemon mode, the specified drive is periodically checked and if a
disk is inserted, it is automatically mounted.

   When the disk is removed, it is automatically unmounted.  However,
it is recommended to unmount the disk manually _before_ removing it. In
order to limit corruption, disks are mounted with the SYNC option when
running in daemon mode, unless the `--nosync' flag is given.

   Note that this mode has some potential drawbacks:
   * Some floppy drives have to move the drive head physically in order
     to reset the disk change signal. It is strongly recommended not to
     use daemon mode with these drives.  See floppycontrol for
     details.

   * If a disk does not contain a filesystem (e.g. a tar archive), the
     mount attempt may slow down initial access.

   * As fdmount cannot identify the user trying to use the disk drive,
     there is no way to protect privacy. Disks are always mounted with
     public access permissions set.

Diagnostics
-----------

`error opening device NAME'

`error reading boot/super block'
     fdmount failed to read the first 1K of the disk. The disk might be
     damaged, unformatted, or it may have a format wich is unsupported
     by the FDC or the Linux kernel.

`unknown filesystem type'
     No magic number of any of the supported filesystems (see above)
     could be identified.

`sorry, can't figure out format (FS filesystem)'
     The size of the filesystem on the disk is incompatible with the
     track layout detected by the kernel and an integer number of
     tracks. This may occur if the filesystem uses only part of the
     disk, or the track layout was detected incorrectly by the kernel.

`failed to mount FS> <SIZEK-disk'
     The actual `mount' system call failed.

`failed to unmount'
     The actual `unmount' system call failed.

`cannot create lock file /etc/mtab~'
     If `/etc/mtab~' exists, you should probably delete it. Otherwise,
     check permissions.

`Can't access MOUNTPOINT'
     Most probably, the default or specified mount point does not exist.
     Use mkdir.

`MOUNTPOINT is not a directory'
     The mountpoint is not a directory.

`not owner of MOUNTPOINT'
     Non-root users must own the directory specified as mount point.
     (This does not apply for the default mount points, /fd[0-3].)

`No write permission to MOUNTPOINT'
     Non-root users must have write permission on the mount point
     directory.

`Not owner of mounted directory: UID=UID'
     Non-root users cannot unmount if the mount point is owned (i.e.
     the disk was mounted) by another user.

`invalid drive name'
     Valid drive names are `fd0', `fd1', etc.

`drive NAME does not exist'
     The drive does not exist physically, is unknown to the Linux
     kernel, or is an unknown type.

`Drive NAME is mounted already'
     Trying to mount a drive which appears to be mounted already.  Use
     the `--force' option if you think this is wrong.

`Drive NAME is not mounted'
     Trying to unmount a drive which does not appear to be mounted.
     Use the `--force' option if you think this is wrong.

`ioctl(...) failed'
     If this occurs with the `FDGETDRVTYP' or `FDGETDRVSTAT', ioctl's
     you should probably update your Linux kernel.

`mounted FS SIZE-disk (OPTIONS)'
     Success message.

Bugs
----

   * Fdmount should be more flexible about drive names and default
     mount points (currently hard coded).

   * Probably not very secure yet (when running suid root).  Untested
     with ext and xia filesystems.

   * Can't specify filesystem type and disk layout explicitly.

   * In daemon mode, the drive light stays on all the time.

   * Some newer filesystem types, such as vfat are not yet supported.

fdrawcmd
========

     `fdrawcmd' [`drive='DRIVE] [`rate='RATE]
     [`length='LENGTH] [`repeat='REPEAT]
     [`cylinder='PHYSICAL-CYL] COMMAND [PARAMTERS ...] [MODE]

   `fdrawcmd' is used to send raw commands to the floppy disk
controller, after having selected a given drive. You must have write
permission to the selected drive.

   When writing to a disk, data is read from stdin; when reading, data
is printed to stdout.  Diagnostic messages, return values from the
controller, and the value of the disk change line after the command are
printed to stderr.

Options
-------

   All numbers may be given in octal (0211), decimal (137), or
hexadecimal (0x89).

`drive=DRIVE'
     Selects the drive.  The default is drive 0 (`/dev/fd0').

`rate=RATE'
     Selects the data transfer rate. Use 0 for high density disks, 1 for
     double density 5 1/4 disks (or 2 Mbps tapes, if the appropriate
     rate table is selected), and 2 for double density 3 1/2 disks.

`length=LENGTH'
     Describes the length of the transferred data for commands reading
     from and writing to the disk.  The default is to continue until
     end of file.

`repeat=COUNT'
     Repeat the command COUNT times.  This only works correctly for
     commands which don't do any data transfer.

`cylinder=COUNT'
     Seek to the given cylinder before executing the command

`COMMAND'
     The name of the command to send.  COMMAND may be a spelled out
     name (like `read' or `write'), or a number representing the
     commands floppy disk controller opcode.  A named command has
     already a mode associated with it, whereas for a number the mode
     parameter should be described using the `mode' option.

`PARAMETERS'
     The parameters for the command (optional, not all commands need
     parameters).

`MODE'
     Various flags or'ed together describing the properties of the
     command.

Commands
--------

   The description of the various floppy commands given in this manpage
is very sketchy. For more details get the 82078 spec sheet which can be
found at:
     http://www-techdoc.intel.com/docs/periph/fd_contr/datasheets/

   Look for the chapter `COMMAND SET/DESCRIPTIONS'.  Older FDCs only
support a subset of the commands described therein, but the syntax for
the commands that do exist is the same.

Commands available on all FDCs
..............................

`read DRVSEL CYL HEAD SECT SZCOD SPT RW-GAP SZCOD2'
     Reads LENGTH bytes of data from the disk.  DRVSEL is the drive
     selector. Bit 0 and 1 describe the drive, and bit 2 describes the
     head.  The remaining parameters give the cylinder, head (yes,
     again), sector, size of the sector (128 * 2 ^ SZCOD), sectors per
     track (`spt', this is used to switch to the second head when the
     first side has been read), and size of the read-write gap. SZCOD2
     should be 0xff.  `read' returns ST0 ST1 ST2 and CYL HEAD SECT
     SZCOD of the next sector to be read; see
     `/usr/include/linux/fdreg.h' .

     N.B. Certain newer floppy disk controllers are buggy, and do not
     correctly recognize the end of transfer when operating in virtual
     DMA mode.  For these, you need to set `spt' to the id of the last
     sector to be read (for example, if you intend to read sectors 2,
     3, 4, set `spt' to 4, even if the disk has more sectors), and set
     the `no-mt' flag.

`write DRVSEL CYL HEAD SECT SZCOD SPT RW-GAP SZCOD2'
     Analogous to `read'.

`sense DRVSEL'
     Returns the third status byte (ST3)

`recalibrate DRVSEL'
     Recalibrates the drive and returns ST0 ST1.

`seek DRVSEL CYL'
     Moves the head to CYL and returns ST0 ST1.

`specify DRVSEL SPEC1 SPEC2'
     Specify various parameters to the drive.

`format DRVSEL SZCOD SECT-PER-TRACK FMT-GAP FMT-FILL'
     Formats the cylinder. The new sectors are filled with FMT-FILL.
     The header information comes from the input, which is made up of
     CYL HEAD SECT SZCOD quadruples. The SZCOD parameter from the
     command line is used to describe the actual size of the sectors,
     and the SZCOD from the input is used to write into the header.
     However, the first write to these sectors will use the header
     information, and might overwrite the following sectors if the
     SZCOD parameter from the command line was too small.

`readid DRVSEL'
     reads the first sector header that comes and returns ST0 ST1 ST2
     and CYL HEAD SECT SZCOD  of the encountered header.

Commands available on 82072 and later
.....................................

`dumpregs'
     Prints the contents of the FDCs registers, if supported.

Commands available on 82072A and later
......................................

`configure CONF1 CONF2 CONF3'
     Configures FIFO operation.

Commands available on 82077 and later
.....................................

`version'
     Echoes 0x90 if the FDC is more recent than 82072A, and 0x80
     otherwise

`perpendicular RATE'
     Sets the perpendicular mode.  Use 0 for normal, 2 for 500kb/s
     perpendicular, and 3 for 1 Mb/s perpendicular.

`seek-out DRVSEL N'
     does a relative seek of N cylinders towards cylinder 0.

`seek-in  DRVSEL N'
     does a relative seek of N cylinders away from cylinder 0.

Commands available on 82077AA and later
.......................................

`lock'
     Locks the FIFO configuration, so that it survives a FDC software
     reset.

`unlock'
     Unlock the FIFO configuration

Commands available on 82078
...........................

`partid'
     echoes a byte describing the type of the FDC in the 3 high bits,
     and the stepping in the three low bits.

`powerdown POWERCONF'
     configures automatic power down of the FDC. The old configuration
     is echoed

`option ISO'
     enables/disables ISO formats. Odd values of ISO enable these
     formats, whereas even values disable them. ISO formats don't have
     index headers, and thus allow to fit slightly more data on a disk.

`save'
     prints out 16 internal registers of the FDC.

`restore R1 R2 R3 ... R16'
     restores the 16 internal registers of the FDC.

`format_n_write DRVSEL SZCOD SECT-PER-TRACK FMT-GAP FMT-FILL'
     formats the cylinder and writes initial data to it. The input data
     is made up of a sequence of headers (4 bytes) and data: HEADER1
     DATA1 HEADER2 DATA2 ... HEADERN DATAN

`drivespec DSPEC1 DSPEC2 ... SPECN TERMINATOR'
     chooses rate tables for various drives. Each dspec byte describes
     one drive. Bits 0 and 1 say which drive is described. Bits 2 and 3
     describe the rate table. Only tables 0 and 2 are interesting. Both
     tables only differ in the meaning og rate 1. For table 0 (the
     default) rate 0 is 300 kb/s (used for 5 1/4 DD disks), whereas for
     table 1 it is 2 Mbps (used for fast floppy tape drives). Bit 4 is
     the precompensation table select bit. It should be set to 0. Bit
     5-7 should be zero as well. The TERMINATOR byte ends the
     `drivespec' command. It is either 0xc0 or 0x80. If it is 0xc0, no
     result phase follows; if it is 0x80, the current data rate table
     configuration for the four drives is echoed.

Modes
-----

   The mode option is only needed when you describe the command as a
numerical value. Some mode names are also valid command names. They are
considered as command name if the command name has not yet been given,
and as mode name otherwise.

   If you give a command name followed by explicit modes, both the
implicit flags of the command name, and the explicit modes are or'ed
together.

   If on the other hand you give a command name preceded by explicit
modes, only the explicit modes are or'ed together.

`read'
     Read data from disk using DMA.

`write'
     Write data to the disk.

`intr'
     Wait for an interrupt.

`spin'
     wait for the disk to spin up

`disk'
     Aborts the operation if no disk is in the drive. This only works
     if you also chose a physical cylinder to seek to.

`no-motor'
     Don't switch on the drive motor while issuing the command

`no-motor-after'
     Switch off the motor immediately after the command returns.

`fm'
     Uses the FM version of the `read', `readid', `write' and `format'
     commands.

`no-mt'
     Do not use MT (multitrack) mode for the `read', `readid' and
     `write' commands. This is needed on certain broken FDC's which
     don't recognize end of transfer when running in `nodma' mode. In
     order to use these safely, set `no-mt', and chose the id of the
     last sector to be read as `sect-per-track'.

   `fdrawcmd' opens the device node with the `NDELAY' flag. This means
that the driver should not try to autodetect the disk type (it might
not be formatted), and that it should not reset the FDC. If a reset was
needed, the command simply fails. If that happens, execute
`floppycontrol --resetnow 0' , and try again.

floppycontrol
=============

     `floppycontrol' [`-p'] [`--pollstate'] [`--printfdstate']
     [`-a' OPERATION-ABORT-THRESHOLD] [`-c' READ-TRACK-THRESHOLD]
     [`-r' RECALIBRATE-THRESHOLD] [`-R' RESET-THRESHOLD]
     [`-e' REPORTING-THRESHOLD] [`-f'] [`-x'] [`-d' DRIVE][`-F'] [`-T']
     [`-reset' CONDITION] [`--debug'] [`--nodebug'] [`--messages']
     [`--nomessages'] [`--broken_dcl'] [`--working_dcl'] [`--inverted_dcl']
     [`--no_inverted_dcl'] [`--silent_dcl_clear'] [`--noisy_dcl_clear']
     [`-c'CMOS-TYPE] [`-hlt' HLT] [`-hut' HUT] [`-srt' SRT] [`-o' SPINDOWN]
     [`-u' SPINUP] [`-s' SELECT-DELAY] [`-rps' ROTATIONS-PER-SECOND]
     [`-O' SPINDOWN-OFFSET] [`-track' MAX-TRACKS] [`-timeout' SECONDS]
     [`-C' CHECK-INTERVAL] [`-n' NATIVE-FORMAT]
     [`-autodetect' AUTODETECTION-SEQUENCE] [`-P'] [`--clrwerror']
     [`--printwerror'] [`-h']

   The `floppycontrol' program is used to configure the floppy driver.

General Options
---------------

`-h'
`--help'
     Print a help screen.

`-d DRIVE'
`--drive  DRIVE'
     Selects the drive to configure. The default is drive 0
     (`/dev/fd0').

One time actions
----------------

   The following `floppycontrol' options don't set a configuration
parameter, but perform a one-time action. They are available to anybody
who has write access to the drive

`-f'
`--flush'
     Flushes (throws away) the dirty data buffers associated with this
     drive.

`-x'
`--eject'
     Ejects the disk out of the drive (Sparc). The dirty buffers are
     first committed to disk before ejecting it. Fails if the disk is
     mounted.

`--reset  CONDITION'
     Resets the FDC under CONDITION . Condition may be one of the
     following:
    `0'
          resets the FDC only if a reset is needed anyways,

    `1'
          resets the FDC also if a raw command has been performed since
          the last reset, and

    `2'
          resets the FDC unconditionally.

     This command may be needed after some failed raw commands (see
     fdrawcmd).

`-F'
`--formatend'
     Issues an end format ioctl. This might be needed after exiting a
     `fdformat' in an unclean way. `superformat' is not subject to this.