Second round of floppy disk driver documentation updates: document the

changes in the userland utilities.  For fdcontrol(8), i now finally
keep my promise made more than 7 years ago that ``the fdcontrol
utility is currently under development and the user interface will
likely change''. :-)

1 files changed, 251 insertions, 52 deletions

diff --git a/usr.sbin/fdcontrol/fdcontrol.8 b/usr.sbin/fdcontrol/fdcontrol.8
index 8d7e879..8e45c01 100644
--- a/usr.sbin/fdcontrol/fdcontrol.8
+++ b/usr.sbin/fdcontrol/fdcontrol.8
@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (C) 1994 by Joerg Wunsch, Dresden
+.\" Copyright (C) 1994, 2001 by Joerg Wunsch, Dresden
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -26,75 +26,274 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 22, 1994
+.Dd December 25, 2001
 .Os
 .Dt FDCONTROL 8
 .Sh NAME
 .Nm fdcontrol
-.Nd modify floppy disk parameters
+.Nd display and modify floppy disk parameters
 .Sh SYNOPSIS
 .Nm
-.Op Fl d Ar 0|1
-.Ar device
-.Nm
-.Op Fl s
+.Op Fl F
+.Op Fl d Ar dbg
+.Op Fl f Ar fmt
+.Op Fl s Ar fmtstr
+.Op Fl v
 .Ar device
 .Sh DESCRIPTION
-.Nm Fdcontrol
-allows the modification of the run-time behavior of the floppy
-disk device specified by
+The
+.Nm
+utility allows the modification of the run-time behavior of the
+.Xr fdc 4
+driver for the device specified by
+.Ar device .
+.Pp
+Commands are implemented to query the current device density settings
+as well as the underlying device hardware as registered with the
+driver, to manipulate debugging levels, and to adjust the device
+density settings.  All the operations that manipulate the kernel
+settings are restricted to the superuser (by the device driver), while
+all inquiry requests only require read access to
 .Ar device .
-.Ar Device
-should be a character device.
 .Pp
-.Nm Fdcontrol
-currently supports the specification of device parameters for the
-floppy disk drive
-.Fl ( s ,
-also default mode),
-or it allows the modification of the driver debug level, in case the
-floppy driver has been compiled into the kernel with the
-.Em DEBUG
-option set
-.Pq Fl d .
+The
+.Ar device
+argument should always be given as a full path name, e. g.
+.Pa /dev/fd0 .
+.Pp
+.Ss Inquiry commands
+Running the
+.Nm
+utility without any of the optional flags will report the drive type
+that has been registered with the device driver.
+In the shortest form, a single string describing the drive type will
+be returned.  Possible values are:
+.Ql 360K ,
+.Ql 1.2M ,
+.Ql 720K ,
+.Ql 1.44M ,
+.Ql 2.88M ,
+or
+.Ql unknown .
+This information is primarily intented to be easily parsable by
+scripts.
 .Pp
-Since the implications of such actions are considered harmful, the
-underlying
-.Xr ioctl 2
-command is restricted to the super-user.
+In order to add some descriptive text that makes the output better
+human readable, the flag
+.Fl v
+can be added.
 .Pp
-When requesting a new parameter specification, the command asks the
-user for each individual tunable parameter, defaulting to the
-currently used value.
-.Sh DIAGNOSTICS
-Error codes for the underlying
-.Xr ioctl 2
-commands are printed by the
-.Xr warn 3
-facility.
-.Sh BUGS
+Specifying flag
+.Fl F
+will report the device's density settings in a form that is suitable
+as input to the
+.Fl s Ar fmtstr
+option (see below).  Again, together with
+.Fl v ,
+some more text will be returned, including the total capacity of the
+density settings in kilobytes.
+.Ss Debug control
+If the
+.Xr fdc 4
+driver has been configured with the
+.Ql FDC_DEBUG
+option, by default, device debugging information is still disabled
+since it could produce huge amounts of kernel messages.  It needs to
+be turned on using
+.Nm
+together with
+.Fl d Ar 1 ,
+usually immediately before starting an operation on the respective
+device the debug information is wanted for, and later turned off again
+using
+.Fl d Ar 0 .
+Note that the debugging levels are a driver global option that will
+affect any drives and controllers using the
+.Xr fdc 4
+driver, regardless which
+.Ar device
+has been specified on the
+.Nm
+command line.
+.Ss Density control
 The
+.Xr fdc 4
+control utilities support two different options how to specify device
+density settings.  The first form uses
+.Fl f Ar fmt
+to specify the format of the medium in kilobytes.  Depending on the
+underlying drive type, the value is compared against a table of known
+commonly used device density settings for that drive, and if a match
+has been found, those settings will be used.  Currently, the following
+values for the respective drive types are acceptable:
+.Bl -tag -width 2.88M -offset 4
+.It 2.88M and 1.44M drives:
+.TS
+lB lB lB lB lB lB lB
+r l l l l l l.
+KB	sectrac	secsize	ncyls	speed	heads	flags
+1721	21	2 (512)	82	500	2	MFM
+1476	18	2 (512)	82	500	2	MFM
+1440	18	2 (512)	80	500	2	MFM
+1200	15	2 (512)	80	500	2	MFM
+820	10	2 (512)	82	250	2	MFM
+800	10	2 (512)	80	250	2	MFM
+720	9	2 (512)	80	250	2	MFM
+.TE
+.It 1.2M drives:
+.TS
+lB lB lB lB lB lB lB
+r l l l l l l.
+KB	sectrac	secsize	ncyls	speed	heads	flags
+1200	15	2 (512)	80	500	2	MFM
+1232	8	3 (1024)	77	500	2	MFM
+1476	18	2 (512)	82	500	2	MFM
+1440	18	2 (512)	80	500	2	MFM
+1200	15	2 (512)	80	500	2	MFM
+820	10	2 (512)	82	300	2	MFM
+800	10	2 (512)	80	300	2	MFM
+720	9	2 (512)	80	300	2	MFM
+360	9	2 (512)	40	300	2	MFM,2STEP
+640	8	2 (512)	80	300	2	MFM
+.TE
+.It 720K drives:
+.TS
+lB lB lB lB lB lB lB
+r l l l l l l.
+KB	sectrac	secsize	ncyls	speed	heads	flags
+720	9	2 (512)	80	250	2	MFM
+.TE
+.It 360K drives:
+.TS
+lB lB lB lB lB lB lB
+r l l l l l l.
+KB	sectrac	secsize	ncyls	speed	heads	flags
+360	9	2 (512)	40	250	2	MFM
+.TE
+.El
+.Pp
+The second form to specify a device density uses
+.Fl s Ar fmtstr
+to explicitly specify each parameter in detail.  The argument
+.Ar fmtstr
+is a comma-separated list of values of the form:
+.Pp
+.Em sectrac,secsize,datalen,gap,ncyls,speed,heads,f_gap,f_inter,offs2,flags
+.Pp
+The meaning of the parameters is:
+.Bl -tag -width secsize -offset indent
+.It Ar sectrac
+The number of sectors per track.
+.It Ar secsize
+The sector size code, 0 = 128 bytes (or less), 1 = 256 bytes, 2 = 512
+bytes, 3 = 1024 bytes.
+.It Ar datalen
+The actual sector size if the size code is 0, or the (ignored) value
+0xFF for larger size codes.
+.It Ar gap
+The length of the gap 3 parameter for read/write operations.
+.It Ar ncyls
+The number of cylinders.
+.It Ar speed
+The transfer speed in kilobytes per second.  Can be 250, 300, 500, or
+1000, but each drive type only supports a subset of these values.
+.It Ar heads
+The number of heads.
+.It Ar f_gap
+The length of the gap 3 when formatting media.
+.It Ar f_inter
+The sector interleave to be applied when formatting.  0 means no
+interleave, 1 means 1:1 etc.
+.It Ar offs2
+The offset of the sector numbers on side 2 (i. e. head number 1).
+Normally, sector numbering on both sides starts with 1.
+.It Ar flags
+A list from one of the following flag values:
+.Bl -tag -compact -width "+perpend"
+.It Ar +mfm
+Use MFM encoding.
+.It Ar -mfm
+Use FM (single-density) encoding.
+.It Ar +2step
+Use 2 steps per each cylinder (for accessing 40-cylinder media in
+80-cylinder drives).
+.It Ar -2step
+Do not use 2 steps per cylinder, i. e. access each physical cylinder
+of the drive.
+.It Ar +perpend
+Use perpendicular recording (for 2.88 MB media, currently not
+supported).
+.It Ar -perpend
+Use longitudinal recording.
+.El
+.El
+.Pp
+For any missing parameter, the current value will be used, so only
+actual changes need to be specified.  Thus to turn off a flag bit
+(like
+.Ql +mfm
+which is the default for all drive types), the form with a leading
+minus sign must explicitly be used.
+.Sh EXAMPLES
+A simple inquiry about the drive type:
+.Bd -literal
+$ fdcontrol /dev/fd0
+1.44M
+.Ed
+.Pp
+Same as above, but with verbose output.  Note that the result is about
+the
+.Em drive type ,
+as opposed to a
+.Em device density ,
+so it is independent from the actual subdevice being used for
+.Ar device .
+.Bd -literal
+$ fdcontrol -v /dev/fd1.360
+/dev/fd1.360: 1.2M drive (5.25" high-density)
+.Ed
+.\" " <- this one is for Emacs :)
+.Pp
+Inquiry about the density settings of a particular subdevice.
+.Bd -literal
+$ fdcontrol -F /dev/fd0.720
+18,512,0xff,0x1b,80,500,2,0x6c,1,0,+mfm
+.Ed
+.Pp
+Note that just accessing a new subdevice for the first time will clone
+this device using the default density settings for the drive type, as
+explained in
+.Xr fdc 4 .
+Thus, albeit the device name in the example above suggests a 720 KB
+media density, it has actually been initialized (by the driver) to
+1440 KB.  So in order to adjust it for standard 720 KB double-density
+media, one of the following
 .Nm
-command is currently under development.
-It's user interface is rather
-silly and likely to change in future, options should be provided to
-allow anything being modified from the command line.
+command needs to be run:
+.Bd -literal
+# fdcontrol -s 9,,,0x20,,250,,0x50 /dev/fd0.720
+# fdcontrol -f 720 /dev/fd0.720
+.Ed
 .Pp
-The driver does actually support only two debug levels
-(0 and 1),
-where debug level 1 will generate huge amounts of output.
-It is likely
-to overflow the syslog if not used with extreme care.
+As indicated, trailing commas in the parameter list may be omitted.
+.Pp
+In order to access archaic 160 KB single-density (FM encoded) 5.25\"
+media in a modern 1.2M drive, something like the following definition
+would be needed.  (Note that not all controller hardware is actually
+capable of handling FM encoding at all.)
+.Bd -literal
+# fdcontrol -s 16,128,0x80,0x2,40,300,,0x10,,,-mfm,+2step /dev/fd1.1
+.Ed
 .Sh SEE ALSO
-.Xr ioctl 2 ,
-.Xr warn 3 ,
 .Xr fdc 4
 .Sh HISTORY
-.Nm Fdcontrol
-is currently under development.
-It's user interface and overall
-functionality are subjects to future improvements and changes.
+The
+.Nm
+utility appeared in
+.Fx 2.0 ,
+and has been vastly overhauled in
+.Fx 5.0 .
 .Sh AUTHORS
-The program has been contributed by
+The program and this man page have been contributed by
 .An J\(:org Wunsch ,
 Dresden.