Ubuntu Manpage: mkdisk - make a blank emulated floppy or hard disk for xtrs, or add/remove an emulated

Name

       mkdisk  -  make  a  blank emulated floppy or hard disk for xtrs, or add/remove an emulated
       write-protect tab

Synopsis

       mkdisk -1 [-f] filename

       mkdisk [-3] [-f] filename

       mkdisk -k [-s sides] [-d density] [-8] [-i] [-f] filename

       mkdisk -h [-c cyl] [-s sec] [-g gran] [-d dcyl] [-S] [-f] filename

       mkdisk {-p|-u} {-1|-3|-k|-h} filename

Description

The mkdisk program is part of the xtrs package. It has two distinct functions:

• It can make a blank (unformatted) emulated floppy or hard drive in a file.

• With the -p or -u flag, it can turn the write-protect flag on or off for an
existing emulated floppy or hard drive file. See xtrs(1) for background
information.

The conventional file extensions are .dsk for emulated floppies and .hdv for “HDV”
emulated hard drives, but mkdisk does not enforce this convention; you can use any
filename. Other extensions sometimes used for emulated floppies are .jv1, .jv3, .8in, and
.dmk.

By default, when creating disk image files, and if the system's underlying fopen(3)
library function supports this ISO C11 feature, mkdisk refuses to overwrite an existing
file called filename. The -f (“force”) option overrides this default, “clobbering”
filename.

Making Emulated Floppies
With the -1 flag, mkdisk makes an unformatted emulated floppy of type JV1. Besides -f, no
additional flags are accepted.

With the -3 flag (which is the default and should normally be used), mkdisk makes an
unformatted emulated floppy of type JV3. Besides -f, no additional flags are accepted.

With the -k flag, mkdisk makes an unformatted emulated floppy of type DMK. With -k, the
optional flags -s, -d, -8, and -i can be used to give the emulated floppy special
properties. Specifying -s1 limits the floppy to one side; with -s2 (the default), the
floppy can be formatted as either one- or two-sided. Specifying -d1 limits the floppy to
single-density; with -d2 (the default), the floppy can be formatted in either single- or
double-density. Specifying -8 allows the floppy to be formatted in an emulated 8" drive;
by default it will work properly only in an emulated 5¼" drive. Setting -s1 or -d1 saves
space after the floppy is formatted; setting -8 consumes additional space. Specifying -i
activates a peculiar feature in some TRS-80 emulators that causes each formatted sector to
appear to be both single- and double-density.

Making Emulated Hard Drives
With the -h flag, mkdisk makes an unformatted emulated hard drive with cyl cylinders, sec
sectors, and gran granules (LDOS allocation units) per cylinder. The hard drive will have
cylinder number dcyl marked for use as its directory.

You will usually want to use the default values for all these parameters. The default is
202 cylinders, 256 sectors per cylinder (that is, 8 heads and 32 sectors per track), and 8
granules per cylinder. This is the largest hard drive that can be used by all LDOS/LS-DOS
operating systems without partitioning the drive or patching the FORMAT command. The
details on what nondefault values are possible vary, depending on which of xtrs's two hard
drive emulations you are using and which other emulators you want to be compatible with,
and it is probably best not to delve into these complexities, but read on if you really
want to.

For cyl, the number of cylinders on the drive, the default value is 202, the minimum is 3,
and the maximum that can be represented in the HDV file's header is 256. You can use 203
cylinders with LDOS and LS-DOS if you format the drive with Model 4 LS-DOS; a minor bug in
Model I/III FORMAT/CMD prevents more than 202 cylinders from being formatted, but the
system can use 203 thereafter. 203 cylinders is the absolute maximum for LDOS/LS-DOS
drivers that do not support partitioning, including the emulator-specific drivers supplied
with xtrs (XTRSHARD/DCT), with Matthew Reed's emulator (HARD/CMD), and with David Keil's
emulator (EHARD/DCT).

In xtrs 4.1 and later, and in David Keil's emulator version 6.0 and later, a true
emulation of Radio Shack's WD1010-based hard disk controller is also available, which
works with the native drivers for the original hardware, such as RSHARDx/DCT and the hard
disk drivers for NEWDOS and CP/M. In xtrs, the WD1010 emulation ignores the maximum
number of cylinders specified in the HDV file's header and allows the driver to format up
to 65536 cylinders. This may be useful if your drivers support partitioning (but why
would anyone want to partition an emulated hard drive instead of just making two smaller
ones?), or if your operating system supports more than 203 cylinders per partition. Note
that although RSHARDx/DCT allows up to 406 cylinders per partition, if you use more than
203, the maximum number of sectors per cylinder is limited to 128, so you gain nothing;
the maximum size of a partition is still the same.

For sec, the number of sectors per cylinder, the default value is 256, the maximum is 256,
and the minimum is 4. There are some restrictions on the values that will work. For the
greatest portability, choose a value that is divisible by 32. With xtrs's XTRSHARD/DCT
and David Keil's EHARD/DCT, any value is allowed that can be evenly divided into granules;
see the next paragraph. With Matthew Reed's HARD/CMD, if sec is greater than 32, it must
be divisible by 32. With the emulation of a real WD1010 in newer versions of xtrs (and
probably David Keil's emulator too), sec must always be divisible by 32, because we always
emulate a drive with 32 sectors per track and from 1 to 8 heads (tracks per cylinder).
The RSHARDx/DCT driver assumes that there are always 32 sectors per track.

For gran, the default value is 8, the maximum is 8, and the minimum is 1. In addition, it
is necessary that sec be evenly divisible by gran, and that sec÷gran be less than or equal
to 32. This value is used only with the emulator-specific drivers listed above; it is
ignored when xtrs is using native hardware drivers such as RSHARDx/DCT.

The maximum size of a hard drive image is controlled by cyl and sec: it can be at most
cyl×sec 256-byte sectors. The image file starts out small and grows as you write to more
cylinders. The allocation efficiency is controlled by the granule size: LDOS allocates
file space in granules. Therefore (1) gran should always be set as large as possible and
(2) reducing sec, thereby making the granules smaller, reduces space wasted due to
fragmentation but limits the maximum size of the drive.

Seeing that the maximum unpartitioned drive size is less than 13 MiB and that the maximum
granule size is only 8 kiB, wasted space should not be much of a concern for most xtrs
users. Therefore the default parameters have been chosen to give you the largest drive
possible without partitioning.

Embedding the file name in a hard disk image
Matthew Reed's hard drive image file format contains an eight-character field for storing
the filename of the hard drive image itself. mkdisk simply uses the given filename as
this within-image filename. This works best if filename specifies a short file name in
the current working directory. Since modern operating systems permit filenames much
longer than eight characters, historically versions of mkdisk would deliberately “spill”
the remaining characters of filename into the reserved structure field following the
filename (see Technical data, below).

There were two problems with the foregoing approach:

• Modern versions of the standard C library such as glibc will detect the overflow of
the destination buffer, emit a lengthy, technical, frightening diagnostic, and
abort the program immediately. mkdisk itself offered no explanation.

• mkdisk also did not do any checking to see if the filename string copy might
overflow the subsequent buffer, the reserved area.

Now, mkdisk by default writes a truncated (if necessary) copy of filename to the hard disk
image file header; a warning diagnostic is emitted in that event.

With the -S option, mkdisk simulates the old behavior, up to the end of the reserved area.
In this “spill mode”, a warning diagnostic is emitted if spillage occurs, and the program
aborts with an error if the filename is too long to fit in the filename and reserved
fields combined.

For maximum portability of your hard drive images, use only ASCII-encoded eight-character
filenames in the current working directory. Omit control characters in the range
\x00-\x1f and \x7f. These are not “8.3” file names; the “.” character, if used, counts
toward the eight-character limit.

Write Protection
With the -p flag, mkdisk turns on write protection for an existing emulated floppy or hard
drive. It turns off all Unix write permission bits on the file, and (except for JV1
floppies) also sets a write-protected flag inside the file.

With the -u flag, mkdisk turns off write protection for an existing emulated floppy or
hard drive. It turns on Unix write permissions to the file, masked by your current umask
and the file's current read permissions. It also clears a write-protected flag inside the
file (except on JV1 floppies, which don't have such a flag).

mkdisk currently does not have code to auto-recognize file formats, so the -p or -u flag
must be accompanied by either -1 (JV1), -3 (JV3), -k (DMK), or -h (hard disk) to identify
the file format. There is also no checking for the correct file format, so if you give
the wrong flag, the wrong byte inside your file will be changed.

Technical data
The JV1 format is just an array of 256-byte sectors, in the order (track 0 sector 0, track
0 sector 1, ... track 0 sector 9, track 1 sector 0, ...). It can represent only single-
sided, single-density floppies. The directory is assumed to be track 17.

The original JV3 format is documented in the printed manual for Jeff Vavasour's commercial
Model III/4 emulator. The xtrs implementation includes some extensions.

Full documentation for both JV1 and JV3 can be found in Common File Formats for Emulated
TRS-80 Floppy Disks ⟨http://www.tim-mann.org/trs80/dskspec.html⟩ at Tim Mann's TRS-80
site. A copy of this HTML file is also included in the xtrs distribution.

The DMK format was documented in a file on David Keil's web site, now available via the
Internet Archive ⟨https://web.archive.org/web/20010128070200/http://discover-net.net/
~dmkeil/trsdoc.htm#Technical⟩; this file is also included with his emulator. Some points
are worth bearing in mind, particularly if you're attempting to work with copy-protected
TRS-80 disks:

• If neither the single-density nor the ignore-density option is set and single-
density data is recorded, each single density byte is written twice (i.e., the four
bytes 12345678 would be written as 1212343456567878). This ensures that when
single- and double-density sectors are mixed, each type occupies the correct
relative amount of space in the track.

• Bit 15 of an IDAM offset is 1 if the sector is double-density, 0 if single-density.
Bit 14 is reserved; it currently must be 0. The actual offset is in bits 13-0.
These offsets are relative to the start of the track header, they must be in
ascending order (I hope!!), and an offset of 0 or 0xffff terminates the list.

An HDV (hard disk) image has the following format. This information is based on email
from Matthew Reed. There is an initial 256-byte header block, followed by an array of
sectors. The geometry of the drive is defined in the header block, which looks like this
(from reed.h):

/* Matthew Reed's hard drive format. Thanks to Matthew for providing
documentation. The comments below are copied from his mail
messages, with some additions. */
/* $Id: reed.h,v 1.2 2008/06/26 04:39:56 mann Exp $ */

typedef struct {
Uchar id1; /* 0: Identifier #1: 56H */
Uchar id2; /* 1: Identifier #2: CBH */
Uchar ver; /* 2: Version of format: 10H = version 1.0 */
Uchar cksum; /* 3: Simple checksum:
To calculate, add together bytes 0 to 31
of header (excepting byte 3), then XOR
result with 4CH */
Uchar blks; /* 4: Number of 256 byte blocks in header:
should be 1 */
Uchar mb4; /* 5: Not used, but HDFORMAT sets to 4 */
Uchar media; /* 6: Media type: 0 for hard disk */
Uchar flag1; /* 7: Flags #1:
bit 7: Write protected: 0 for no, 1 for
yes [xtrshard/dct ignores for now]
bit 6: Must be 0
bit 5 - 0: reserved */
Uchar flag2; /* 8: Flags #2: reserved */
Uchar flag3; /* 9: Flags #3: reserved */
Uchar crtr; /* 10: Created by:
14H = HDFORMAT
42H = xtrs mkdisk
80H = Cervasio xtrshard port to Vavasour
M4 emulator */
Uchar dfmt; /* 11: Disk format: 0 = LDOS/LS-DOS */
Uchar mm; /* 12: Creation month: mm */
Uchar dd; /* 13: Creation day: dd */
Uchar yy; /* 14: Creation year: yy (offset from 1900) */
Uchar res1[12]; /* 15 - 26: reserved */
Uchar dparm; /* 27: Disk parameters:
(unused with hard drives)
bit 7: Density: 0 = double, 1 = single
bit 6: Sides: 0 = one side, 1 = 2 sides
bit 5: First sector: 0 if sector 0,
1 if sector 1
bit 4: DAM convention: 0 if normal
(LDOS), 1 if reversed (TRSDOS 1.3)
bit 3 - 0: reserved */
Uchar cyl; /* 28: Number of cylinders per disk */
Uchar sec; /* 29: Number of sectors per track (floppy);
cyl (hard) */
Uchar gran; /* 30: Number of granules per track (floppy);
gran (hard) */
Uchar dcyl; /* 31: Directory cylinder [mkdisk sets to 1;
xtrs ignores] */
char label[32]; /* 32: Volume label: 31 bytes terminated by 0 */
char filename[8]; /* 64 - 71: 8 characters of filename (without
extension) [Cervasio addition. xtrs
actually doesn't limit this to 8
chars or strip the extension] */
Uchar res2[184]; /* 72 - 255: reserved */
} ReedHardHeader;

Authors

       mkdisk was written by Timothy Mann (see ⟨http://tim-mann.org/⟩).

       The  floppy  file  formats here called JV1 and JV3 were developed by Jeff Vavasour for his
       MS-DOS-based Model I and Model III/4 emulators (respectively).   They  have  become  a  de
       facto standard in the TRS-80 emulation community, and much TRS-80 software is available on
       the Internet in .dsk format.  Thanks to Jeff for designing and documenting the formats.

       The format here called DMK was developed by  David  Keil  for  his  MS-DOS-based  Model  4
       emulator.   This format has the advantage that it can represent essentially everything the
       original TRS-80 floppy disk controllers can write, including all forms of  copy  protected
       disk.  Thanks to David for designing and documenting this format.

       The  hard  drive format was developed by Matthew Reed for his MS-DOS-based Model I/III and
       Model 4 emulators.  I have duplicated his format to allow users to exchange HDV hard drive
       images  between  xtrs and Matthew's emulators.  Thanks to Matthew for designing the format
       and providing documentation.

Name

Synopsis

Description

Authors

See also