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