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