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''. :-)

2 files changed, 312 insertions, 117 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.
diff --git a/usr.sbin/fdformat/fdformat.1 b/usr.sbin/fdformat/fdformat.1
index d568181..ef542a7 100644
--- a/usr.sbin/fdformat/fdformat.1
+++ b/usr.sbin/fdformat/fdformat.1
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 2, 2001
+.Dd December 25, 2001
 .Os
 .Dt FDFORMAT 1
 .Sh NAME
@@ -32,84 +32,74 @@
 .Nd format floppy disks
 .Sh SYNOPSIS
 .Nm
-.Op Fl q
-.Op Fl y
-.Op Fl v | Fl n
-.Op Fl f Ar capacity
-.Op Fl c Ar cyls
-.Op Fl s Ar secs
-.Op Fl h Ar heads
-.Nm
-.Op Fl r Ar rate
-.Op Fl g Ar gap3len
-.Op Fl i Ar intleave
-.Op Fl S Ar secshft
-.Op Fl F Ar fillbyte
-.Op Fl t Ar steps_per_track
-.Ar device_name
+.Op Fl F Ar fill
+.Op Fl f Ar fmt
+.Op Fl s Ar fmtstr
+.Op Fl nqvy
+.Ar device
 .Sh DESCRIPTION
-.Nm Fdformat
-formats a floppy disk at device
-.Ar device_name .
-.Ar Device_name
-may be given either with a full path
+The
+.Nm
+utility formats a floppy disk at
+.Ar device ,
+where
+.Ar device
+may either be given as a full path
 name of a device node for a floppy disk drive
 (e.g.\&
 .Pa /dev/fd0 ) ,
-or a default name in an abbreviated form
+or using an abbreviated name that will be looked up
+under
+.Pa /dev
 (e.g.\&
 .Em fd0 ) .
-In the latter case, the name is constructed by prepending
-.Pa /dev/
-and appending a
-.Em .capacity
-to the
-.Ar device_name .
-Note that any geometry constraints of the device node
-(minor device number)
-are meaningless, since they're overridden by
-.Nm .
 .Pp
 The options are as follows:
 .Bl -tag -width 10n -offset indent
+.It Fl F Ar fill
+Use
+.Ar fill
+as the fill byte for newly formatted sectors.
+.Ar fill
+must be a number in the range 0 through 255 using common C
+language notation.  The default value is
+.Em 0xf5 .
+.It Fl f Ar fmt
+Specify the density settings for a
+.Ar fmt
+kilobyte format, as described in
+.Xr fdcontrol 8 .
+.It Fl s Ar fmtstr
+Specify the density settings using explicit parameters, as
+described in
+.Xr fdcontrol 8 .
+.It Fl n
+Don't verify floppy after formatting.
 .It Fl q
 Suppress any normal output from the command, and don't ask the
 user for a confirmation whether to format the floppy disk at
-.Ar device_name .
-.It Fl y
-Suppress confirmation request by automagically responding "yes", but still
-report format status.
-.It Fl f Ar capacity
-The normal way to specify the desired formatting parameters.
-.Ar Capacity
-is the number of kilobytes to format.
-Valid choices are 360, 720, 800, 820,
-1200, 1440, 1480 or 1720.
-.It Fl n
-Don't verify floppy after formatting.
+.Ar device .
 .It Fl v
 Don't format, verify only.
-.It Fl c Ar cyls
-Number of cylinders: 40 or 80.
-.It Fl s Ar secs
-Number of sectors per track: 9, 10, 15 or 18.
-.It Fl h Ar heads
-Number of floppy heads: 1 or 2.
-.It Fl r Ar rate
-Data rate: 250, 300 or 500 kbps.
-.It Fl g Ar gap3len
-Gap length.
-.It Fl i Ar intleave
-Interleave factor.
-.It Fl S Ar secshft
-Sector size: 0=128, 1=256, 2=512 bytes.
-.It Fl F Ar fillbyte
-Fill byte.
-.It Fl t Ar steps_per_track
-Number of steps per track.
-An alternate method to specify the geometry data to write to the floppy disk.
+.It Fl y
+Do not ask for confirmation whether to format the floppy disk but
+still report formatting status.
 .El
 .Pp
+For non-autoselecting subdevices, neither
+.Fl f Ar fmt
+nor
+.Fl s Ar fmtstr
+may be specified, since the preconfigured media density settings
+from the kernel driver will always be used.  However, if
+.Ar device
+is a device with automatic media density selection (see
+.Xr fdc 4 ) ,
+both methods can be used to override the density settings for the
+newly formatted medium (without permanently changing the density
+settings of
+.Ar device ) .
+.Pp
 If the
 .Fl q
 flag has not been specified, the user is asked for a confirmation
@@ -121,7 +111,7 @@ must be given.
 .Pp
 Note that
 .Nm
-does only perform low-level formatting.  In case you wish to create
+does only perform low-level formatting.  In order to create
 a file system on the medium, see the commands
 .Xr newfs 8
 for an
@@ -144,7 +134,8 @@ while it's being verified, and if an error has been detected, it
 will finally change to
 .Sq Em E .
 Detailed status information (cylinder, head and sector number, and the
-exact cause of the error) will then be printed for up to 10 errors.
+exact cause of the error) will be printed for up to 10 errors after the
+entire formatting process has completed.
 .Pp
 An exit status of 0 is returned upon successful operation.
 Exit status
@@ -153,6 +144,7 @@ of 2 reflects invalid arguments given to the program (along with an
 appropriate information written to diagnostic output).
 .Sh SEE ALSO
 .Xr fdc 4 ,
+.Xr fdcontrol 8 ,
 .Xr newfs 8 ,
 .Xr newfs_msdos 8
 .Sh HISTORY
@@ -165,6 +157,10 @@ floppy disk driver.
 It later became part of the
 .Fx 1.1
 system.
+Starting with
+.Fx 5.0 ,
+it uses the unified density specifications as described in
+.Xr fdcontrol 8 .
 .Sh AUTHORS
 .An -nosplit
 The program has been contributed by