


mkdisk(1)                                                           mkdisk(1)



Name
  mkdisk - Make a blank emulated floppy or hard disk for xtrs

Syntax
  mmkkddiisskk [-1 | -3 | -h] [-c cyl] [-s sec] [-g gran] [-d dir] filename

Description
  The mkdisk program is part of the xxttrrss(1) package.  It makes a blank
  (unformatted) emulated floppy or hard drive in a file.  See the xtrs man
  page for background information.

  With the -1 flag, mmkkddiisskk makes an unformatted emulated floppy of type JV1.
  With the -3 flag (which is the default and should normally be used), mmkkddiisskk
  makes an unformatted emulated floppy of type JV3.  The conventional file
  extension for both types is ".dsk", but mkdisk does not enforce this con-
  vention; you can give any filename.

  With the -h flag, mmkkddiisskk makes an unformatted emulated hard drive with _c_y_l
  cylinders, _s_e_c sectors, and _g_r_a_n granules (LDOS allocation units) per
  cylinder.  You should format the drive with its directory on cylinder _d_i_r.
  You will usually want to use the default values for all these parameters.
  The conventional file extension for emulated hard drives is ".hdv", but
  mmkkddiisskk does not enforce this convention; you can give any filename.

  For _c_y_l, 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 _s_e_c, 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 _s_e_c
  is greater than 32, it must be divisible by 32.  Later Reed emulators do
  not have this limitation.

  For _g_r_a_n, the default value is 8, the maximum is 8, and the minimum is 1.
  In addition, it is necessary that _s_e_c be evenly divisible by _g_r_a_n, and that
  _s_e_c/_g_r_a_n be less than or equal to 32.

  The maximum size of a hard drive image is controlled by _c_y_l and _s_e_c: it can
  be at most _c_y_l*_s_e_c 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) _g_r_a_n should always be set as large as possible and (2) reducing
  _s_e_c, 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 xxttrrss users.  Therefore the default parameters have been
  chosen to give you the largest drive possible.

  The _d_i_r 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 _d_i_r value you used with mmkkddiisskk; for example, if you omitted the -d
  option and accepted the default value of 1, then type _F_O_R_M_A_T (_D_I_R=_1).
  Note: setting the -_d _d_i_r and _D_I_R=_d_i_r values to agree is not essential
  unless you plan to share hard drive images with Matthew Reed's emulators;
  xxttrrss itself ignores the _d_i_r parameter and allows FORMAT to place the direc-
  tory on any cylinder.

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.

  A JV3 file is an array of 3-byte sector descriptors followed by an array of
  256-byte sectors, in the same order as the descriptors.  The first 34*256
  bytes of the file are reserved for descriptors, leaving room for 2901 of
  them with one byte left over at the end.  The extra byte should be 0xff.  A
  newer feature, not implemented in all emulators, emulates a write protect
  tab on the disk if the extra byte is 0x00.  Currently xtrs respects this
  flag, but provides no way to turn it on or off.  The preferred way to
  write-protect a floppy image under xtrs is to turn off write permission on
  the corresponding file.

  The original format thus could handle only 2901 sectors.  This is enough
  for a DSDD 80-track 5" floppy, but not enough for 8" floppies, so xtrs
  extends the format by adding an optional second block of 2901 more headers
  after the last possible sector described by the first block.  That is, the
  second block starts at byte (34 + 2901)*256 in the file.  This extension is
  also implemented in Matthew Reed's newer TRS-80 emulators.

  The headers themselves look like this (from trs_disk.c):

  /* Values for flags below */
  #define JV3_DENSITY     0x80  /* 1=dden, 0=sden */
  #define JV3_LOCKED      0x40  /* always zero */
  #define JV3_DIRECTORY   0x20  /* dden: 1=deleted DAM (0xF8)
                                   sden: 1=0xFA or 0xF8 */
  #define JV3_SIDE        0x10  /* 0=side 0, 1=side 1 */
  #define JV3_ERROR       0x08  /* 0=ok, 1=CRC error */
  #define JV3_MBZ         0x07  /* must be zero if sector in use */
  #define JV3_UNUSED      0xFF

  typedef struct {
    unsigned char track;
    unsigned char sector;
    unsigned char flags;
  } SectorId;

  An unused sector is denoted by a header filled with 0xFF.  Sometimes
  headers in the middle of a block can be unused; this happens, for example,
  if you reformat a track from double density to single density.  In general,
  when you format a track with N sectors, the first N unused headers are
  assigned to it; they need not be contiguous in the file or ordered with
  respect to other tracks.  The order of the sectors within a track does
  matter, though; they show up in that order if you do a series of Read
  Address commands or a Read Track command (however, xtrs doesn't currently
  implement Read Track).

  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
  xxttrrss(1)

Authors
  mmkkddiisskk was written by Timothy Mann <mann@pa.dec.com>, Digital Equipment
  Corporation.

  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 (respec-
  tively).  They have become a de facto standard in the TRS-80 emulation com-
  munity, and much TRS-80 software is available on the Internet in .dsk for-
  mat.  Thanks to Jeff for designing and documenting the formats.

  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 xxttrrss and Matthew's emula-
  tors.  Thanks to Matthew for designing the format and providing documenta-
  tion.

