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