
Name
  mkdisk - Make a blank hard disk for TRS80 emulator.

Syntax
  mkdisk [-c cyl] [-s sec] [-g gran] [-d dir] filename

Description
  The mkdisk program is part of the TRS80 package.  It makes a blank
  (unformatted) emulated hard drive in a file.

  MKDISK makes an unformatted emulated hard drive with cyl cylinders,
  sec sectors, and gran granules (LDOS allocation units) per cylinder.
  You should format the drive with its directory on cylinder dir.
  You will usually want to use the default values for all these parameters.
  The conventional file extension for emulated hard drives is ".hdv", but
  mkdisk does not enforce this convention; you can give any filename.

  For cyl, the default value is 202, the maximum is 202 (Model I/III) or 203
  (Model 4), and the minimum is 3.  Note: Model I/III LDOS could handle 203
  cylinders except for a minor bug in FORMAT/CMD that prevents such a large
  drive from being formatted.  You can use a 203-cylinder drive with Model
  I/III LDOS if you format it with Model 4 LDOS.

  For sec, the default value is 256, the maximum is 256, and the minimum is
  4.  Note: if you are using version 1.1 of Matthew Reed's Model I/III emula-
  tor and you would like to share emulated hard drives with it, then if sec
  is greater than 32, it must be divisible by 32.  Later Reed emulators do
  not have this limitation.

  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.

  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 con-
  trolled by the granule size: LDOS allocates file space in granules.  There-
  fore (1) gran should always be set as large as possible and (2) reducing
  sec, thereby making the granules smaller, reduces wasted space due to frag-
  mentation but limits the maximum size of the drive.

  Seeing that the absolute maximum 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 TRS80 users.  Therefore the default parameters have been
  chosen to give you the largest drive possible.

  The dir parameter declares which cylinder will contain the LDOS directory.
  The default value is 1, a good choice so that the emulated drive image can
  start out small, with no data written past cylinder 1 by the LDOS FORMAT
  program.  You should invoke the LDOS FORMAT program on the new image with
  the same dir value you used with mkdisk; for example, if you omitted the -d
  option and accepted the default value of 1, then type FORMAT (DIR=1).
  Note: setting the -d dir and DIR=dir values to agree is not essential
  unless you plan to share hard drive images with Matthew Reed's emulators;
  TRS80 itself ignores the dir parameter and allows FORMAT to place the direc-
  tory on any cylinder.

Technical data

  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;


  http://www.research.digital.com/SRC/personal/Tim_Mann/trs80/dskspec.html

Authors
  mkdisk was written by Timothy Mann <mann@pa.dec.com>, Digital Equipment
  Corporation. Modifications for TRS80 use by David Keil

  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 this emulator and Matthew's
  emulators.  Thanks to Matthew for designing the format and providing
  documentation.
