Skip to content

Commit 4bcbf2b

Browse files
davidgivendavidgiven
committed
Fix bad documentation which got checked in somehow.
1 parent 6d3969a commit 4bcbf2b

36 files changed

+1699
-72
lines changed

‎doc/disk-40track_drive.md

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,15 @@
1-
-d
2-
\r
1+
40track_drive
2+
====
3+
## Adjust configuration for a 40-track drive
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
This is an extension profile; adding this to the command line will configure
7+
FluxEngine to read from 40-track, 48tpi 5.25" drives. You have to tell it because there is
8+
no way to detect this automatically.
9+
10+
For example:
11+
12+
```
13+
fluxengine read ibm --180 40track_drive
14+
```
15+

‎doc/disk-acornadfs.md

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,39 @@
1-
-d
2-
\r
1+
acornadfs
2+
====
3+
## BBC Micro, Archimedes
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
Acorn ADFS disks are used by the 6502-based BBC Micro and ARM-based Archimedes
7+
series of computers. They are yet another variation on MFM encoded IBM scheme
8+
disks, although with different sector sizes and with the 0-based sector
9+
identifiers rather than 1-based sector identifiers. The index hole is ignored
10+
and sectors are written whereever, requiring FluxEngine to do two revolutions
11+
to read a disk.
12+
13+
There are various different kinds, which should all work out of the box.
14+
15+
Be aware that Acorn logical block numbering goes all the way up side 0 and
16+
then all the way up side 1. However, FluxEngine uses traditional disk images
17+
with alternating sides, with the blocks from track 0 side 0 then track 0 side
18+
1 then track 1 side 0 etc. Most Acorn emulators will use both formats, but
19+
they might require nudging as the side order can't be reliably autodetected.
20+
21+
## Options
22+
23+
- Format variants:
24+
- `160`: 160kB 3.5" or 5.25" 40-track SSDD; S format
25+
- `320`: 320kB 3.5" or 5.25" 80-track SSDD; M format
26+
- `640`: 640kB 3.5" or 5.25" 80-track DSDD; L format
27+
- `800`: 800kB 3.5" 80-track DSDD; D and E formats
28+
- `1600`: 1600kB 3.5" 80-track DSHD; F formats
29+
30+
## Examples
31+
32+
To read:
33+
34+
- `fluxengine read acornadfs --160 -s drive:0 -o acornadfs.img`
35+
- `fluxengine read acornadfs --320 -s drive:0 -o acornadfs.img`
36+
- `fluxengine read acornadfs --640 -s drive:0 -o acornadfs.img`
37+
- `fluxengine read acornadfs --800 -s drive:0 -o acornadfs.img`
38+
- `fluxengine read acornadfs --1600 -s drive:0 -o acornadfs.img`
39+

‎doc/disk-acorndfs.md

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,38 @@
1-
-d
2-
\r
1+
acorndfs
2+
====
3+
## Acorn Atom, BBC Micro series
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
Acorn DFS disks are used by the Acorn Atom and BBC Micro series of computers.
7+
They are pretty standard FM encoded IBM scheme disks, with 256-sectors and
8+
0-based sector identifiers. There's nothing particularly special here.
9+
10+
DFS disks are all single-sided, but allow the other side of the disk to be
11+
used as another volume.
12+
13+
They come in two varieties, 40 track and 80 track. These should both work.
14+
Some rare disks are both at the same time. FluxEngine can read these but it
15+
requires a bit of fiddling as they have the same tracks on twice.
16+
17+
## Options
18+
19+
- Format variants:
20+
- `100`: 100kB 40-track SSSD
21+
- `200`: 200kB 80-track SSSD
22+
23+
## Examples
24+
25+
To read:
26+
27+
- `fluxengine read acorndfs --100 -s drive:0 -o acorndfs.img`
28+
- `fluxengine read acorndfs --200 -s drive:0 -o acorndfs.img`
29+
30+
To write:
31+
32+
- `fluxengine write acorndfs --100 -d drive:0 -i acorndfs.img`
33+
- `fluxengine write acorndfs --200 -d drive:0 -i acorndfs.img`
34+
35+
## References
36+
37+
- [The Acorn DFS disc format](https://beebwiki.mdfs.net/Acorn_DFS_disc_format)
38+

‎doc/disk-aeslanier.md

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,48 @@
1-
-d
2-
\r
1+
aeslanier
2+
====
3+
## 616kB 5.25" 77-track SSDD hard sectored
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
Back in 1980 Lanier released a series of very early integrated word processor
7+
appliances, the No Problem. These were actually [rebranded AES Data Superplus
8+
machines](http://vintagecomputers.site90.net/aes/). They were gigantic,
9+
weighed 40kg, and one example I've found cost ꆲ5bb4
10+
of nearly ㇢1a6e
11+
12+
8080 machines with 32kB of RAM, they ran their own proprietary word
13+
processing software off twin 5.25" drive units, but apparently other software
14+
was available.
15+
16+
The disk format is exceptionally weird. They used 77 track, 32 sector, single-sided
17+
_hard_ sectored disks, where there were multiple index holes,
18+
indicating to the hardware where the sectors start. The encoding scheme
19+
itself is [MMFM (aka
20+
M2FM)](http://www.retrotechnology.com/herbs_stuff/m2fm.html), an early
21+
attempt at double-density disk encoding which rapidly got obsoleted by the
22+
simpler MFM --- and the bytes are stored on disk _backwards_. Even aside from
23+
the encoding, the format on disk was strange; unified sector header/data
24+
records, so that the sector header (containing the sector and track number)
25+
is actually inside the user data.
26+
27+
FluxEngine can read these, but I only have a single, fairly poor example of a
28+
disk image, and I've had to make a lot of guesses as to the sector format
29+
based on what looks right. If anyone knows _anything_ about these disks,
30+
[please get in touch](https://github.com/davidgiven/fluxengine/issues/new).
31+
32+
## Options
33+
34+
(no options)
35+
36+
## Examples
37+
38+
To read:
39+
40+
- `fluxengine read aeslanier -s drive:0 -o aeslanier.img`
41+
42+
## References
43+
44+
* [SA800 Diskette Storage Drive - Theory Of
45+
Operations](http://www.hartetechnologies.com/manuals/Shugart/50664-1_SA800_TheorOp_May78.pdf):
46+
talks about MMFM a lot, but the Lanier machines didn't use this disk
47+
format.
48+

‎doc/disk-agat.md

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,36 @@
1-
-d
2-
\r
1+
agat
2+
====
3+
## 840kB 5.25" 80-track DS
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
The Agat (Russian: ↊fd74
7+
1983. These were based around a 6502 and were nominally Apple II-compatible
8+
although with enough differences to be problematic.
9+
10+
They could use either standard Apple II 140kB disks, or a proprietary 840kb
11+
MFM-based double-sided format. FluxEngine supports both of these; this profile
12+
is for the proprietary format. for the Apple II format, use the `apple2`
13+
profile.
14+
15+
## Options
16+
17+
(no options)
18+
19+
## Examples
20+
21+
To read:
22+
23+
- `fluxengine read agat -s drive:0 -o agat.img`
24+
25+
To write:
26+
27+
- `fluxengine write agat -d drive:0 -i agat.img`
28+
29+
## References
30+
31+
- [Magazine article on the
32+
Agat](https://sudonull.com/post/54185-Is-AGAT-a-bad-copy-of-Apple)
33+
34+
- [Forum thread with (some) documentation on the
35+
format](https://torlus.com/floppy/forum/viewtopic.php?t=1385)
36+

‎doc/disk-amiga.md

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,41 @@
1-
-d
2-
\r
1+
amiga
2+
====
3+
## 880kB 3.5" DSDD
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
Amiga disks use MFM, but don't use IBM scheme. Instead, the entire track is
7+
read and written as a unit, with each sector butting up against the previous
8+
one. This saves a lot of space which allows the Amiga to not just store 880kB
9+
on a DD disk, but _also_ allows an extra 16 bytes of metadata per sector.
10+
11+
This metadata is mostly unused, so the default for FluxEngine is to ignore it
12+
and just use the 512 bytes of main sector data. If you want it, specify a
13+
528-byte sector size. The metadata will come after the user data.
14+
15+
Bizarrely, the data in each sector is stored with all the odd bits first, and
16+
then all the even bits. This is tied into the checksum algorithm, which is
17+
distinctly subpar and not particularly good at detecting errors.
18+
19+
## Options
20+
21+
- Sector size:
22+
- `without_metadata`: 512-byte sectors
23+
- `with_metadata`: 528-byte sectors
24+
25+
## Examples
26+
27+
To read:
28+
29+
- `fluxengine read amiga -s drive:0 -o amiga.adf`
30+
31+
To write:
32+
33+
- `fluxengine write amiga -d drive:0 -i amiga.adf`
34+
35+
## References
36+
37+
- [The Amiga Floppy Boot Process and Physical
38+
Layout](https://wiki.amigaos.net/wiki/Amiga_Floppy_Boot_Process_and_Physical_Layout)
39+
40+
- [The Amiga Disk File FAQ](http://lclevy.free.fr/adflib/adf_info.html)
41+

‎doc/disk-ampro.md

Lines changed: 52 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,52 @@
1-
-d
2-
\r
1+
ampro
2+
====
3+
## CP/M
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
The Ampro Little Board was a very simple and cheap Z80-based computer from
7+
1984, which ran CP/M. It was, in fact, a single PCB which you could mount
8+
on the bottom of a 5.25" drive.
9+
10+
[All about the Ampro Little Board](http://oldcomputers.net/ampro-little-board.html)
11+
12+
It stored either 400kB on a double-sided 40-track drive or 800kB on a
13+
double-sided 80 track drive. The disk format it used was a slightly quirky
14+
variation of the standard MFM IBM scheme --- sector numbering starts at 17
15+
rather than 1 (or Acorn's 0). FluxEngine supports this.
16+
17+
FluxEngine has direct filesystem support for these disks, or you can pass the
18+
disk images into [cpmtools](http://www.moria.de/~michael/cpmtools/):
19+
20+
```
21+
$ cpmls -f ampdsdd ampro.img
22+
0:
23+
-a60014.e
24+
amprodsk.com
25+
bitchk.doc
26+
bitchk.mac
27+
cpmmac.mac
28+
dir.com
29+
himem.doc
30+
himem.mac
31+
kaydiag.lbr
32+
kayinfo.lbr
33+
...etc...
34+
```
35+
36+
## Options
37+
38+
- Format variants:
39+
- `400`: 400kB 40-track DSDD
40+
- `800`: 800kB 80-track DSDD
41+
42+
## Examples
43+
44+
To read:
45+
46+
- `fluxengine read ampro --400 -s drive:0 -o ampro.img`
47+
- `fluxengine read ampro --800 -s drive:0 -o ampro.img`
48+
49+
## References
50+
51+
- [The Ampro Little Board](http://oldcomputers.net/ampro-little-board.html)
52+

‎doc/disk-apple2.md

Lines changed: 74 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,74 @@
1-
-d
2-
\r
1+
apple2
2+
====
3+
## Prodos, Appledos, and CP/M
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
Apple II disks are nominally fairly sensible 40-track, single-sided, 256
7+
bytes-per-sector jobs. However, they come in two varieties: DOS 3.3/ProDOS and
8+
above, and pre-DOS 3.3. They use different GCR encoding systems, dubbed
9+
6-and-2 and 5-and-3, and are mutually incompatible (although in some rare
10+
cases you can mix 6-and-2 and 5-and-3 sectors on the same disk).
11+
12+
The difference is in the drive controller; the 6-and-2 controller is capable
13+
of a more efficient encoding, and can fit 16 sectors on a track, storing
14+
140kB on a disk. The 5-and-3 controller can only fit 13, with a mere 114kB.
15+
16+
Both formats use GCR (in different varieties) in a nice, simple grid of
17+
sectors, unlike the Macintosh. Like the Macintosh, there's a crazy encoding
18+
scheme applied to the data before it goes down on disk to speed up
19+
checksumming.
20+
21+
In addition, a lot of the behaviour of the drive was handled in software.
22+
This means that Apple II disks can do all kinds of weird things, including
23+
having spiral tracks! Copy protection for the Apple II was even madder than
24+
on other systems.
25+
26+
FluxEngine can only read well-behaved 6-and-2 disks. It doesn't even try to
27+
handle the weird stuff.
28+
29+
Apple DOS also applies logical sector remapping on top of the physical sector
30+
numbering on the disk, and this _varies_ depending on what the disk is for.
31+
FluxEngine can remap the sectors from physical to logical using modifiers. If
32+
you don't specify a remapping modifier, you get the sectors in the order they
33+
appear on the disk.
34+
35+
If you don't want an image in physical sector order, specify one of the
36+
filesystem ordering options. These also select the appropriate file system;
37+
FluxEngine has read-only support for all of these.
38+
39+
In addition, some third-party systems use 80-track double sides drives, with
40+
the same underlying disk format. The complication here is that the AppleDOS
41+
filesystem only supports up to 50 tracks, so it needs tweaking to support
42+
larger disks. It treats the second side of the disk as a completely different
43+
volume.
44+
45+
## Options
46+
47+
- Format variants:
48+
- `140`: 140kB 5.25" 35-track SS
49+
- `640`: 640kB 5.25" 80-track DS
50+
- Filesystem and sector skew:
51+
- `nofs`: use physical CHS sector order and no file system
52+
- `appledos`: use AppleDOS soft sector skew and file system
53+
- `prodos`: use ProDOS soft sector skew and filesystem
54+
- `cpm`: use CP/M soft sector skew and filesystem
55+
- `side1`: for AppleDOS file system access, read the volume on side 1 of a disk
56+
57+
## Examples
58+
59+
To read:
60+
61+
- `fluxengine read apple2 --140 -s drive:0 -o apple2.img`
62+
- `fluxengine read apple2 --640 -s drive:0 -o apple2.img`
63+
64+
To write:
65+
66+
- `fluxengine write apple2 --140 -d drive:0 -i apple2.img`
67+
- `fluxengine write apple2 --640 -d drive:0 -i apple2.img`
68+
69+
## References
70+
71+
- [Beneath Apple DOS](https://fabiensanglard.net/fd_proxy/prince_of_persia/Beneath%20Apple%20DOS.pdf)
72+
73+
- [MAME's ap2_dsk.cpp file](https://github.com/mamedev/mame/blob/4263a71e64377db11392c458b580c5ae83556bc7/src/lib/formats/ap2_dsk.cpp)
74+

‎doc/disk-apple2_drive.md

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,16 @@
1-
-d
2-
\r
1+
apple2_drive
2+
====
3+
## Adjust configuration for a 40-track Apple II drive
4+
<!-- This file is automatically generated. Do not edit. -->
5+
6+
This is an extension profile; adding this to the command line will configure
7+
FluxEngine to adjust the pinout and track spacing to work with an Apple II
8+
drive. This only works on Greaseweazle hardware and requires a custom
9+
connector.
10+
11+
For example:
12+
13+
```
14+
fluxengine read apple2 --160 apple2_drive
15+
```
16+

0 commit comments

Comments
 (0)