.WOZ File Format

Introduction

The WOZ format, named for Steve Wozniak and designed by the makers of the Applesauce disk reader, holds a disk as the bits a drive head would see on each track, so that copy-protected disks, disks with unusual timing and the spaces between sectors survive. It comes in two versions, WOZ1 and WOZ2, and covers 5.25-inch disks (the Disk II) and 3.5-inch disks. It is the format most Apple II preservation work now uses. The tracks of ordinary DOS 3.3 and ProDOS disks are read into sectors the way a NIB is, so the same file systems are shown inside.

The header and the chunks

The chunks are INFO, TMAP, TRKS and (optionally) META, and in version 2.1 WRIT and FLUX. The CRC is the ordinary CRC-32 (polynomial $EDB88320); the viewer's own routine was checked against Node's zlib.crc32, and the CRC and the field layout of version 2 against how KEGS reads a WOZ 2 (woz.c, which also checks the CRC).

INFO

TMAP

160 bytes: for each quarter-track position of the head (track × 4, then +1, +2, +3 for the quarter tracks after it), the index of the track entry in TRKS, or $FF when nothing is recorded there. A normal disk fills the whole-track slots and the quarter tracks next to them point at the same entry. (A 3.5-inch disk is indexed by track and side instead.)

TRKS

In WOZ1, 6,656 bytes for each track: 6,646 bytes of bit stream, then the number of bytes used (2), the number of bits (2), the splice point (2), the splice nibble (1), the splice bit count (1) and 2 reserved. In WOZ2 the chunk starts with 160 entries of 8 bytes (first 512-byte block counted from the start of the file, number of blocks, number of bits), and the tracks follow from block 3, each on a block boundary, so a track can be any length.

Reading a track. The bits are taken most significant bit first. A Disk II controller makes a byte when the high bit of its shift register is a 1, so bits are shifted in and, when eight bits since the first 1 are in, a byte is out and the register is cleared; zero bits in front of a 1 are skipped. This is what makes a self-sync FF with two extra zero bits (10 bits) come out as FF. The viewer reads each track twice round, so a field across the end of the track is found, and then decodes the sectors the same way as for a NIB.

What is in a 5.25-inch track

Once read into disk bytes a track is the same as a NIB track, and described the same way there; in short:

• Gaps of $FF self-sync bytes (10 bits each on a real disk) between the fields.
• Address field: D5 AA 96, the volume, track, sector and a checksum each as two 4-and-4 bytes, then DE AA EB. The sector number is the physical position, not the DOS or ProDOS logical sector.
• Data field: D5 AA AD, 342 values and a checksum in the 6-and-2 encoding, then DE AA EB.

A 13-sector disk's address field starts D5 AA B5 and its data field is in the 5-and-3 encoding, which is not decoded.

META

UTF-8 text, one line for each item, a key and a value with a tab between (title, subtitle, publisher, developer, copyright, version, language, requires_ram, requires_machine, notes, side, side_name, contributor, image_date). The viewer shows the lines as a table.

In the explorer

The tree has the header (with the CRC checked), every chunk with its fields, the TMAP slots, the track entries and each 5.25-inch track as its fields (gaps, address fields, data fields) with the byte positions rounded from the bit positions. The table of tracks lists the bits, the nibbles read, the sectors decoded and the problems; the metadata and the chunks are tables. A WOZ with a wrong CRC opens with the problem reported.

Not described

Known, not yet covered

• Viewer: 3.5-inch disks are listed by track entry with their bit counts, but their GCR sectors (524 bytes, a different 6-and-2 scheme with a three-part checksum) are not decoded.
• Viewer: the WRIT and FLUX chunks (WOZ 2.1) are listed and their bytes shown, not decoded; the flux timings are not turned into bits.
• Viewer: only the whole-track slot of each track is decoded; quarter tracks that hold other data and tracks that are different on each read (copy protection with weak bits) are not shown separately.
• Viewer: a track read with a fixed bit position cannot show the real timing (the optimal bit timing field is shown, not used).

Unknown

• Reference and viewer: no real .woz file and no WOZ reader other than KEGS's C source is on this Mac, so both versions were built here from the published layout and read back; real tracks (long gaps, 10-bit sync, weak bits, tracks not starting at a field) were not seen.

Variants

• Apple II sector image (.DSK, .DO, .PO) – the sectors with no header, in DOS or ProDOS order
• 2IMG disk image – a 64-byte header in front of the sectors
• NIB nibble image – the nibbles of each track as the drive reads them
• WOZ disk image – the bit stream of every track, in chunks

Links