diff options
author | joerg <joerg@FreeBSD.org> | 2001-12-16 22:49:57 +0000 |
---|---|---|
committer | joerg <joerg@FreeBSD.org> | 2001-12-16 22:49:57 +0000 |
commit | 3a6276ed89bada372c87aa7c47fada8209c421ec (patch) | |
tree | 84f61d5edaea6e99033ce46fb9a30d77a3dc26d8 /share/man/man4/fdc.4 | |
parent | 5c873cad57d228e70ad36d16b23b89c8b49387c7 (diff) | |
download | FreeBSD-src-3a6276ed89bada372c87aa7c47fada8209c421ec.zip FreeBSD-src-3a6276ed89bada372c87aa7c47fada8209c421ec.tar.gz |
Part #1 of the promised floppy driver documentation update.
Diffstat (limited to 'share/man/man4/fdc.4')
-rw-r--r-- | share/man/man4/fdc.4 | 284 |
1 files changed, 251 insertions, 33 deletions
diff --git a/share/man/man4/fdc.4 b/share/man/man4/fdc.4 index 288ff05..94b1cfd 100644 --- a/share/man/man4/fdc.4 +++ b/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. -.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. -.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 . +.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 -.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 . |