Part #1 of the promised floppy driver documentation update.

share/man/man4/fdc.4

@@ -1,5 +1,6 @@
 .\"
 .\" Copyright (c) 1994 Wilko Bulte
+.\" Copyright (c) 2001 Joerg Wunsch
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -26,7 +27,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 31, 1994
+.Dd December 16, 2001
 .Dt FDC 4
 .Os
 .Sh NAME
@@ -42,47 +43,264 @@ In
 .Cd hint.fdc.0.port="0x3F0"
 .Cd hint.fdc.0.irq="6"
 .Cd hint.fdc.0.drq="2"
+.Cd hint.fdc.0.flags="0x0"
 .Cd hint.fd.0.at="fdc0"
 .Cd hint.fd.0.drive="0"
+.Cd hint.fd.0.flags="0x0"
 .Cd hint.fd.1.at="fdc0"
 .Cd hint.fd.1.drive="1"
+.Cd hint.fd.1.flags="0x0"
 .Sh DESCRIPTION
-This driver provides access to floppy disk drives.
-In /dev for each floppy device a number of minor devices are present.
-The
-/dev/fd* devices with trailing alphabetic characters are used to indicate
-.Sq partitions
-on the floppy disk.
-The /dev/fd*.<number> are devices that
-indicate the size of the floppy disk (so: 720kB, 1440kB etc). The latter
-are used for formatting disks using fdformat or for accessing different
-density disks in multidensity drive.
-Example: 720kB disk in a 1.44Mb drive.
+.Ss Device Usage
+This driver provides access to floppy disk drives.  Floppy disks using
+either FM (single-density) or MFM (double or high-density) recording
+can be handled.
 .Pp
-Normally, the driver will ask the system's CMOS memory to obtain the
-floppy drive configuration.  Some machines do not store any form of a
-configuration value in their CMOS.  Use the flags value
-.Ql 0x1
-to pretend a 1.44 MB floppy drive as the first unit, without asking the
-CMOS for it.
+Floppy disk controllers can connect up to four drives each.  The
+.Nm
+driver can currently handle up to two drives per controller.  Upon
+driver initialization, an attempt is made to find out the type of the
+floppy controller in use.  The known controller types are either the
+original NE765 or i8272 chips, or alternatively
+.Em enhanced
+controllers that are compatible with the NE72065 or i82077 chips.
+These enhanced controllers (among other enhancements) implement a FIFO
+for floppy data transfers that will automatically be enabled once an
+enhanced chip has been detected.  This FIFO activation can be disabled
+using the per-controller flags value of
+.Ar 0x1 .
+.Pp
+By default, this driver creates a single device node
+.Pa /dev/fd Ns Ar N
+for each attached drive with number
+.Ar N .
+For historical reasons, device nodes that use a trailing UFS-style
+partition letter (ranging from
+.Sq a
+through
+.Sq h )
+can also be accessed, which will be implemented as symbolic links to
+the main device node.
+.Pp
+Accessing the main device node will attempt to autodetect the density
+of the available medium for multi-density devices.  Thus it is
+possible to use either a 720 KB medium or a 1440 KB medium in a
+high-density 3.5 inch standard floppy drive.  Normally, this
+autodetection will only happen once at the first call to
+.Xr open 2
+for the device after inserting the medium.  This assumes the drive
+offers proper changeline support so media changes can be detected by
+the driver.  To indicate a drive that doesn't have changeline support,
+this can be overridden using the per-drive device flags value of
+.Ar 0x10
+(causing each call to
+.Xr open 2
+to perform the autodetection).
+.Pp
+When trying to use a floppy device with special-density media, other
+device nodes can be created, of the form
+.Pa /dev/fd Ns Ar N . Ns Ar MMMM ,
+where
+.Ar N
+is the drive number, and
+.Ar MMMM
+is a number between one and four digits describing the device density.
+Up to 15 additional subdevices per drive can be created that way.  The
+administrator is free to decide on a policy how to assign these
+numbers.  The two common policies are to either implement subdevices
+numbered 1 through 15, or to use a number that describes the medium
+density in kilobytes.  Initially, each of those devices will be
+configured to the maximal density that is possible for the drive type
+(like 1200 KB for 5.25 inch HD drives or 1440 KB for 3.5 inch HD
+drives).  The desired density to be used on that subdevice needs to be
+configured using
+.Xr fdcontrol 8 .
+.Pp
+Drive types are configured using the lower four bits of the per-drive
+device flags.  The following values can be specified:
+.Pp
+.Bl -tag -width NN -offset indent
+.It Ar 1
+5.25 inch double-density device with 40 cylinders (360 KB native
+capacity)
+.It Ar 2
+5.25 inch high-density device with 80 cylinders (1200 KB native
+capacity)
+.It Ar 3
+3.5 inch double-density device with 80 cylinders (720 KB native
+capacity)
+.It Ar 4
+3.5 inch high-density device with 80 cylinders (1440 KB native
+capacity)
+.It Ar 5
+3.5 inch extra-density device with 80 cylinders (2880 KB native
+capacity, usage currently restricted to at most 1440 KB media)
+.It Ar 6
+Same as type 5, available for compatibility with some BIOSes
+.El
+.Pp
+On IA32 architectures, the drive type can be specified as 0 for the
+first two drives.  In that case, the CMOS configuration memory will be
+consulted to obtain the value for that drive.
+.Pp
+Normally, each configured drive will be probed at initialization
+time, using a short seek sequence.  This is intended to find out about
+about drives that have been configured but are actually missing or
+otherwise not responding.  In some environments (like laptops with
+detachable drives), it might be desirable to bypass this drive probe,
+and pretend a drive to be there so the driver autoconfiguration will
+work even if the drive is currently not present.  For that purpose, a
+per-drive device flags value of
+.Ar 0x20
+needs to be specified.
+.Pp
+.Ss Programming Interface
+In addition to the normal read and write functionality, the
+.Nm
+driver offers a number of configurable options using
+.Xr ioctl 2 .
+In order to access any of this functionality, programmers need to
+include the header file
+.Pp
+.In sys/fdcio.h
+.Pp
+into their programs.  The call to
+.Xr open 2
+can be performed in two possible ways.  When opening the device
+without the
+.Li O_NONBLOCK
+flag set, the device is opened in a normal way, which would cause the
+main device nodes to perform automatic media density selection, and which
+will yield a file descriptor that is fully available for any IO operation
+or any of the following
+.Xr ioctl 2
+commands.
+.Pp
+Whe opening the device with
+.Li O_NONBLOCK
+set, automatic media density selection will be bypassed, and the device
+remains in a half-opened state.  No actual IO operations are possible, but
+many of the
+.Xr ioctl 2
+commands described below can be performed.  This mode is intended for
+access to the device without the requirement to have an accessible
+media present, like for status inquiries to the drive, or in order to
+format a medium.
+.Li O_NONBLOCK
+needs to be cleared before IO operations are possible on the descriptor,
+which requires a prior specification of the density using the
+.Li FD_STYPE
+command (see below).  Operations that are not allowed on the half-opened
+descriptor will cause an error value of
+.Ev EAGAIN .
+.Pp
+The following
+.Xr ioctl 2
+commands are currently available:
+.Pp
+.Bl -tag -width FD_READID -offset indent
+.It Li FD_FORM
+Used to format a floppy disk medium.  Third argument is a pointer to a
+.Li struct fd_formb
+specifying which track to format, and which parameters to fill into
+the ID fields of the floppy disk medium.
+.It Li FD_GTYPE
+Returns the current density definition record for the selected device.
+Third argument is a pointer to
+.Li struct fd_type .
+.It Li FD_STYPE
+Adjusts the density definition of the selected device.  Third argument
+is a pointer to
+.Li struct fd_type .
+For the fixed-density subdevices (1 through 15 per drive), this
+operation is restricted to a process with superuser privileges.  For
+the auto-selecting subdevice 0, the operation is temporarily allowed
+to any process, but this setting will be lost again upon the next
+autoselection.  This can be used when formatting a new medium (which
+will require to open the device using
+.Li O_NONBLOCK ,
+and thus to later adjust the density using
+.Li FD_STYPE ) .
+.It Li FD_GOPTS
+Obtain the current drive options.  Third argument is a pointer to
+.Li int ,
+containing a bitwise union of the following possible flag values:
+.Bl -tag -width FDOPT_NOERRLOG -offset indent
+.It Li FDOPT_NORETRY
+Do not automatically retry operations upon failure.
+.It Li FDOPT_NOERRLOG
+Do not cause
+.Dq hard error
+kernel logs for failed IO operations.
+.It Li FDOPT_NOERROR
+Do not indicate IO errors when returning from
+.Xr read 2
+or
+.Xr write 2
+system calls.  The caller is assumed to use
+.Li FD_GSTAT
+calls in order to inquire about the success of each operation.  This
+is intented to allow even erroneous data from bad blocks to be
+retrieved using normal IO operations.
+.It Li FDOPT_AUTOSEL
+Device performs automatic density selection.  Unlike the above flags,
+this one is read-only.
+.El
+.It Li FD_SOPTS
+Set device options, see above for their meaning.  Third argument is a
+pointer to
+.Li int .
+Drive options will always be cleared when closing the descriptor.
+.It Li FD_DEBUG
+Set the driver debug level.  Third argument is a pointer to
+.Li int ,
+level 0 turns off all debugging.  Only applicable if the driver has
+been configured with
+.Pp
+.Cd options FDC_DEBUG
+.It Li FD_CLRERR
+Clear the internal low-level error counter.  Normally, controller-level
+IO errors are only logged up to
+.Li FDC_ERRMAX
+errors (currently defined to 100).  This command resets the counter.
+Requires superuser privileges.
+.It Li FD_READID
+Read one sector ID field from the floppy disk medium.  Third argument is
+a pointer to
+.Li struct fdc_readid ,
+where the read data will be returned.  Can be used to analyze a floppy
+disk medium.
+.It Li FD_GSTAT
+Return the recent floppy disk controller status, if available.  Third
+argument is a pointer to
+.Li struct fdc_status ,
+where the status registers (ST0, ST1, ST2, C, H, R, and N) are being
+returned.
+.Ev EINVAL
+will be caused if no recent status is available.
+.It Li FD_GDTYPE
+Returns the floppy disk drive type.  Third argument is a pointer to
+.Li enum fd_drivetype .
+This type is the same as being used in the per-drive configuration
+flags, or in the CMOS configuration data on IA32 systems.
+.El
 .Pp
-Normally, the device driver detects FDC chipsets that have an internal
-FIFO, and enables the FIFO on them.  There is a slight chance that this
-feature is actually misdetected (seen on an IBM Thinkpad 755c), so it
-can be turned off using flags
-.Ql 0x4 .
 .Sh FILES
 .Bl -tag -width Pa -compact
 .It Pa /dev/fd*
 floppy disk device nodes
-.It Pa /dev/fd*. Ns Ar "<size in kB>"
-floppy disk device nodes where the trailing number indicates the floppy
-capacity
-.It Pa /sys/i386/conf/GENERIC
-sample generic kernel config file
-.It Pa /sys/isa/fd.c
-floppy driver source
 .El
 .Sh SEE ALSO
+.Xr fdcontrol 8 ,
 .Xr fdformat 1 ,
-.Xr disktab 5
+.Xr fdread 1 ,
+.Xr fdwrite 1 ,
+.Xr ioctl 2 ,
+.Xr open 2 ,
+.Xr read 2 ,
+.Xr write 2
+.Sh AUTHORS
+This man page was initially written by
+.An Wilko Bulte ,
+and later vastly rewritten by
+.An J\(:org Wunsch .