d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

mdoc(7) police: tidy up the markup.

Browse Source
This commit is contained in:
ru 2002-01-10 16:51:28 +00:00
parent 3c4655ddfb
commit f69963b299
1 changed files with 131 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
share/man/man4/fdc.4
View File

@ -32,7 +32,7 @@
.Os .Os
.Sh NAME .Sh NAME
.Nm fdc .Nm fdc
.Nd PC architecture floppy disk controller driver .Nd "PC architecture floppy disk controller driver"
.Sh SYNOPSIS .Sh SYNOPSIS
.Cd device fdc .Cd device fdc
.Cd device fd .Cd device fd
@ -52,21 +52,26 @@ In
.Cd hint.fd.1.flags="0x0" .Cd hint.fd.1.flags="0x0"
.Sh DESCRIPTION .Sh DESCRIPTION
.Ss Device Usage .Ss Device Usage
This driver provides access to floppy disk drives. Floppy disks using This driver provides access to floppy disk drives.
Floppy disks using
either FM (single-density) or MFM (double or high-density) recording either FM (single-density) or MFM (double or high-density) recording
can be handled. can be handled.
.Pp .Pp
Floppy disk controllers can connect up to four drives each. The Floppy disk controllers can connect up to four drives each.
The
.Nm .Nm
driver can currently handle up to two drives per controller. Upon driver can currently handle up to two drives per controller.
Upon
driver initialization, an attempt is made to find out the type of the driver initialization, an attempt is made to find out the type of the
floppy controller in use. The known controller types are either the floppy controller in use.
The known controller types are either the
original NE765 or i8272 chips, or alternatively original NE765 or i8272 chips, or alternatively
.Em enhanced .Em enhanced
controllers that are compatible with the NE72065 or i82077 chips. controllers that are compatible with the NE72065 or i82077 chips.
These enhanced controllers (among other enhancements) implement a FIFO These enhanced controllers (among other enhancements) implement a FIFO
for floppy data transfers that will automatically be enabled once an for floppy data transfers that will automatically be enabled once an
enhanced chip has been detected. This FIFO activation can be disabled enhanced chip has been detected.
This FIFO activation can be disabled
using the per-controller flags value of using the per-controller flags value of
.Ar 0x1 . .Ar 0x1 .
.Pp .Pp
@ -83,14 +88,18 @@ can also be accessed, which will be implemented as symbolic links to
the main device node. the main device node.
.Pp .Pp
Accessing the main device node will attempt to autodetect the density Accessing the main device node will attempt to autodetect the density
of the available medium for multi-density devices. Thus it is of the available medium for multi-density devices.
Thus it is
possible to use either a 720 KB medium or a 1440 KB medium in a possible to use either a 720 KB medium or a 1440 KB medium in a
high-density 3.5 inch standard floppy drive. Normally, this high-density 3.5 inch standard floppy drive.
Normally, this
autodetection will only happen once at the first call to autodetection will only happen once at the first call to
.Xr open 2 .Xr open 2
for the device after inserting the medium. This assumes the drive for the device after inserting the medium.
This assumes the drive
offers proper changeline support so media changes can be detected by offers proper changeline support so media changes can be detected by
the driver. To indicate a drive that doesn't have changeline support, the driver.
To indicate a drive that does not have the changeline support,
this can be overridden using the per-drive device flags value of this can be overridden using the per-drive device flags value of
.Ar 0x10 .Ar 0x10
(causing each call to (causing each call to
@ -105,21 +114,25 @@ where
is the drive number, and is the drive number, and
.Ar MMMM .Ar MMMM
is a number between one and four digits describing the device density. is a number between one and four digits describing the device density.
Up to 15 additional subdevices per drive can be created that way. The Up to 15 additional subdevices per drive can be created that way.
The
administrator is free to decide on a policy how to assign these administrator is free to decide on a policy how to assign these
numbers. The two common policies are to either implement subdevices numbers.
The two common policies are to either implement subdevices
numbered 1 through 15, or to use a number that describes the medium numbered 1 through 15, or to use a number that describes the medium
density in kilobytes. Initially, each of those devices will be density in kilobytes.
Initially, each of those devices will be
configured to the maximal density that is possible for the drive type configured to the maximal density that is possible for the drive type
(like 1200 KB for 5.25 inch HD drives or 1440 KB for 3.5 inch HD (like 1200 KB for 5.25 inch HD drives or 1440 KB for 3.5 inch HD
drives). The desired density to be used on that subdevice needs to be drives).
The desired density to be used on that subdevice needs to be
configured using configured using
.Xr fdcontrol 8 . .Xr fdcontrol 8 .
.Pp .Pp
Drive types are configured using the lower four bits of the per-drive Drive types are configured using the lower four bits of the per-drive
device flags. The following values can be specified: device flags.
.Pp The following values can be specified:
.Bl -tag -width NN -offset indent .Bl -tag -width 2n -offset indent
.It Ar 1 .It Ar 1
5.25 inch double-density device with 40 cylinders (360 KB native 5.25 inch double-density device with 40 cylinders (360 KB native
capacity) capacity)
@ -140,16 +153,20 @@ Same as type 5, available for compatibility with some BIOSes
.El .El
.Pp .Pp
On IA32 architectures, the drive type can be specified as 0 for the On IA32 architectures, the drive type can be specified as 0 for the
first two drives. In that case, the CMOS configuration memory will be first two drives.
In that case, the CMOS configuration memory will be
consulted to obtain the value for that drive. consulted to obtain the value for that drive.
.Pp .Pp
Normally, each configured drive will be probed at initialization Normally, each configured drive will be probed at initialization
time, using a short seek sequence. This is intended to find out about time, using a short seek sequence.
about drives that have been configured but are actually missing or This is intended to find out about
otherwise not responding. In some environments (like laptops with drives that have been configured but are actually missing or
otherwise not responding.
In some environments (like laptops with
detachable drives), it might be desirable to bypass this drive probe, detachable drives), it might be desirable to bypass this drive probe,
and pretend a drive to be there so the driver autoconfiguration will and pretend a drive to be there so the driver autoconfiguration will
work even if the drive is currently not present. For that purpose, a work even if the drive is currently not present.
For that purpose, a
per-drive device flags value of per-drive device flags value of
.Ar 0x20 .Ar 0x20
needs to be specified. needs to be specified.
@ -161,145 +178,163 @@ driver offers a number of configurable options using
.Xr ioctl 2 . .Xr ioctl 2 .
In order to access any of this functionality, programmers need to In order to access any of this functionality, programmers need to
include the header file include the header file
.Pp .Aq Pa sys/fdcio.h
.In sys/fdcio.h into their programs.
.Pp The call to
into their programs. The call to
.Xr open 2 .Xr open 2
can be performed in two possible ways. When opening the device can be performed in two possible ways.
When opening the device
without the without the
.Li O_NONBLOCK .Dv O_NONBLOCK
flag set, the device is opened in a normal way, which would cause the flag set, the device is opened in a normal way, which would cause the
main device nodes to perform automatic media density selection, and which main device nodes to perform automatic media density selection, and which
will yield a file descriptor that is fully available for any IO operation will yield a file descriptor that is fully available for any I/O operation
or any of the following or any of the following
.Xr ioctl 2 .Xr ioctl 2
commands. commands.
.Pp .Pp
Whe opening the device with Whe opening the device with
.Li O_NONBLOCK .Dv O_NONBLOCK
set, automatic media density selection will be bypassed, and the device set, automatic media density selection will be bypassed, and the device
remains in a half-opened state. No actual IO operations are possible, but remains in a half-opened state.
No actual I/O operations are possible, but
many of the many of the
.Xr ioctl 2 .Xr ioctl 2
commands described below can be performed. This mode is intended for commands described below can be performed.
This mode is intended for
access to the device without the requirement to have an accessible access to the device without the requirement to have an accessible
media present, like for status inquiries to the drive, or in order to media present, like for status inquiries to the drive, or in order to
format a medium. format a medium.
.Li O_NONBLOCK .Dv O_NONBLOCK
needs to be cleared before IO operations are possible on the descriptor, needs to be cleared before I/O operations are possible on the descriptor,
which requires a prior specification of the density using the which requires a prior specification of the density using the
.Li FD_STYPE .Dv FD_STYPE
command (see below). Operations that are not allowed on the half-opened command (see below).
Operations that are not allowed on the half-opened
descriptor will cause an error value of descriptor will cause an error value of
.Ev EAGAIN . .Er EAGAIN .
.Pp .Pp
The following The following
.Xr ioctl 2 .Xr ioctl 2
commands are currently available: commands are currently available:
.Pp .Bl -tag -width ".Dv FD_READID"
.Bl -tag -width FD_READID -offset indent .It Dv FD_FORM
.It Li FD_FORM Used to format a floppy disk medium.
Used to format a floppy disk medium. Third argument is a pointer to a Third argument is a pointer to a
.Li struct fd_formb .Vt "struct fd_formb"
specifying which track to format, and which parameters to fill into specifying which track to format, and which parameters to fill into
the ID fields of the floppy disk medium. the ID fields of the floppy disk medium.
.It Li FD_GTYPE .It Dv FD_GTYPE
Returns the current density definition record for the selected device. Returns the current density definition record for the selected device.
Third argument is a pointer to Third argument is a pointer to
.Li struct fd_type . .Vt "struct fd_type" .
.It Li FD_STYPE .It Dv FD_STYPE
Adjusts the density definition of the selected device. Third argument Adjusts the density definition of the selected device.
Third argument
is a pointer to is a pointer to
.Li struct fd_type . .Vt "struct fd_type" .
For the fixed-density subdevices (1 through 15 per drive), this For the fixed-density subdevices (1 through 15 per drive), this
operation is restricted to a process with superuser privileges. For operation is restricted to a process with superuser privileges.
For
the auto-selecting subdevice 0, the operation is temporarily allowed the auto-selecting subdevice 0, the operation is temporarily allowed
to any process, but this setting will be lost again upon the next to any process, but this setting will be lost again upon the next
autoselection. This can be used when formatting a new medium (which autoselection.
This can be used when formatting a new medium (which
will require to open the device using will require to open the device using
.Li O_NONBLOCK , .Dv O_NONBLOCK ,
and thus to later adjust the density using and thus to later adjust the density using
.Li FD_STYPE ) . .Dv FD_STYPE ) .
.It Li FD_GOPTS .It Dv FD_GOPTS
Obtain the current drive options. Third argument is a pointer to Obtain the current drive options.
.Li int , Third argument is a pointer to
.Vt int ,
containing a bitwise union of the following possible flag values: containing a bitwise union of the following possible flag values:
.Bl -tag -width FDOPT_NOERRLOG -offset indent .Bl -tag -width ".Dv FDOPT_NOERRLOG"
.It Li FDOPT_NORETRY .It Dv FDOPT_NORETRY
Do not automatically retry operations upon failure. Do not automatically retry operations upon failure.
.It Li FDOPT_NOERRLOG .It Dv FDOPT_NOERRLOG
Do not cause Do not cause
.Dq hard error .Dq "hard error"
kernel logs for failed IO operations. kernel logs for failed I/O operations.
.It Li FDOPT_NOERROR .It Dv FDOPT_NOERROR
Do not indicate IO errors when returning from Do not indicate I/O errors when returning from
.Xr read 2 .Xr read 2
or or
.Xr write 2 .Xr write 2
system calls. The caller is assumed to use system calls.
.Li FD_GSTAT The caller is assumed to use
calls in order to inquire about the success of each operation. This .Dv FD_GSTAT
calls in order to inquire about the success of each operation.
This
is intented to allow even erroneous data from bad blocks to be is intented to allow even erroneous data from bad blocks to be
retrieved using normal IO operations. retrieved using normal I/O operations.
.It Li FDOPT_AUTOSEL .It Dv FDOPT_AUTOSEL
Device performs automatic density selection. Unlike the above flags, Device performs automatic density selection.
Unlike the above flags,
this one is read-only. this one is read-only.
.El .El
.It Li FD_SOPTS .It Dv FD_SOPTS
Set device options, see above for their meaning. Third argument is a Set device options, see above for their meaning.
Third argument is a
pointer to pointer to
.Li int . .Vt int .
Drive options will always be cleared when closing the descriptor. Drive options will always be cleared when closing the descriptor.
.It Li FD_DEBUG .It Dv FD_DEBUG
Set the driver debug level. Third argument is a pointer to Set the driver debug level.
.Li int , Third argument is a pointer to
level 0 turns off all debugging. Only applicable if the driver has .Vt int ,
level 0 turns off all debugging.
Only applicable if the driver has
been configured with been configured with
.Pp .Cd "options FDC_DEBUG" .
.Cd options FDC_DEBUG .It Dv FD_CLRERR
.It Li FD_CLRERR Clear the internal low-level error counter.
Clear the internal low-level error counter. Normally, controller-level Normally, controller-level
IO errors are only logged up to I/O errors are only logged up to
.Li FDC_ERRMAX .Dv FDC_ERRMAX
errors (currently defined to 100). This command resets the counter. errors (currently defined to 100).
This command resets the counter.
Requires superuser privileges. Requires superuser privileges.
.It Li FD_READID .It Dv FD_READID
Read one sector ID field from the floppy disk medium. Third argument is Read one sector ID field from the floppy disk medium.
Third argument is
a pointer to a pointer to
.Li struct fdc_readid , .Vt "struct fdc_readid" ,
where the read data will be returned. Can be used to analyze a floppy where the read data will be returned.
Can be used to analyze a floppy
disk medium. disk medium.
.It Li FD_GSTAT .It Dv FD_GSTAT
Return the recent floppy disk controller status, if available. Third Return the recent floppy disk controller status, if available.
Third
argument is a pointer to argument is a pointer to
.Li struct fdc_status , .Vt "struct fdc_status" ,
where the status registers (ST0, ST1, ST2, C, H, R, and N) are being where the status registers (ST0, ST1, ST2, C, H, R, and N) are being
returned. returned.
.Ev EINVAL .Er EINVAL
will be caused if no recent status is available. will be caused if no recent status is available.
.It Li FD_GDTYPE .It Dv FD_GDTYPE
Returns the floppy disk drive type. Third argument is a pointer to Returns the floppy disk drive type.
.Li enum fd_drivetype . Third argument is a pointer to
.Vt "enum fd_drivetype" .
This type is the same as being used in the per-drive configuration This type is the same as being used in the per-drive configuration
flags, or in the CMOS configuration data on IA32 systems. flags, or in the CMOS configuration data on IA32 systems.
.El .El
.Pp
.Sh FILES .Sh FILES
.Bl -tag -width Pa -compact .Bl -tag -width ".Pa /dev/fd*" -compact
.It Pa /dev/fd* .It Pa /dev/fd*
floppy disk device nodes floppy disk device nodes
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr fdcontrol 8 ,
.Xr fdformat 1 , .Xr fdformat 1 ,
.Xr fdread 1 , .Xr fdread 1 ,
.Xr fdwrite 1 , .Xr fdwrite 1 ,
.Xr ioctl 2 , .Xr ioctl 2 ,
.Xr open 2 , .Xr open 2 ,
.Xr read 2 , .Xr read 2 ,
.Xr write 2 .Xr write 2 ,
.Xr fdcontrol 8
.Sh AUTHORS .Sh AUTHORS
.An -nosplit
This man page was initially written by This man page was initially written by
.An Wilko Bulte , .An Wilko Bulte ,
and later vastly rewritten by and later vastly rewritten by