CWTool image format

From DiscFerret
Revision as of 16:21, 14 June 2011 by Philpem (talk | contribs) (Binary file formats)
Jump to: navigation, search

Format originator: CWTool by Karsten Scheibler (

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
  • "cwtool raw data 2" -- binary format 2
  • "cwtool raw data 3" -- binary format 3

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:
  • Flags is a bit-field which stores a list of possible acquisition flags which apply to the track:
    • Bit 0: Writable
    • 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.
    • Bit 2: Index Aligned. The track data has been aligned to the index mark.
    • Bit 3: No 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.

 # 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.