307 lines
11 KiB
Groff
307 lines
11 KiB
Groff
.\"
|
|
.\" Copyright (c) 1994 Wilko Bulte
|
|
.\" Copyright (c) 2001 Joerg Wunsch
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 16, 2001
|
|
.Dt FDC 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fdc
|
|
.Nd PC architecture floppy disk controller driver
|
|
.Sh SYNOPSIS
|
|
.Cd device fdc
|
|
.Cd device fd
|
|
.Pp
|
|
In
|
|
.Pa /boot/device.hints :
|
|
.Cd hint.fdc.0.at="isa"
|
|
.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
|
|
.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
|
|
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
|
|
.Sh FILES
|
|
.Bl -tag -width Pa -compact
|
|
.It Pa /dev/fd*
|
|
floppy disk device nodes
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr fdcontrol 8 ,
|
|
.Xr fdformat 1 ,
|
|
.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 .
|