README for the dfi2dmk addition to cw2dmk. See README for the original documentation.

This is a patched version of the cw2dmk-4.4 source created by Tim Mann. 

The changes and additions were made to allow the software to read the DFI files
as produced by the magpie program that is part of the DiscFerret source code. 
Some additions were only made to create a testable path to the desired 
functionality.

The  followed strategy is:
- Refactor the cw2dmk code to eliminate most global variables (optional, but 
  helped understand the code).
- Adapt cw2dmk-4.4 to produce a raw file with Catweasel data (per track). I 
  used the DiscFerret magpie format for this.
- Adapt cw2dmk-4.4 to read data from the file produced by the previous version 
  instead of the Catweasel.
- Tweak an additional set of the kind.h parameters to reliably decode a magpie 
  created file.

The main benefit for me is that the code remained testable most of the time, 
quite useful if you don't pretend to understand it all.


For this the cw2dmk.c and several header files were modified. The header file
cw2dmk.h is new. A new source file, dfi2dmk.c was added to read the dfi file. 
Maybe later the new functionality will be merged into the cw2dmk file.

The changes in some detail

cw2dmk.c has a new option "-b <dumpFile>". This command dumps the raw sample 
data from the catweasel card to a file with the same structure as the magpie
DFE2 file. Note that tracks that are re-read appear multiple times in the file.
For proper usage, the cw2dmk output (set -v to 2) should be checked. 

As a by product of the new functionality, the cw2dmk.c code is refactored, so
most global variables are gone. To limit the number of arguments to the 
functions, these are grouped into structs. The new functionality could also be 
added to the original code.

New is the dfi2dmk.c file. This is basically a simplified version of the 
modified cw2dmk.c file, with all catweasel access removed. A new option is 
"-j <dumpFile>". This reads the dump file created with "magpie" or "cw2dmk -b"
and feed it to the decoding functionality. Some options are effective:

-k has some new kinds of drives, 5 to 8. These are the same as 1 to 4 but for
   the discFerret clock rates. So far only 6 is tested. This means the
   thesholds of the others are probably wrong.
-s the side option is handy as it ignores the second side in the dump file.

Another change is the value range accepted by the decoder functions. cw2dmk
operates the Catweasel card with a clock setting of 14.161 MHz. With this
rate, all valid transition times are less than 127 ticks. The DiscFerret has 
a minimum clock of 25 MHz, and transition timess can become larger. The code
has been adapted to accept these values. At the same time the index hole is
no longer used to break off decoding. With sufficient verbose logging it is 
still visible.

Typical usage:
./dfi2dmk -k 6 -j <dfi file> <dmk file> -v 4

Known issues:

The code does not detect reread tracks, so these are happily decoded and written
to the dmk file. As both header and track data are written, this might still
work with some emulators, but consider the result corrupt.

The decoder function contains an adjust variable, which currently does not work.
With properly tuned tresholds it will make the detection more robust, but it
didn't work jet. It is now disabled.

The current DFI file format does not contain a indicator of the clock used. 
Dfi2dmk only accepts 25 MHz files.

There are no executables in this distribution. It is only slightly tested and 
only for Linux i386. 

As cw2dmk is licensed under GNU v2, so is this version.

Fred Jan Kraan, 2013-01-31
