


cw2dmk(1)                                               cw2dmk(1)


Name
       cw2dmk  -  Read a floppy disk using a Catweasel controller
       and make an exact copy in DMK format

Syntax
       cw2dmk [options] filename.dmk

Description
       The cw2dmk program uses  the  Catweasel  universal  floppy
       disk  controller to read a disk and save its contents to a
       file.  The save file is written in the  DMK  format  first
       used  by some TRS-80 Model I/III/4/4P emulators.  The disk
       is exactly reproduced, including the positioning and spac-
       ing  of  sectors and the content of gaps, so that even so-
       called copy protected disks can be read correctly and will
       work  with emulators.  Currently, cw2dmk can read all for-
       mats that can be written by the Western Digital  177x/179x
       disk controllers used in the original TRS-80 machines, all
       formats that can be  written  by  the  NEC  765-compatible
       floppy  disk  controllers  used  in  PCs,  and the Digital
       Equipment Corporation RX02 format.

       The cw2dmk program automatically  recognizes  most  varia-
       tions  of drive type and disk format, but you can override
       this autodetection with command line arguments; see below.
       Detection  of FM (single density) or MFM (double/high den-
       sity) encoding works even for disks that have some sectors
       in  each  encoding  on  the same track, such as disks that
       were made to boot on both TRS-80 Models I and III.

       Versions of cw2dmk exist for both Linux  and  MS-DOS.   On
       Linux, cw2dmk must be run as root.  If the program is made
       setuid to root, it drops its root privileges as soon as it
       has  obtained access to the block of I/O ports it needs to
       directly access the Catweasel.  On Windows 95,  cw2dmk.exe
       can  be  run  in  an  MS-DOS Prompt box.  On plain MS-DOS,
       cw2dmk.exe requires a DPMI host to be loaded  first.   You
       can  obtain a suitable, free DPMI host from ftp://ftp.sim-
       tel.net/pub/simtelnet/gnu/djgpp/v2misc/csdpmi4b.zip.
       Unzip  this file and follow the simple instructions before
       running cw2dmk.

       cw2dmk accesses the hardware directly, so it must  not  be
       used at the same time as any other Catweasel software.  In
       particular,  on  Linux,  do  not  load  Michael   Krause's
       "cwfloppy"  driver at the same time, and on MS-DOS, do not
       load the "catbase" driver that comes with the Catweasel.

       For more information about the  Catweasel  controller  and
       other software that works with it, see:
           http://www.jschoenfeld.com/
           http://apd2.tripod.com/catweasl.htm
           http://www.soundtracker.org/raw/

       For  information  about the DMK file format and the emula-
       tors that use it, see:
           http://discover-net.net/~dmkeil/
           http://www.tim-mann.org/xtrs.html


Options
       -p port
          ----
              Set the Catweasel I/O port base.   The  default  is
              the factory setting, 0x320.

       -d drive
          -----
              Specify the drive unit number, 0 or 1.  Default: 0.

       -v verbosity
          ---------
              Specify how much output is printed.  Larger numbers
              select more output.  The default setting is 2.

              0      No output.

              1      Print a summary at the end of conversion.

              2      Also  print  the  number of good sectors and
                     errors on each track.

              3      Also print a short message in brackets  when
                     an error is encountered or the FM/MFM encod-
                     ing detector fires.

              4      Also print the  track  IDs  and  DAMs  (data
                     address marks).

              5      Also  print  all data in hexadecimal.  Print
                     "{" and "}" to indicate where the index hole
                     sensor  went  on  and  off.  Print "(-N)" or
                     "(+N)" where the decoder dropped  or  dupli-
                     cated  N  clock/data  bits  in an attempt to
                     resynchronize itself with the data  bit  and
                     byte  boundaries.   Print  a  "?" before any
                     byte where a clock was unexpectedly  missing
                     or   unexpectedly  present  even  after  the
                     resynchronization heuristics were applied.

              6      Like 4, but also print the data as raw char-
                     acters.

              7      Like 5, but also print each Catweasel sample
                     and its classification as short (s),  medium
                     (m),  or long (l).  Enclose the decoded hex-
                     adecimal data bytes in  angle  brackets  ("<
                     >") to distinguish them from the samples.

       The remaining options are usually not needed.  cw2dmk will
       ordinarily detect or guess the correct values.

       -k kind
          ----
              Specify the type of drive and type of media in use.
              This  option  is  generally  not  needed, as cw2dmk
              should always autorecognize the correct value.  You
              can  use  it  if  you  want to eliminate the slight
              delay for autodetection, or  in  the  special  case
              where you want to treat a 3.5" high density disk as
              an 8" disk (ignoring the last 1/6 of each track) by
              giving the -k3 option where -k4 would have been the
              autorecognized value.  Possible values:

              1      5.25" SD/DD disk in 1.2MB drive

              2      5.25" SD/DD disk in  360KB/720KB  drive,  or
                     3.5" SD/DD disk

              3      5.25" HD disk, or 8" SD/DD disk

              4      3.5" HD disk

       -m steps
          -----
              Step multiplier, 1 or 2.  A step multiplier of 2 is
              used when reading a 40-track (or 35-track) disk  in
              an  80-track  drive.   If this option is not given,
              cw2dmk guesses a likely value and checks its  guess
              by  trying  to  read  the first few tracks.  If the
              guess appears to have been wrong, cw2dmk  will  use
              the  opposite  value  instead.   Giving this option
              will speed up cw2dmk slightly  by  eliminating  the
              time  to check the guess, and will remove the small
              possibility that the guess is wrong even after hav-
              ing  been checked (which can happen only with copy-
              protected disks that are formatted with nonstandard
              track  numbers).   The  initial  guess  is 2 if the
              drive/media type (-k option) is set or autodetected
              to be 1; otherwise the initial guess is 1.

       -t tracks
          ------
              Specifies  the  number of tracks per side.  If this
              option is not given, cw2dmk will guess 43 if the -m
              option  is  set (or guessed) to be 2, otherwise 86.
              If cw2dmk is operating with a guessed value for -t,
              and  the  next  track  after one of the more likely
              ending places (35, 40, 77, or  80  tracks)  has  no
              valid  sectors or has the same logical track number
              as the previous track, it will lower its guess  and
              immediately stop reading at that point.

       -s sides
          -----
              Specifies  the  number of sides.  If this option is
              not given, cw2dmk will guess 2 sides if the  second
              side appears to be formatted, then revise its guess
              to 1 side if there are  no  valid  sectors  on  the
              first  track or two of the second side.  Giving the
              -s1 option explictly for a single-sided  disk  will
              save the time needed for this autodetection.

       -w fmtimes
          -------
              Normally,  FM  bytes  are written into the DMK file
              twice (-w2), so that they take up the correct  pro-
              portion  of the space on mixed-density tracks.  You
              can set -w1 to cause FM bytes to  be  written  only
              once.   This  does  not  save space in the DMK file
              unless you also reduce the track length with the -l
              option.

       -e encoding
          --------
              Overrides the normal FM/MFM/RX02 autodetection.  To
              try only FM decoding, specify -e1; to try only MFM,
              specify  -e2; to try only RX02, specify -e3.  Using
              -e1 or -e2 does not speed  up  cw2dmk  appreciably;
              the   FM/MFM  autodetection  is  very  fast.   RX02
              autodetection is slightly slower, requiring a retry
              on the first double density track.

              Additional notes on DEC RX02 disks: These disks use
              a  nonstandard  encoding  for  double  density.   A
              slight  extension to the DMK format is used to rep-
              resent them: Bit 5 (previously unused)  is  set  in
              the  DMK  header's  options byte (byte 4).  The DMK
              double density flag (bit 15 of the IDAM pointer) is
              not  set  for  RX02  double density sectors, on the
              grounds that only the data and CRC are in MFM,  not
              the  ID,  DAM,  gap,  etc.  A program reading a DMK
              with the RX02 option bit set should expect a sector
              to  contain  twice  as many valid data bytes as its
              sizecode indicates if the sector's DAM is  0xf9  or
              0xfd.  Note that as with other disk types, FM bytes
              are written to the DMK file twice  unless  you  set
              the  -w1  option,  while MFM bytes are written only
              once.  RX02 autodetection does not work in the case
              where the disk has a track with deleted double den-
              sity sectors (0xf9 DAM) before the first track with
              normal  double  density  sectors  (0xfd DAM).  This
              case probably never occurs in practice.

       The following are special options for dealing with hard to
       read disks.

       -x retries
          -------
              While  reading  a  track, cw2dmk tries to recognize
              sector IDs and sector data, and it checks that each
              ID  has  a  corresponding sector and that both have
              correct CRCs.  If any of these checks fail,  cw2dmk
              will  try reading the track again, up to the number
              of additional times specified by this option.   The
              default  value  is 4.  If you have an old disk with
              CRC errors, increasing the number of retries  to  a
              large  value  may  still allow the disk to be read.
              If you have a copy-protected disk with  intentional
              CRC errors, or other strange formatting that cw2dmk
              interprets as a possible error, you might  want  to
              reduce  or  eliminate  the  retries to speed up the
              conversion.

       -a alternate
          ---------
              This option  is  used  only  when  when  reading  a
              40-track disk in an 80-track drive (-m2).  If -a is
              set to 0 (the default) cw2dmk reads from the  even-
              numbered  head positions, skipping the odd-numbered
              ones.  That is, disk track  n  is  read  from  head
              position 2n.  Occasionally, more data may be recov-
              erable by reading at the next higher head position.
              If  you set -a to 1, cw2dmk will always read at odd
              positions (2n+1).  If -a is 2  or  3,  cw2dmk  will
              alternate  between  even  and  odd  positions  when
              retries are needed to read  a  track,  trying  even
              positions first if -a is 2; odd if -a is 3.

       -o postcomp
          --------
              If  you have a disk that shows a lot of CRC errors,
              especially on the higher-numbered tracks,  you  can
              try  re-reading  it  with different values for this
              parameter.  Values between 0.5  and  0.75  seem  to
              work  well  for  old 8" disks.  The default is cur-
              rently 0.0.

              Exactly what does this  option  do?   The  magnetic
              flux  transitions  on  a  floppy  disk tend to move
              slightly farther apart if they  are  recorded  very
              close  together,  thus lengthening the short inter-
              vals and shortening the  long  ones,  a  phenomenon
              sometimes  called  bit-shifting.   When  a  disk is
              recorded, the disk  controller  ordinarily  applies
              write-precompensation  to  reduce this effect; that
              is, it makes the short intervals  extra  short  and
              the long ones correspondingly longer, especially on
              the inner,  higher-numbered  tracks.   Sometimes  a
              disk    is   recorded   with   too   little   write
              precompensation, or perhaps  the  bits  shift  even
              more  as  the  disk ages.  With the postcomp option
              enabled, if cw2dmk observes  that  an  interval  is
              longer  or shorter than its nominal length, it will
              assume that the interval's ending transition  moved
              slightly,  and  will  lengthen  or shorten the next
              interval as a sort of  read-postcompensation.   The
              deviation  of  each  interval  is  multipled by the
              value of the postcomp option before being added  to
              the next interval.

       -r readtime
          --------
              If  this  option  is -1 (the default), cw2dmk reads
              each track up to the end of the index hole.  Other-
              wise,  cw2dmk  reads  each  track for the specified
              number of milliseconds.  This option can be  useful
              if  the  last  sector  on  a track extends past the
              index hole.

       -g ign Causes cw2dmk to ignore the first ign bytes decoded
          ---
              on  each  track.  If ign is negative, an extra -ign
              bytes of padding are inserted at the  beginning  of
              each track.

       -i ipos
          ----
              If  this  option  is given, cw2dmk forces the first
              IAM (index address mark) encountered to be  exactly
              ipos bytes from the physical start of the track, by
              ignoring bytes or adding padding at  the  start  of
              the  track  as with the -g flag.  The default value
              is -1, which disables this feature, instead record-
              ing  the  gap exactly as it was read.  This feature
              was added to help convert one  specific  old  copy-
              protected disk that would work only if the data was
              precisely positioned on  the  physical  track,  but
              which  showed a slightly different initial gap size
              when read with a Catweasel and  a  new  disk  drive
              than with an original TRS-80.

       -z maxsize
          -------
              Change  the maximum value expected for IBM-compati-
              ble sector size codes.  This option does not affect
              the  actual  data  that  is  read from the disk and
              written to the DMK file; it affects  only  the  CRC
              checking  and error retry algorithm described under
              the -x option above.  The default value is  correct
              for  disks  that  were  written  by Western Digital
              WD177x/179x controllers used in TRS-80s.   On  most
              of  these  controllers, only the two low-order bits
              of the code are ever significant,  and  the  sector
              size  is  given by 128 << (code & 3).  On the 1771,
              there is also an optional  "non-IBM"  feature  that
              can  be  selected when a sector is read or written.
              When this feature is used, the sector size is given
              by  16  * code (or 16 * 256 if code is zero).  As a
              heuristic, cw2dmk assumes the non-IBM  feature  was
              used if a sector is recorded in FM (single density)
              and its size code is more than  maxsize.   In  con-
              trast,  with  NEC765-compatible  floppy  disk  con-
              trollers as used in PCs, the sector size  is  given
              by  128  <<  (code  &  7).  Thus if you have a disk
              written by a  PC  with  sectors  larger  than  1024
              bytes,  setting  maxsize  to 7 will allow cw2dmk to
              correctly determine  the  sector  sizes  and  avoid
              reporting false CRC errors.

       The next few options modify individual parameters that are
       normally set correctly by the -k option (or by  autodetec-
       tion  of  the  correct  value  for  the -k option).  These
       options can be given only after the -k option.  To see the
       default values for a particular disk kind N, type the com-
       mand "cw2dmk -kN" with no other arguments;  they  will  be
       shown in brackets in the usage message.

       -c clock
          -----
              Catweasel  sample  rate.   0  selects 14.161 MHz; 1
              selects 7.080 MHz.

       -f threshold
          ---------
              FM threshold for short (1) vs. long (10), in number
              of samples.

       -1 threshold
          ---------
              MFM  threshold  for short (10) vs. medium (100), in
              number of samples.

       -2 threshold
          ---------
              MFM threshold for medium (100) vs. long (1000),  in
              number of samples.

       -l bytes
          -----
              DMK track length in bytes.

Limitations
       Here are the only known cases where the results may not be
       correct unless an additional command line option is given.
       (1)  The disk has a defect but can be successfully read by
       using a larger number of retries than normal (use  the  -x
       option).   (2)  The  disk  was formatted with more than 43
       tracks in a 40-track drive, or more than 86 tracks  in  an
       80-track  drive (use the -t option).  (3) A copy-protected
       disk has nonstandard track numbers that fool  cw2dmk  when
       it tries to detect whether the drive needs to be single or
       double-stepped (use the -s option).   (Double-stepping  is
       used  to read 35- or 40-track disks in an 80-track drive.)
       (4) The TRS-80 program on a  copy-protected  disk  does  a
       Read  Track  when  it is run, and it expects the raw track
       data to be precisely  aligned,  but  the  data  comes  out
       shifted a few bytes forward or backward when read with the
       Catweasel (use the -g or -i option).  (5) The last  sector
       on a track extends past the end of the index hole (use the
       -r option, together with -g, -i, or -l  if  -r  makes  the
       track  too  long).  (6) The disk was made by a NEC765-com-
       patible controller and has sectors longer than 1024  bytes
       (use the -z7 option).

       If  a  disk  has fewer tracks than cw2dmk guesses, reading
       will sometimes continue past the last valid track.  It  is
       harmless  for extra tracks of garbage to be written to the
       end of the DMK file, but if you know the correct number of
       tracks,  you can use the -t option to force cw2dmk to stop
       at the right place.  Remember  that  track  numbers  start
       from  zero,  so  (for example) giving the option -t35 will
       cause tracks numbered 0 to 34 to be read.

Diagnostics
       cw2dmk: No access to I/O ports!
              On Linux, cw2dmk must be made setuid to root or  be
              run  as  root, or it will not be able to access the
              Catweasel's I/O ports and this error  message  will
              appear.

       cw2dmk: Failed to detect Catweasel!
              A  Catweasel card was not detected at the specified
              I/O ports.

       cw2dmk: Failed to detect drive!
              The  specified  drive  (see  -d  option)  was   not
              detected.   Cabling and drive selection can be con-
              fusing, so try the other drive number before giving
              up,  especially  if  you  saw  some  drive activity
              before this message was printed.

       cw2dmk: Track 0 is unformatted!
              For drive/media autodetection to work, track  0  of
              the  diskette  must  be formatted.  This message is
              printed if the track appears not to be formatted.

       cw2dmk: Failed to detect drive and media type!
              This message is printed if  drive/media  autodetec-
              tion fails for some unknown reason.  The detector's
              estimate of the data clock rate and  disk  rotation
              speed  are  also printed; if they are wildly wrong,
              the disk may be unformatted.

       cw2dmk: Read error!
       cw2dmk: No index hole detected!
              Either the drive reported that  it  was  not  ready
              when  the  Catweasel  tried  to read from it, or no
              index hole was detected.   These  messages  usually
              mean  that  there  is  no  disk in the drive.  They
              might also appear in some cases if the drive is not
              connected  properly,  the  door  is not closed, the
              disk is inserted upside-down, etc.

       cw2dmk: Catweasel memory error?! See cw2dmk.txt
              This message may appear with some  Catweasel  cards
              manufactured  before  July  2000  when  used at the
              higher clock rate.   Contact  Individual  Computers
              for  information on obtaining an updated version of
              the MACH chip in your Catweasel.  If you never  see
              this message, the update is not needed.

              Alternatively,  you  may be able to work around the
              problem by using the Catweasel's lower  clock  rate
              (-c1)  with  appropriately  reduced  values for the
              threshold  parameters  (-f  or  -1  and  -2).   The
              thresholds for -c1 should be about half the default
              values used with -c0.  To see the default threshold
              values  for  disk  kind  number N, type the command
              "cw2dmk -kN" with no other arguments; they will  be
              shown in brackets in the usage message.

Authors
       cw2dmk was written by Timothy Mann <tim@tim-mann.org>.  It
       uses  low-level  Catweasel  access  routines  written   by
       Michael  Krause.   cw2dmk is free software, released under
       the GNU General Public License.  Thanks to Jens Schoenfeld
       for  providing  documentation on programming the Catweasel
       hardware.  Thanks to David Keil for  designing  and  docu-
       menting the DMK file format for floppy disk images.

       $Id: cw2dmk.man,v 1.10 2001/08/30 06:41:33 mann Exp $



                                                                1

