 This package contains utilities to configure and debug the floppy
driver, and utilities to format floppy disks.

-----------------------------------------------------------------------------
WARNING
=======
 Although most drives are able to use 83 tracks, some may not. If your
drive is making strange noises while accessing these tracks, don't use
formats which use more than 80 tracks (13-19). (You may still gain
something by the increased number of sectors)
-----------------------------------------------------------------------------

 The fdutils allows you to access some of the extended features of the
linux floppy driver.

 These include:

 1. Formatting disks with a higher capacity than usual (up to 1992k on
a 3 1/2 HD disk).
 2. Reconfiguration of the autodetection sequence to automatically
detect some of these extended formats.
 3. Limitation by the superuser of the highest allowable number of
tracks.
 4. Access to various internal driver structures, and drive
configuration using the floppycontrol program.

Floppy ioctls: 
==============

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

 1. FDSETPRM sets the geometry (number of tracks, heads and sectors,
etc) of a drive.
 2. FDDEFPRM sets the geometry in a permanent way (not cleared after a
disk change)
 3. FDGETPRM read a previously set drive geometry (or an autodetected
geometry) back.
 4. FDCLRPRM makes the driver forget the geometry for a given drive
(to trigger autodetection)
 5. FDFLUSH forgets the contents of the floppy buffers. CAUTION: This
doesn't write dirty buffers to the disk. Use fsync first.
 6. 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.
 7. FDSETDRVPRM sets various drive parameters.
 8. FDGETDRVPRM reads these parameters back.
 9. FDGETDRVSTAT gets the cached drive state (disk changed, write
protected et al.)
10. FDPOLLDRVSTAT polls the drive and return its state.
11. FDGETFDCSTAT gets the floppy controller state.
12. FDRESET resets the floppy controller under certain conditions.
13. FDRAWCMD sends a raw command to the floppy controller.
14. FDWERRORCLR clear the write error stats.
15. FDWERRORGET gets the write error stats.
16. 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.
17. 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.

 The extended formats
 ====================

 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 o set the number
of tracks according to the boot sector of the disk. Mtools 2.5 and up
are ok. This doesn't obviously work with disks containing something
else than a MSDOS filesystem.

 The minor device number for the floppy devices is calculated as
follows:
    minor_device = format_nr * 4 + 128 * fdc_nr + unit_nr 
 (fdc_nr identifies the floppy disk controller, and unit_nr identifies
which drive on the floppy disk controller to be used)

The major device number is 2. The format_nr is the number of the entry
in the table in floppy.c. Valid numbers and formats are:

             format_nr     Format
             ---------     ------
                  0        autodetect
                  1        360kB,  5.25" DD drive
                  2        1200kB, 5.25" HD drive
                  3        360kB,  3.5"  DD drive
                  4        720kB,  3.5"  DD drive
                  5        360kB,  5.25" DD disk in HD drive
                  6        720kB,  5.25" DD disk in HD drive
                  7        1440kB, 3.5"  HD drive
                  8        2880kB, 3.5"  ED drive

                  9        2880kB, 3.5"  CompaQ ED drive (???)

                 10        1440kB, 5.25" HD drive
                 11        1680kB, 3.5"  HD drive
                 12        410kB,  5.25" DD disk in HD drive
                 13        820kB,  3.5"  DD drive
                 14        1476kB, 5.25" HD drive
                 15        1722kB, 3.5"  HD drive
                 16        420kB,  5.25" DD disk in HD drive
                 17        830kB,  3.5"  DD drive
                 18        1494kB, 5.25" HD drive
                 19        1743kB, 3.5"  HD drive
                 20         880kB, 5.25" DD drive
                 21        1040kB, 3.5"  DD drive
                 22        1120kB, 3.5"  DD drive
                 23        1600kB, 5.25" HD drive
                 24        1760kB, 3.5"  HD drive
                 25        1920kB, 3.5"  HD drive
		 26	   3200kB, 3.5"  ED drive
		 27	   3520kB, 3.5"  ED drive
		 28	   3840kB, 3.5"  ED drive
		 29	   1840kB, 3.5"  HD drive
		 30	    800kB, 3.5"  DD drive
		 31	   1600kB, 3.5"  HD drive

 This table lists first the format_nr (0-31) used to compute the minor
number, then the capacity of the format (360kb - 3200kb), and then the
type of the drive in which this format is used.

 The formats 0..8 are the standard PC formats, 9 is apparently needed
for certain weird CompaQ computers. The remaining formats are extended
capacity formats. Some of them have been taken from Heiko Schroeder's
fdpatches (after correcting some minor bugs). Others have been added
by David Niemi and me (Alain Knaff). Formats 30 and 31 are
non-interleaved formats with normal sized sectors, and have the
highest capacity that can be achieved without resorting to
interleaving or bigger sectors. Formats 20 to 29 use bigger sectors
than usual, and thus are probably not readable with most DOS utilities
(fdformat, vgacopy etc. Get 2m instead :-) )
 BEWARE OF FORMATS 13-19 IF YOUR DRIVE ONLY SUPPORTS 80 TRACKS.

 You can redefine these formats using the setfdprm program (Written by
Werner Almesberger).

 To use the new formats, you have to make new /dev/fd* entries, using the
MAKEFLOPPIES shell script.

You may also make the devices manually: (This is needed if you redefine
your default formats using setfdprm)

Example:
   Make a device entry for a 1.74MB floppy in drive 0:
   The format number is 19, drive 0, floppy disk controller 0 so 
   the minor device number is 128*0+4*19+0=76. The command line to make 
   the new device entry is:
          mknod /dev/fd0H1743 b 2 76
                   ^          ^ ^ ^
                   |          | | Minor device number
                   |          | Major device number (always 2!)           
                   |          Blockdevice
                   A name that you choose for the format. I
		   recommend the names I used in floppy.c, but
                   you can choose any name you want.


 Other formats:
 ==============

 Linux is able to read almost any MFM disks. These include many CP/M
disks and also Commodore 1581 disks. Please get Michael Haardt's
documentation on floppy drives for a detailed description of those
formats. This can be ftp'ed from
ftp://cantor.informatik.rwth-aachen.de/pub/linux/floppy.ps

 Commodore 1581 disks are not yet described in this documentation.
Use 'setfdprm /dev/fd0 1600 10 2 80 2 0x2A 0x02 0xDF 0x2E' to use
these. If you want to use these disks often, redefine one of the
"default" formats to be Commodore 1581, and then put it into the
autodetection list for the drive. The following example describes how
to redefine format number 31 (minor device number 124) to be Commodore
1581:

 mknod /dev/fd0cbm1581 b 2 124
 setfdprm /dev/fd0cmb1581 1600 10 2 80 2 0x2A 0x02 0xDF 0x2E
 floppycontrol --autodetect /dev/fd0 31,7,8,4,25,28,22,21

 The two latter commands have to be issued after each reboot, so I
suggest you put them into your /etc/rc files if you use many Commodore
1581 disks.


 Using more than 80 tracks:
 ==========================

 Although most drives support more than 80 tracks some may not, and
repeatedly trying to read beyond track 80 might be damaging to them.
In order to know wether your drive supports more than eighty tracks,
first set the number of allowed tracks to 82.
(using floppycontrol --tracks 82 -d <drive>)
 Then format a disks with a 82 track format (for example
/dev/fd0H1722), and copy a file on it large enough to fill the disk it
completely. (Many small files will do too. The disk is full enough if
the free space is less than a track, in this case 18k) Then eject and
reinsert the disk, and compare the file on the disk with the
original. If they are still the same, your drive supports 82
tracks. (If yes, you might want to try also with 83 tracks: /dev/fd0H1743))
 (This single experience should not damage the drive.)
 If you do have a drive which supports more than 80 tracks, you have
to enable the additional tracks after each boot, for instance by
calling floppycontrol --tracks 82 from your /etc/rc.local in order to
allow programs to use these tracks. (Alternatively, you could also
change it in the default_drive_params structure)
 If your drive doesn't support more than 80 tracks, please remove the
entries for formats 13-19 from your /dev directory after running
MAKEFLOPPIES.

 N.B. I have yet to see a 3.5" drive which doesn't support 82 tracks.
If you have such a beast, please mail me.

 Configuring the floppy driver via lilo:
 =======================================

 The floppy driver is configured using the 'floppy=' option in
lilo. This option can be typed at the boot prompt, or entered in the
lilo configuration file.
 Example: If your kernel is called linux-72, type the following line
at the lilo boot prompt (if you have a thinkpad):
 linux-72 floppy=thinkpad
You may also enter the following line in /etc/lilo.conf, in the description
of linux-72:
 append = "floppy=thinkpad"

 Several floppy related options may be given, example:
 linux-72 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.

 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=<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: 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.)

(There are other options as well, but they are considered obsolete)

 Included utilities:
 ===================

 1. floppycontrol. This program sets the various error tresholds
(error reporting, operation abortion, and read track), prints out
drive drive types, and flushes buffers. There is a -h help option.
 This program provides examples on how to use the new ioctl's.
 
 To compile this program just type make in the util directory.

 See also the included manpage. (in the utils directory)

 2. MAKEFLOPPIES. This shell script creates the new floppy block
device files.  It uses the floppycontrol program to translate the
minor device numbers into meaningful names. It also uses these names
to decide wether 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, the kernel cannot find out
the types of these additional drives, and you need to specify them
with the environmental variables FD2 and FD3. The following types are
available: H1440 ( HD 3''1/2), h1200 (HD 5''1/4), D720 (DD 3''1/2) and
d360 (DD 5''1/4).
 Sample command line:
  FD2=1.44M FD3=1.2M MAKEFLOPPIES

 The names of the device are a letter describing the _drive_ types,
followed by a letter describing the size of the _format_.
The letters are
 E = 3.5"  ED drive
 H = 3.5"  HD drive
 D = 3.5"  DD drive
 h = 5.25" HD drive
 d = 5.25" DD drive

 Example: h360 is a device for accessing a 360k disk in a 5.25" HD drive.

 This convention is the same as used by Slackware and the MAKEDEV script,
except for the ED drives (which are named H2880 by MAKEDEV, and don't yet
exist in Slackware)

 IMPORTANT: The MAKEFLOPPIES script needs the floppycontrol program on
the search PATH.

 3. Setfdprm. This program is used to set the media parameters for a drive.
See manpage (in the utils directory)

 4. Superformat. This program is used to format floppy disks. The old
fdformat doesn't work for disks with bigger sectors. WARNING: DO READ
THIS MANPAGE CAREFULLY. IMPROPER USAGE MAY LEAD TO DATA LOSS.

 5. Others: see the manpages

 Reading these disks under dos:
 ==============================

 *formats with normal sector sizes: (10..19)
 	There are zillions of utilities which are able to read these:
		fdformat, vgacopy, ...

	With dos6, you don't even need those, just put the following
	line in your config.sys:

		drivparm=/d:0 /f:7 /h:2 /s:21 /t:82
			    ^    ^ \______________/
			    |    |          |
                 drive number    |       max geometry
                                 |
			drive type, consult the dos help for details



 *formats with bigger sectors:
	There is only one utility which can do this: 
	2m20 (by Ciriaco Garcia)
	You can get this program from 
	nic.switch.ch:/mirror/msdos/diskutil/2m20.zip
	(for other adresses, see archie)	

	This program uses a normal format for the first track and first head
	(18 sectors), and enhanced formats for the other tracks (up to
	24*512 bytes per track !)
	See the manpage of superformat (option --2m) to know how to
	format disks readable by this program. This man page is in
	the utils directory. WARNING: DO READ THIS MANPAGE CAREFULLY.
	IMPROPER USAGE MAY LEAD TO DATA LOSS. DO ONLY PUT MSDOS FILESYSTEMS
	ON 2M DISKS.

 Other Doc:
 ==========

 There are man pages for mtools (in mtools/) and the utilities (in
utils/) included. There's also a FAQ list. It is regularily updated on
http://www.club.innet.lu/~year3160/floppy/FAQ.html .  You can find
alpha versions of fdutils on
http://www.club.innet.lu/~year3160/fdutils . (They are named
fduddmm.taz, where dd stands for the day and mm for the month. I'll
only leave these for a limited time, and then move them into an old
directory, or remove them.)
