mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-21 18:27:22 +00:00
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''. :-)
This commit is contained in:
Joerg Wunsch
parent
9af58b360a
commit
0377dd590e
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=88480
|
|
@ -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
|
||||
.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 .
|
||||
.Pp
|
||||
Since the implications of such actions are considered harmful, the
|
||||
underlying
|
||||
.Xr ioctl 2
|
||||
command is restricted to the super-user.
|
||||
.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
|
||||
The
|
||||
.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.
|
||||
utility allows the modification of the run-time behavior of the
|
||||
.Xr fdc 4
|
||||
driver for the device specified by
|
||||
.Ar device .
|
||||
.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.
|
||||
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 .
|
||||
.Pp
|
||||
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
|
||||
In order to add some descriptive text that makes the output better
|
||||
human readable, the flag
|
||||
.Fl v
|
||||
can be added.
|
||||
.Pp
|
||||
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 needs to be run:
|
||||
.Bd -literal
|
||||
# fdcontrol -s 9,,,0x20,,250,,0x50 /dev/fd0.720
|
||||
# fdcontrol -f 720 /dev/fd0.720
|
||||
.Ed
|
||||
.Pp
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue