


mkdisk(1)                                                           mkdisk(1)



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

Syntax
  mmkkddiisskk --11 ffiilleennaammee
  mmkkddiisskk [[--33]] ffiilleennaammee
  mmkkddiisskk --kk [[--ss ssiiddeess]] [[--dd ddeennssiittyy]]
  mmkkddiisskk --hh [[--cc ccyyll]] [[--ss sseecc]]
  mmkkddiisskk {{--pp||--uu}} {{--11||--33||--kk||--hh}} ffiilleennaammee

Description
  The mkdisk program is part of the xxttrrss(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 mmkkddiisskk does not enforce this convention; you
  can use any filename.  Other extensions sometimes used for emulated flop-
  pies are .jv1, .jv3, .8in, and .dmk.

Making Emulated Floppies
  With the -1 flag, mmkkddiisskk 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), mmkkddiisskk
  makes an unformatted emulated floppy of type JV3.  No additional flags are
  accepted.

  With the -k flag, mmkkddiisskk makes an unformatted emulated floppy of type DMK.
  With -k, the optional flags -s, -d, -8, and -i can be used to give the emu-
  lated 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 den-
  sity.  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.  Set-
  ting -s1 or -d1 saves space after the floppy is formatted; setting -8 con-
  sumes 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, 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.

  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.

Write Protection
  With the -p flag, mmkkddiisskk 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, mmkkddiisskk turns off write protection for an existing emu-
  lated 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 (except for JV1 floppies) clears a write-protected flag inside the
  file.

  mmkkddiisskk 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.research.digital.com/SRC/personal/Tim_Mann/trs80/dskspec.html.
  A copy of this html file is also included in the xxttrrss 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 writ-
  ten twice (i.e., the four bytes 12345678 would be written as
  1212343456567878).  This ensures that when single and double density sec-
  tors 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 emula-
  tor; 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
  xxttrrss(1)

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

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







































