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 .Pp
 177 .Ss Programming Interface
 178 In addition to the normal read and write functionality, the
 179 .Nm
 180 driver offers a number of configurable options using
 181 .Xr ioctl 2 .
 182 In order to access any of this functionality, programmers need to
 183 include the header file
 184 .In sys/fdcio.h
 185 into their programs.
 186 The call to
 187 .Xr open 2
 188 can be performed in two possible ways.
 189 When opening the device
 190 without the
 191 .Dv O_NONBLOCK
 192 flag set, the device is opened in a normal way, which would cause the
 193 main device nodes to perform automatic media density selection, and which
 194 will yield a file descriptor that is fully available for any I/O operation
 195 or any of the following
 196 .Xr ioctl 2
 197 commands.
 198 .Pp
 199 When opening the device with
 200 .Dv O_NONBLOCK
 201 set, automatic media density selection will be bypassed, and the device
 202 remains in a half-opened state.
 203 No actual I/O operations are possible, but
 204 many of the
 205 .Xr ioctl 2
 206 commands described below can be performed.
 207 This mode is intended for
 208 access to the device without the requirement to have an accessible
 209 media present, like for status inquiries to the drive, or in order to
 210 format a medium.
 211 .Dv O_NONBLOCK
 212 needs to be cleared before I/O operations are possible on the descriptor,
 213 which requires a prior specification of the density using the
 214 .Dv FD_STYPE
 215 command (see below).
 216 Operations that are not allowed on the half-opened
 217 descriptor will cause an error value of
 218 .Er EAGAIN .
 219 .Pp
 220 The following
 221 .Xr ioctl 2
 222 commands are currently available:
 223 .Bl -tag -width ".Dv FD_READID"
 224 .It Dv FD_FORM
 225 Used to format a floppy disk medium.
 226 Third argument is a pointer to a
 227 .Vt "struct fd_formb"
 228 specifying which track to format, and which parameters to fill into
 229 the ID fields of the floppy disk medium.
 230 .It Dv FD_GTYPE
 231 Returns the current density definition record for the selected device.
 232 Third argument is a pointer to
 233 .Vt "struct fd_type" .
 234 .It Dv FD_STYPE
 235 Adjusts the density definition of the selected device.
 236 Third argument
 237 is a pointer to
 238 .Vt "struct fd_type" .
 239 For the fixed-density subdevices (1 through 15 per drive), this
 240 operation is restricted to a process with superuser privileges.
 241 For
 242 the auto-selecting subdevice 0, the operation is temporarily allowed
 243 to any process, but this setting will be lost again upon the next
 244 autoselection.
 245 This can be used when formatting a new medium (which
 246 will require to open the device using
 247 .Dv O_NONBLOCK ,
 248 and thus to later adjust the density using
 249 .Dv FD_STYPE ) .
 250 .It Dv FD_GOPTS
 251 Obtain the current drive options.
 252 Third argument is a pointer to
 253 .Vt int ,
 254 containing a bitwise union of the following possible flag values:
 255 .Bl -tag -width ".Dv FDOPT_NOERRLOG"
 256 .It Dv FDOPT_NORETRY
 257 Do not automatically retry operations upon failure.
 258 .It Dv FDOPT_NOERRLOG
 259 Do not cause
 260 .Dq "hard error"
 261 kernel logs for failed I/O operations.
 262 .It Dv FDOPT_NOERROR
 263 Do not indicate I/O errors when returning from
 264 .Xr read 2
 265 or
 266 .Xr write 2
 267 system calls.
 268 The caller is assumed to use
 269 .Dv FD_GSTAT
 270 calls in order to inquire about the success of each operation.
 271 This
 272 is intended to allow even erroneous data from bad blocks to be
 273 retrieved using normal I/O operations.
 274 .It Dv FDOPT_AUTOSEL
 275 Device performs automatic density selection.
 276 Unlike the above flags,
 277 this one is read-only.
 278 .El
 279 .It Dv FD_SOPTS
 280 Set device options, see above for their meaning.
 281 Third argument is a
 282 pointer to
 283 .Vt int .
 284 Drive options will always be cleared when closing the descriptor.
 285 .It Dv FD_DEBUG
 286 Set the driver debug level.
 287 Third argument is a pointer to
 288 .Vt int ,
 289 level 0 turns off all debugging.
 290 Only applicable if the driver has
 291 been configured with
 292 .Cd "options FDC_DEBUG" .
 293 .It Dv FD_CLRERR
 294 Clear the internal low-level error counter.
 295 Normally, controller-level
 296 I/O errors are only logged up to
 297 .Dv FDC_ERRMAX
 298 errors (currently defined to 100).
 299 This command resets the counter.
 300 Requires superuser privileges.
 301 .It Dv FD_READID
 302 Read one sector ID field from the floppy disk medium.
 303 Third argument is
 304 a pointer to
 305 .Vt "struct fdc_readid" ,
 306 where the read data will be returned.
 307 Can be used to analyze a floppy
 308 disk medium.
 309 .It Dv FD_GSTAT
 310 Return the recent floppy disk controller status, if available.
 311 Third
 312 argument is a pointer to
 313 .Vt "struct fdc_status" ,
 314 where the status registers (ST0, ST1, ST2, C, H, R, and N) are being
 315 returned.
 316 .Er EINVAL
 317 will be caused if no recent status is available.
 318 .It Dv FD_GDTYPE
 319 Returns the floppy disk drive type.
 320 Third argument is a pointer to
 321 .Vt "enum fd_drivetype" .
 322 This type is the same as being used in the per-drive configuration
 323 flags, or in the CMOS configuration data or ACPI namespace on IA32 systems.
 324 .El
 325 .Sh FILES
 326 .Bl -tag -width ".Pa /dev/fd*" -compact
 327 .It Pa /dev/fd*
 328 floppy disk device nodes
 329 .El
 330 .Sh SEE ALSO
 331 .Xr fdformat 1 ,
 332 .Xr fdread 1 ,
 333 .Xr fdwrite 1 ,
 334 .Xr ioctl 2 ,
 335 .Xr open 2 ,
 336 .Xr read 2 ,
 337 .Xr write 2 ,
 338 .Xr fdcontrol 8
 339 .Sh AUTHORS
 340 .An -nosplit
 341 This man page was initially written by
 342 .An Wilko Bulte ,
 343 and later vastly rewritten by
 344 .An J\(:org Wunsch .