Provided by: xtrs_4.9c-3.2ubuntu3_amd64 bug

Name

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

Syntax

       mkdisk -1 filename
       mkdisk [-3] filename
       mkdisk -k [-s sides] [-d density] [-8] [-i] filename
       mkdisk -h [-c cyl] [-s sec] [-g gran] filename
       mkdisk {-p|-u} {-1|-3|-k|-h} filename

Description

       The mkdisk program is part of the xtrs(1) package.  It has two distinct functions: (1)  It
       can  make  a blank (unformatted) emulated floppy or hard drive in a file.  (2) 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 the xtrs man page for background information.

       The conventional file extensions are .dsk for emulated floppies and .hdv for 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.

Making Emulated Floppies

       With  the -1 flag, mkdisk makes an unformatted emulated floppy of type JV1.  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.  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 dir 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 wasted space due to
       fragmentation but limits the maximum size of the drive.

       Seeing that the maximum unpartitioned drive size is less than 13 MB and that  the  maximum
       granule  size  is  only  8  KB, 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.

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   at   http://www.tim-
       mann.org/trs80/dskspec.html.   A  copy  of  this  html  file  is also included in the xtrs
       distribution.

       The DMK format is documented  in  a  file  on  David  Keil's  web  site,  http://discover-
       net.net/~dmkeil/trsdoc.htm#Technical-disks;  this file is also included with his emulator.
       Some updates to the 4.00 version of the document: (1) If neither the  single  density  nor
       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.  This update will be effective  in  version
       4.3  of David's emulator; it is incompatible with previous versions. (2) 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 mkdisk.c):

       typedef unsigned char Uchar;
       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, currently set 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
                                    [warning: xtrs currently ignores this flag]
                             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); cyl (hard)*/
         Uchar dcyl;      /* 31: Directory cylinder [mkdisk sets to 1; xtrs
                             ignores, but value must be correct if image is
                             to be used with Reed emulators.] */
         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;

See also

       xtrs(1)

       http://www.tim-mann.org/trs80/dskspec.html

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
       MSDOS-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 MSDOS-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 MSDOS-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.

                                                                                        mkdisk(1)