share/man/man4/fdc.4

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