Fix & Document Apple II sector mapping

* Update documentation (note apple flux writing is a unicorn now even though this isn't quite true until #489)
 * Fix DOS 3.3 mapping
 * Add ProDOS (all versions) mapping

README.md

@@ -97,7 +97,7 @@ people who've had it work).
 | [Acorn ADFS](doc/disk-acornadfs.md)       |  🦄   |   🦖*  | single- and double- sided           |
 | [Acorn DFS](doc/disk-acorndfs.md)         |  🦄   |   🦖*  |                                     |
 | [Ampro Little Board](doc/disk-ampro.md)   |  🦖   |   🦖*  |                                     |
-| [Apple II DOS 3.3](doc/disk-apple2.md)    |  🦄   |   🦖   | doesn't do logical sector remapping |
+| [Apple II](doc/disk-apple2.md)            |  🦄   |   🦄   |                                     |
 | [Amiga](doc/disk-amiga.md)                |  🦄   |   🦄   |                                     |
 | [Commodore 64 1541/1581](doc/disk-c64.md) |  🦄   |   🦄   | and probably the other formats      |
 | [Brother 120kB](doc/disk-brother.md)      |  🦄   |   🦄   |                                     |

doc/disk-apple2.md

@@ -2,7 +2,7 @@ Disk: Apple II
 ==============
 
 Apple II disks are nominally fairly sensible 40-track, single-sided, 256
-bytes-per-sector jobs. However, they come in two varieties: DOS 3.3 and
+bytes-per-sector jobs. However, they come in two varieties: DOS 3.3/ProDOS and
 above, and pre-DOS 3.3. They use different GCR encoding systems, dubbed
 6-and-2 and 5-and-3, and are mutually incompatible (although in some rare
 cases you can mix 6-and-2 and 5-and-3 sectors on the same disk).
@@ -21,14 +21,14 @@ This means that Apple II disks can do all kinds of weird things, including
 having spiral tracks! Copy protection for the Apple II was even madder than
 on other systems.
 
-FluxEngine can only read well-behaved, DOS 3.3 6-and-2 disks. It doesn't even
-try to handle the weird stuff.
+FluxEngine can only read well-behaved 6-and-2 disks. It doesn't even try to
+handle the weird stuff.
 
-Sadly, DOS 3.3 also applies logical sector remapping on top of the physical
-sector numbering on the disk, and this _varies_ depending on what the disk is
-for. FluxEngine doesn't attempt to remap sectors, instead giving you an exact
-copy of what's on the disk, so you may need to do some work before the images
-are usable in emulators.
+Apple DOS also applies logical sector remapping on top of the physical sector
+numbering on the disk, and this _varies_ depending on what the disk is for.
+FluxEngine can remap the sectors from physical to logical using modifiers.  If
+you don't specify a remapping modifier, you get the sectors in the order they
+appear on the disk.
 
 
 Reading discs
@@ -41,9 +41,13 @@ fluxengine read apple2
 ```
 
 You should end up with an `apple2.img` which is 143360 bytes long.
+It will be in physical sector ordering. You can specify a sector ordering,
+`appledos` or `prodos` to get an image intended for use in an emulator,
+due to the logical sector mapping issue described above:
 
-**Big warning!** The image may not work in an emulator, due to the
-logical sector mapping issue described above.
+```
+fluxengine read apple2 prodos
+```
 
 Writing discs
 -------------
@@ -53,8 +57,12 @@ Just do:
 fluxengine write apple2 -i apple2.img
 ```
 
-**Big warning!** An image designed for an emulator may not work, due to the
-logical sector mapping issue described above.
+If your image is in logical sector ordering (images intended for emulators
+usually are), specify a modifier of `appledos` or `prodos`:
+
+```
+fluxengine write apple2 prodos -i apple2.img
+```
 
 
 Useful references

mkninja.sh

@@ -532,6 +532,7 @@ FORMATS="\
     northstar175 \
     northstar350 \
     northstar87 \
+    prodos \
     rx50 \
     tids990 \
     vgi \

src/formats/appledos.textpb

@@ -4,20 +4,20 @@ is_extension: true
 sector_mapping {
 	trackdata {
 		mapping { physical: 0  logical: 0  }
-		mapping { physical: 1  logical: 13 }
-		mapping { physical: 2  logical: 11 }
-		mapping { physical: 3  logical: 9  }
-		mapping { physical: 4  logical: 7  }
+		mapping { physical: 1  logical: 7  }
+		mapping { physical: 2  logical: 14 }
+		mapping { physical: 3  logical: 6  }
+		mapping { physical: 4  logical: 13 }
 		mapping { physical: 5  logical: 5  }
-		mapping { physical: 6  logical: 3  }
-		mapping { physical: 7  logical: 1  }
-		mapping { physical: 8  logical: 14 }
-		mapping { physical: 9  logical: 12 }
+		mapping { physical: 6  logical: 12 }
+		mapping { physical: 7  logical: 4  }
+		mapping { physical: 8  logical: 11 }
+		mapping { physical: 9  logical: 3  }
 		mapping { physical: 10 logical: 10 }
-		mapping { physical: 11 logical: 8  }
-		mapping { physical: 12 logical: 6  }
-		mapping { physical: 13 logical: 4  }
-		mapping { physical: 14 logical: 2  }
+		mapping { physical: 11 logical: 2  }
+		mapping { physical: 12 logical: 9  }
+		mapping { physical: 13 logical: 1  }
+		mapping { physical: 14 logical: 8  }
 		mapping { physical: 15 logical: 15 }
 	}
 }

src/formats/prodos.textpb

@@ -0,0 +1,25 @@
+
+comment: 'Applies standard ProDOS soft sector skew to the Apple II format'
+is_extension: true
+
+sector_mapping {
+	trackdata {
+		mapping { physical:  0 logical:  0 }
+		mapping { physical:  1 logical:  8 }
+		mapping { physical:  2 logical:  1 }
+		mapping { physical:  3 logical:  9 }
+		mapping { physical:  4 logical:  2 }
+		mapping { physical:  5 logical: 10 }
+		mapping { physical:  6 logical:  3 }
+		mapping { physical:  7 logical: 11 }
+		mapping { physical:  8 logical:  4 }
+		mapping { physical:  9 logical: 12 }
+		mapping { physical: 10 logical:  5 }
+		mapping { physical: 11 logical: 13 }
+		mapping { physical: 12 logical:  6 }
+		mapping { physical: 13 logical: 14 }
+		mapping { physical: 14 logical:  7 }
+		mapping { physical: 15 logical: 15 }
+	}
+}
+