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