CWTool image format

Format originator: CWTool by Karsten Scheibler (http://www.unusedino.de/cw/)

Credits: Some information provided (in private email) by Karsten Scheibler.

This format contains raw counter values as provided (and understood) by the Catweasel controllers. This means that the encoded data stream follows the same encoding rules.

Common features

Track numbers are stored as 'absolute' tracks. If a drive has only one magnetic head, the track number will match the physical track number used to read the given track.

When a drive has more than one head (e.g. a 3.5-inch double-sided 80-track drive), the following conversions are used:

• Converting from physical track/head numbers to absolute track number
  • AbsTrack = (PhysTrack * NumHeads) + PhysHead
• Converting from absolute track number to physical track/head numbers
  • PhysTrack = AbsTrack / NumHeads
  • PhysHead = AbsTrack % NumHeads

Note that for the above equations, the forward-slash symbol denotes integer division, while the percent symbol denotes an integer modulo operation.

This means that our typical 3.5-inch floppy disc with two physical heads and 80 physical tracks will -- to CWTool -- be seen as having 160 absolute tracks. Thus, in order to decode back to a cyl/head address, we need to know how many heads the original drive had, and how many were used to image the disc. Failing that, we can make an educated guess based on the maximum absolute track number seen in the image (e.g. a greater than 85 absolute tracks is likely to indicate that the image was created from a double-sided disc).

Binary file formats

All CWTool binary image formats begin with a 32-byte "magic string" which identifies the file format version. Possible magic strings include:

• "cwtool raw data" -- binary format 1. Used by old versions of CWTool, readable but not generated by the current version.
• "cwtool raw data 2" -- binary format 2. Used by old versions of CWTool, readable but not generated by the current version.
• "cwtool raw data 3" -- binary format 3. Current file format version.

Binary formats store tracks as a sequence of data blocks with a header prepended. This header consists of:

• TRACK_MAGIC -- one byte, 0xCA
• Track -- one byte, absolute track number
• Clock -- one byte
• Flags -- one byte
• Payload size -- 32-bit unsigned integer, little endian (most significant byte first)

These bytes have the following function:

• Track stores the Absolute Track Number for the given track, as described above.
• Clock indicates the clock speed which was used to acquire the data. This is permitted to have one of the following values:
  • 0: 14MHz (14.161MHz?)
  • 1: 28MHz (28.322MHz?)
  • 2: 56MHz (actually 56.644MHz, according to http://www.schoenfeld.de/inside/Inside_CWMK3.txt)
• Flags is a bit-field which stores a list of possible acquisition flags which apply to the track:
  • Bit 0: Writable. If a raw image is captured without any further post-processing, there is no way to guarantee that the image could be written back to disc without errors (e.g. one sector may get corrupted if the data stream ends in mid-sector). This bit is set by CWTool for images which have been generated by CWTool itself, instead of those which were read from a disc.
  • Bit 1: Index Stored. Index data has been stored with the track. The most significant bit of each timing value contains the state of the index bit during that timing period. Soft-sectored discs have one index hole per rotation, so this is active (bit set) once per disc rotation.
  • Bit 2: Index Aligned. The track data has been aligned to the index mark. DOS discs are usually written this way, but Amiga and CBM 1541 discs (which have no concept of an "index" except the track sync marker) are not.
  • Bit 3: No Correction. Early versions of CWTool stored timing values decremented by 1 (instead of the actual timing value). Images written with the current version of CWTool do not require this correction.

Text-based file format

This format is unique in that it stores the track data as decimal or hex numbers. The magic string detected by CWTool is "# cwtool raw text 3\n", where '\n' is an ASCII newline.

This feature is classified as "experimental" (ref: email, Karsten Scheibler, 2011-07-19) and intended to ease manual recovery of damaged data. Individual tracks and sectors may be exported as text, edited, then reimported.

# cwtool raw text 3
track_data track clock flags { data data ... }
track_data track clock flags { data data ... }
...

Alternatively, if the data is being stored in hexadecimal:

# cwtool raw text 3
track_data_hex track clock flags { data data ... }
track_data_hex track clock flags { data data ... }
...

Track, Clock and Flags function as described in the Binary Formats section above. They are always stored as decimal numbers, however the actual track data may be stored in either decimal (if the track_data keyword was used) or hexadecimal (if the track_data_hex keyword was used).

No track data length is stored -- this is determined at run-time by the format loader.