1.\" 2.\" Copyright (c) 1994 Wilko Bulte 3.\" Copyright (c) 2001 Joerg Wunsch 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd May 11, 2006 31.Dt FDC 4 32.Os 33.Sh NAME 34.Nm fdc 35.Nd "PC architecture floppy disk controller driver" 36.Sh SYNOPSIS 37.Cd device fdc 38.Pp 39In 40.Pa /boot/device.hints : 41.Cd hint.fdc.0.at="isa" 42.Cd hint.fdc.0.port="0x3F0" 43.Cd hint.fdc.0.irq="6" 44.Cd hint.fdc.0.drq="2" 45.Cd hint.fdc.0.flags="0x0" 46.Cd hint.fd.0.at="fdc0" 47.Cd hint.fd.0.drive="0" 48.Cd hint.fd.0.flags="0x0" 49.Cd hint.fd.1.at="fdc0" 50.Cd hint.fd.1.drive="1" 51.Cd hint.fd.1.flags="0x0" 52.Sh DESCRIPTION 53.Ss Device Usage 54This driver provides access to floppy disk drives. 55Floppy disks using 56either FM (single-density) or MFM (double or high-density) recording 57can be handled. 58.Pp 59Floppy disk controllers can connect up to four drives each. 60The 61.Nm 62driver can currently handle up to two drives per controller (or four 63drives on ACPI). 64Upon 65driver initialization, an attempt is made to find out the type of the 66floppy controller in use. 67The known controller types are either the 68original NE765 or i8272 chips, or alternatively 69.Em enhanced 70controllers that are compatible with the NE72065 or i82077 chips. 71These enhanced controllers (among other enhancements) implement a FIFO 72for floppy data transfers that will automatically be enabled once an 73enhanced chip has been detected. 74This FIFO activation can be disabled 75using the per-controller flags value of 76.Ar 0x1 . 77.Pp 78By default, this driver creates a single device node 79.Pa /dev/fd Ns Ar N 80for each attached drive with number 81.Ar N . 82For historical reasons, device nodes that use a trailing UFS-style 83partition letter (ranging from 84.Sq a 85through 86.Sq h ) 87can also be accessed, which will be implemented as symbolic links to 88the main device node. 89.Pp 90Accessing the main device node will attempt to autodetect the density 91of the available medium for multi-density devices. 92Thus it is 93possible to use either a 720 KB medium or a 1440 KB medium in a 94high-density 3.5 inch standard floppy drive. 95Normally, this 96autodetection will only happen once at the first call to 97.Xr open 2 98for the device after inserting the medium. 99This assumes the drive 100offers proper changeline support so media changes can be detected by 101the driver. 102To indicate a drive that does not have the changeline support, 103this can be overridden using the per-drive device flags value of 104.Ar 0x10 105(causing each call to 106.Xr open 2 107to perform the autodetection). 108.Pp 109When trying to use a floppy device with special-density media, other 110device nodes can be created, of the form 111.Pa /dev/fd Ns Ar N . Ns Ar MMMM , 112where 113.Ar N 114is the drive number, and 115.Ar MMMM 116is a number between one and four digits describing the device density. 117Up to 15 additional subdevices per drive can be created that way. 118The 119administrator is free to decide on a policy how to assign these 120numbers. 121The two common policies are to either implement subdevices 122numbered 1 through 15, or to use a number that describes the medium 123density in kilobytes. 124Initially, each of those devices will be 125configured to the maximal density that is possible for the drive type 126(like 1200 KB for 5.25 inch HD drives or 1440 KB for 3.5 inch HD 127drives). 128The desired density to be used on that subdevice needs to be 129configured using 130.Xr fdcontrol 8 . 131.Pp 132Drive types are configured using the lower four bits of the per-drive 133device flags. 134The following values can be specified: 135.Bl -tag -width 2n -offset indent 136.It Ar 1 1375.25 inch double-density device with 40 cylinders (360 KB native 138capacity) 139.It Ar 2 1405.25 inch high-density device with 80 cylinders (1200 KB native 141capacity) 142.It Ar 3 1433.5 inch double-density device with 80 cylinders (720 KB native 144capacity) 145.It Ar 4 1463.5 inch high-density device with 80 cylinders (1440 KB native 147capacity) 148.It Ar 5 1493.5 inch extra-density device with 80 cylinders (2880 KB native 150capacity, usage currently restricted to at most 1440 KB media) 151.It Ar 6 152Same as type 5, available for compatibility with some BIOSes 153.El 154.Pp 155On IA32 architectures, the drive type can be specified as 0 for the 156drives. 157In that case, the CMOS configuration memory will be 158consulted to obtain the value for that drive. 159The ACPI probe automatically determines these values via the _FDE and 160_FDI methods, but this can be overridden by specifying a drive type hint. 161.Pp 162Normally, each configured drive will be probed at initialization 163time, using a short seek sequence. 164This is intended to find out about 165drives that have been configured but are actually missing or 166otherwise not responding. 167(The ACPI probe method does not perform this seek.) 168In some environments (like laptops with 169detachable drives), it might be desirable to bypass this drive probe, 170and pretend a drive to be there so the driver autoconfiguration will 171work even if the drive is currently not present. 172For that purpose, a 173per-drive device flags value of 174.Ar 0x20 175needs to be specified. 176.Pp 177.Ss Programming Interface 178In addition to the normal read and write functionality, the 179.Nm 180driver offers a number of configurable options using 181.Xr ioctl 2 . 182In order to access any of this functionality, programmers need to 183include the header file 184.In sys/fdcio.h 185into their programs. 186The call to 187.Xr open 2 188can be performed in two possible ways. 189When opening the device 190without the 191.Dv O_NONBLOCK 192flag set, the device is opened in a normal way, which would cause the 193main device nodes to perform automatic media density selection, and which 194will yield a file descriptor that is fully available for any I/O operation 195or any of the following 196.Xr ioctl 2 197commands. 198.Pp 199When opening the device with 200.Dv O_NONBLOCK 201set, automatic media density selection will be bypassed, and the device 202remains in a half-opened state. 203No actual I/O operations are possible, but 204many of the 205.Xr ioctl 2 206commands described below can be performed. 207This mode is intended for 208access to the device without the requirement to have an accessible 209media present, like for status inquiries to the drive, or in order to 210format a medium. 211.Dv O_NONBLOCK 212needs to be cleared before I/O operations are possible on the descriptor, 213which requires a prior specification of the density using the 214.Dv FD_STYPE 215command (see below). 216Operations that are not allowed on the half-opened 217descriptor will cause an error value of 218.Er EAGAIN . 219.Pp 220The following 221.Xr ioctl 2 222commands are currently available: 223.Bl -tag -width ".Dv FD_READID" 224.It Dv FD_FORM 225Used to format a floppy disk medium. 226Third argument is a pointer to a 227.Vt "struct fd_formb" 228specifying which track to format, and which parameters to fill into 229the ID fields of the floppy disk medium. 230.It Dv FD_GTYPE 231Returns the current density definition record for the selected device. 232Third argument is a pointer to 233.Vt "struct fd_type" . 234.It Dv FD_STYPE 235Adjusts the density definition of the selected device. 236Third argument 237is a pointer to 238.Vt "struct fd_type" . 239For the fixed-density subdevices (1 through 15 per drive), this 240operation is restricted to a process with superuser privileges. 241For 242the auto-selecting subdevice 0, the operation is temporarily allowed 243to any process, but this setting will be lost again upon the next 244autoselection. 245This can be used when formatting a new medium (which 246will require to open the device using 247.Dv O_NONBLOCK , 248and thus to later adjust the density using 249.Dv FD_STYPE ) . 250.It Dv FD_GOPTS 251Obtain the current drive options. 252Third argument is a pointer to 253.Vt int , 254containing a bitwise union of the following possible flag values: 255.Bl -tag -width ".Dv FDOPT_NOERRLOG" 256.It Dv FDOPT_NORETRY 257Do not automatically retry operations upon failure. 258.It Dv FDOPT_NOERRLOG 259Do not cause 260.Dq "hard error" 261kernel logs for failed I/O operations. 262.It Dv FDOPT_NOERROR 263Do not indicate I/O errors when returning from 264.Xr read 2 265or 266.Xr write 2 267system calls. 268The caller is assumed to use 269.Dv FD_GSTAT 270calls in order to inquire about the success of each operation. 271This 272is intended to allow even erroneous data from bad blocks to be 273retrieved using normal I/O operations. 274.It Dv FDOPT_AUTOSEL 275Device performs automatic density selection. 276Unlike the above flags, 277this one is read-only. 278.El 279.It Dv FD_SOPTS 280Set device options, see above for their meaning. 281Third argument is a 282pointer to 283.Vt int . 284Drive options will always be cleared when closing the descriptor. 285.It Dv FD_DEBUG 286Set the driver debug level. 287Third argument is a pointer to 288.Vt int , 289level 0 turns off all debugging. 290Only applicable if the driver has 291been configured with 292.Cd "options FDC_DEBUG" . 293.It Dv FD_CLRERR 294Clear the internal low-level error counter. 295Normally, controller-level 296I/O errors are only logged up to 297.Dv FDC_ERRMAX 298errors (currently defined to 100). 299This command resets the counter. 300Requires superuser privileges. 301.It Dv FD_READID 302Read one sector ID field from the floppy disk medium. 303Third argument is 304a pointer to 305.Vt "struct fdc_readid" , 306where the read data will be returned. 307Can be used to analyze a floppy 308disk medium. 309.It Dv FD_GSTAT 310Return the recent floppy disk controller status, if available. 311Third 312argument is a pointer to 313.Vt "struct fdc_status" , 314where the status registers (ST0, ST1, ST2, C, H, R, and N) are being 315returned. 316.Er EINVAL 317will be caused if no recent status is available. 318.It Dv FD_GDTYPE 319Returns the floppy disk drive type. 320Third argument is a pointer to 321.Vt "enum fd_drivetype" . 322This type is the same as being used in the per-drive configuration 323flags, or in the CMOS configuration data or ACPI namespace on IA32 systems. 324.El 325.Sh FILES 326.Bl -tag -width ".Pa /dev/fd*" -compact 327.It Pa /dev/fd* 328floppy disk device nodes 329.El 330.Sh SEE ALSO 331.Xr fdformat 1 , 332.Xr fdread 1 , 333.Xr fdwrite 1 , 334.Xr ioctl 2 , 335.Xr open 2 , 336.Xr read 2 , 337.Xr write 2 , 338.Xr fdcontrol 8 339.Sh AUTHORS 340.An -nosplit 341This man page was initially written by 342.An Wilko Bulte , 343and later vastly rewritten by 344.An J\(:org Wunsch . 345