From 0377dd590e3866305cd5fdfb4990855cfcbd0dc5 Mon Sep 17 00:00:00 2001 From: Joerg Wunsch Date: Tue, 25 Dec 2001 21:21:18 +0000 Subject: 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''. :-) --- usr.sbin/fdcontrol/fdcontrol.8 | 303 ++++++++++++++++++++++++++++++++++------- 1 file changed, 251 insertions(+), 52 deletions(-) (limited to 'usr.sbin/fdcontrol/fdcontrol.8') diff --git a/usr.sbin/fdcontrol/fdcontrol.8 b/usr.sbin/fdcontrol/fdcontrol.8 index 8d7e87903117..8e45c01500be 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. -- cgit v1.2.3