.TH superformat 1 "27Jan21" fdutils-5.6
.SH Name
superformat - format floppies
'\" t
.de TQ
.br
.ns
.TP \\$1
..

.tr \(is'
.tr \(if`
.tr \(pd"

.SH Note
This manpage has been automatically generated from fdutils's texinfo
documentation.  However, this process is only approximative, and some
items, such as cross-references, footnotes and indices are lost in this
translation process.  Indeed, these items have no appropriate
representation in the manpage format.  Moreover, only the items specific
to each command have been translated, and the general information about
fdutils has been dropped in the manpage version.  Thus I strongly advise
you to use the original texinfo doc.
.TP
* \ \ 
To generate a printable copy from the texinfo doc, run the following
commands:
 
.nf
.ft 3
.in +0.3i
    ./configure; make dvi; dvips fdutils.dvi
.fi
.in -0.3i
.ft R
 
\&\fR
.TP
* \ \ 
To generate a HTML copy,  run:
 
.nf
.ft 3
.in +0.3i
    ./configure; make html
.fi
.in -0.3i
.ft R
 
\&\fRA pre-made HTML can be found at:
\&\fR\&\f(CW\(ifhttp://www.tux.org/pub/knaff/fdutils\(is\fR
.TP
* \ \ 
To generate an info copy (browsable using emacs' info mode), run:
 
.nf
.ft 3
.in +0.3i
    ./configure; make info
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
The texinfo doc looks most pretty when printed or as HTML.  Indeed, in
the info version certain examples are difficult to read due to the
quoting conventions used in info.
.SH Description
.PP
 
.nf
.ft 3
.in +0.3i
\&\fR\&\f(CWsuperformat [\fR\&\f(CW\-D \fIdos\-drive\fR\&\f(CW] [\fR\&\f(CW\-v \fIverbosity\-level\fR\&\f(CW] [\fR\&\f(CW\-b \fIbegin\-track\fR\&\f(CW]
[\fR\&\f(CW\-e \fIend\-track\fR\&\f(CW] [\fR\&\f(CW\-\-superverify] [\fR\&\f(CW\-\-dosverify]
[\fR\&\f(CW\-\-noverify] [\fR\&\f(CW\-\-verify_later] [\fR\&\f(CW\-\-first\-sector\-number \fIn\fR\&\f(CW] [\fR\&\f(CW\-\-zero\-based]
[\fR\&\f(CW\-G \fIformat\-gap\fR\&\f(CW] [\fR\&\f(CW\-F \fIfinal\-gap\fR\&\f(CW] [\fR\&\f(CW\-i \fIinterleave\fR\&\f(CW] [\fR\&\f(CW\-c \fIchunksize\fR\&\f(CW]
[\fR\&\f(CW\-g \fIgap\fR\&\f(CW] [\fR\&\f(CW\-\-absolute\-skew \fIabsolute\-skew\fR\&\f(CW] [\fR\&\f(CW\-\-head\-skew \fIhead\-skew\fR\&\f(CW]
[\fR\&\f(CW\-\-track\-skew \fItrack\-skew\fR\&\f(CW] [\fR\&\f(CW\-\-biggest\-last] \fIdrive\fR\&\f(CW [\fImedia\-description\fR\&\f(CW]
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
\&\fR\&\f(CWsuperformat\fR is used to format disks with a capacity of up to
1992K HD or 3984K ED.  See section Extended formats, for a detailed
description of these formats. See section Media description, for a detailed
description of the syntax for the media description.  If no media
description is given, superformat formats a disk in the highest
available density for that drive, using standard parameters (i.e. no
extra capacity formats).
.PP
When the disk is formatted, \fR\&\f(CWsuperformat\fR automatically invokes
\&\fR\&\f(CWmformat\fR in order to put an MS-DOS filesystem on it. You may
ignore this filesystem, if you don't need it.
.PP
Superformat allows one to format 2m formats.  Be aware, however, that these
\&\fR\&\f(CW2m\fR formats were specifically designed to hold an MS-DOS
filesystem, and that they take advantage of the fact that the MS-DOS
filesystem uses redundant sectors on the first track (the FAT, which is
represented twice). The second copy of the FAT is \fInot\fR represented
on the disk.
.PP
High capacity formats are sensitive to the exact rotation speed of the
drive and the resulting difference in raw capacity.  That's why
\&\fR\&\f(CWsuperformat\fR performs a measurement of the disks raw capacity
before proceeding with the formatting.  This measurement is rather time
consuming, and can be avoided by storing the relative deviation of the
drive capacity into the drive definition file file. See section Drive
descriptions, for more details on this file. The line to be inserted
into the drive definition file is printed by superformat after
performing its measurement.  However, this line depends on the drive and
the controller.  Do not copy it to other computers.  Remove it before
installing another drive or upgrade your floppy controller.  Swap the
drive numbers if you swap the drives in your computer.
.PP
.SH Common\ Options
Many options have a long and a short form.
.TP
\&\fR\&\f(CW\-h\fR\ 
.TQ
\&\fR\&\f(CW\-\-help\fR
Print the help.
.TP
\&\fR\&\f(CW\-D\ \fIdrive\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-dosdrive\ \fIdos\-drive\fR\&\f(CW\fR
Selects DOS drive letter for \fR\&\f(CWmformat\fR (for example \fR\&\f(CWa:\fR or
\&\fR\&\f(CWb:\fR).  The colon may be omitted.  The default is derived from the
minor device number.  If the drive letter cannot be guessed, and is not
given on the command line, \fR\&\f(CWmformat\fR is skipped.
.TP
\&\fR\&\f(CW\-v\ \fIverbosity\-level\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-verbosity\ \fIverbosity\-level\fR\&\f(CW\fR
Sets the verbosity level. 1 prints a dot for each formatted track. 2
prints a changing sign for each formatted track (\- for formatting the
first head, = for formatting the second head, x for verifying the
first head, and + for verifying the second head). 3 prints a complete
line listing head and track. 6 and 9 print debugging information.
.TP
\&\fR\&\f(CW\-\-superverify\fR\ 
Verifies the disk by first reading the track, than writing a pattern of
U's, and then reading it again.  This is useful as some errors only show
up after the disk has once been written.  However, this is also slower.
.TP
\&\fR\&\f(CW\-B\fR\ 
.TQ
\&\fR\&\f(CW\-\-dosverify\fR
Verifies the disk using the \fR\&\f(CWmbadblocks\fR program.
\&\fR\&\f(CWmbadblocks\fR marks the bad sectors as bad in the FAT.  The
advantage of this is that disks which are only partially bad can still
be used for MS-DOS filesystems.
.TP
\&\fR\&\f(CW\-V\fR\ 
.TQ
\&\fR\&\f(CW\-\-verify_later\fR
Verifies the whole disk at the end of the formatting process instead
of at each track. Verifying the disk at each track has the advantage
of detecting errors early on.
.TP
\&\fR\&\f(CW\-f\fR\ 
.TQ
\&\fR\&\f(CW\-\-noverify\fR
Skips the verification altogether.
.TP
\&\fR\&\f(CW\-\-print\-drive\-deviation\fR\ 
Does not format, but prints the drive deviation. If file /etc/driveprm
exists and provides a deviation for the drive, nothing is printed and
the disk is not formatted.
.PP
.SH Advanced\ Options
Usually, superformat uses sensible default values for these options,
which you normally don't need to override.  They are intended for expert
users.  Most of them should only be needed in cases where the hardware
or superformat itself has bugs.
.IP
.TP
\&\fR\&\f(CW\-b\ \fIbegin\-track\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-begin_track\ \ \fIbegin\-track\fR\&\f(CW\fR
Describes the track where to begin formatting.  This is useful if the
previous formatting failed halfway through.  The default is 0.
.TP
\&\fR\&\f(CW\-e\ \fIend\-track\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-end_track\ \fIend\-track\fR\&\f(CW\fR
Describes where to stop formatting. \fIend_track\fR is the last track to
be formatted plus one. This is mainly useful for testing purposes. By
default, this is the same as the total number of tracks.  When the
formatting stops, the final skew is displayed (to be used as absolute
skew when you'll continue).
.TP
\&\fR\&\f(CW\-S\ \fIsizecode\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-sizecode\ \fIsizecode\fR\&\f(CW\fR
Set the sector size to be used. The sector size is 128 * (2 ^
\&\fIsizecode\fR).  Sector sizes below 512 bytes are not supported, thus
sizecode must be at least 2. By default 512 is assumed, unless you ask
for more sectors than would fit with 512 bytes.
.TP
\&\fR\&\f(CW\-\-stretch\ \fIstretch\fR\&\f(CW\fR\ 
Set the stretch factor. The stretch factor describes how many physical
tracks to skip to get to the next logical track (2 ^ \fIstretch\fR).  On
double density 5 1/4 disks, the tracks are further apart from each
other.
.TP
\&\fR\&\f(CW\-G\ \fIfmt\-gap\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-format_gap\ \fIfmt\-gap\fR\&\f(CW\fR
Set the formatting gap. The formatting gap tells how far the sectors
are away from each other. By default, this is chosen so as to evenly
distribute the sectors along the track.
.TP
\&\fR\&\f(CW\-F\ \fIfinal\-gap\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-final_gap\ \fIfinal\-gap\fR\&\f(CW\fR
Set the formatting gap to be used after the last sector.
.TP
\&\fR\&\f(CW\-i\ \fIinterleave\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-interleave\ \fIinterleave\fR\&\f(CW\fR
Set the sector interleave factor.
.TP
\&\fR\&\f(CW\-c\ \fIchunksize\fR\&\f(CW\fR\ 
.TQ
\&\fR\&\f(CW\-\-chunksize\ \fIchunksize\fR\&\f(CW\fR
Set the size of the chunks. The chunks are small auxiliary sectors
used during formatting. They are used to handle heterogeneous sector
sizes (i.e. not all sectors have the same size) and negative
formatting gaps.
.TP
\&\fR\&\f(CW\-\-biggest\-last\fR\ 
For MSS formats, make sure that the biggest sector is last on the track.
This makes the format more reliable on drives which are out of spec.
.TP
\&\fR\&\f(CW\-\-first\-sector\-number\ \fIn\fR\&\f(CW\fR\ 
Formats the disk with sector numbers starting at \fIn\fR, rather than
1. Certain CP/M boxes or Music synthesizers use this format.
.TP
\&\fR\&\f(CW\-\-zero\-based\fR\ 
Shorthand for \fR\&\f(CW\-\-first\-sector\-number 0\fR
.PP
.SH Sector\ skewing\ options
.PP
In order to maximize the user data transfer rate, the sectors are
arranged in such a way that sector 1 of the new track/head comes under
the head at the very moment when the drive is ready to read from that
track, after having read the previous track. Thus the first sector of
the second track is not necessarily near the first sector of the first
track.  The skew value describes for each track how far sector number
1 is away from the index mark. This skew value changes for each head
and track. The amount of this change depends on how fast the disk
spins, and on how much time is needed to change the head or the track.
.TP
\&\fR\&\f(CW\-\-absolute_skew\ \fIabsolute\-skew\fR\&\f(CW\fR\ 
.IP
Set the absolute skew. This skew value is used for the first formatted
track.  It is expressed in raw bytes.
.TP
\&\fR\&\f(CW\-\-head_skew\ \fIhead\-skew\fR\&\f(CW\fR\ 
.IP
Set the head skew. This is the skew added for passing from head 0 to
head 1.  It is expressed in raw bytes.
.TP
\&\fR\&\f(CW\-\-track_skew\ \fItrack\-skew\fR\&\f(CW\fR\ 
.IP
Set the track skew. This is the skew added for seeking to the next
track.  It is expressed in raw bytes.
.PP
Example: (absolute skew=3, head skew=1, track skew=2)
.PP
 
.nf
.ft 3
.in +0.3i
track 0 head 0: 4,5,6,1,2,3	(skew=3)
track 0 head 1: 3,4,5,6,1,2	(skew=4)
\&\&
track 1 head 0: 1,2,3,4,5,6	(skew=0)
track 1 head 1: 6,1,2,3,4,5	(skew=1)
\&\&
track 2 head 0: 4,5,6,1,2,3	(skew=3)
track 2 head 1: 3,4,5,6,1,2	(skew=4)
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
N.B. For simplicity's sake, this example expresses skews in units of
sectors. In reality, superformat expects the skews to be expressed in
raw bytes.
.PP
.SH Media description
Please see the Media description section in the full fdutils
documentation:
.TQ
- Texinfo documentation (info fdutils)
.TQ
- HTML documentation in /usr/share/doc/fdutils/Fdutils.html
.TQ
- or DVI documentation in /usr/share/doc/fdutils/Fdutils.dvi.gz
.PP
.SH Examples
In all the examples of this section, we assume that drive 0 is a 3 1/2
and drive 1 a 5 1/4.
.PP
The following example shows how to format a 1440K disk in drive 0:
 
.nf
.ft 3
.in +0.3i
superformat /dev/fd0 hd
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
The following example shows how to format a 1200K disk in drive 1:
 
.nf
.ft 3
.in +0.3i
superformat /dev/fd1 hd
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
The following example shows how to format a 1440K disk in drive 1:
 
.nf
.ft 3
.in +0.3i
superformat /dev/fd1 hd sect=18
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
The following example shows how to format a 720K disk in drive 0:
 
.nf
.ft 3
.in +0.3i
superformat /dev/fd0 dd
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
The following example shows how to format a 1743K disk in drive 0 (83
cylinders times 21 sectors):
 
.nf
.ft 3
.in +0.3i
superformat /dev/fd0 sect=21 cyl=83
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
The following example shows how to format a 1992K disk in drive 0 (83
cylinders times 2 heads times 12 KB per track)
 
.nf
.ft 3
.in +0.3i
superformat /dev/fd0 tracksize=12KB cyl=83 mss
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
The following example shows how to format a 1840K disk in drive 0. It
will have 5 2048-byte sectors, one 1024-byte sector, and one 512-byte
sector per track:
 
.nf
.ft 3
.in +0.3i
superformat /dev/fd0 tracksize=23b mss 2m ssize=2KB
.fi
.in -0.3i
.ft R
 
\&\fR
.PP
All these formats can be autodetected by mtools, using the floppy
driver's default settings.
.PP
.SH Troubleshooting
.TP
\&\fR\&\f(CWFDC\ busy,\ sleeping\ for\ a\ second\fR\ 
When another program accesses a disk drive on the same controller as the
one being formatted, \fR\&\f(CWsuperformat\fR has to wait until the other
access is finished.  If this happens, check whether any other program
accesses a drive (or whether a drive is mounted), kill that program (or
unmount the drive), and the format should proceed normally.
.TP
\&\fR\&\f(CWI/O\ errors\ during\ verification\fR\ 
Your drive may be too far out of tolerance, and you may thus need to
supply a margin parameter.  Run \fR\&\f(CWfloppymeter\fR (see section  floppymeter)
to find out an appropriate value for this parameter, and add the
suggested \fR\&\f(CWmargin\fR parameter to the command line
.PP
.SH Bugs
Opening up new window while \fR\&\f(CWsuperformat\fR is running produces
overrun errors. These errors are benign, as the failed operation is
automatically retried until it succeeds.
.SH See Also
Fdutils' texinfo doc