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