diff --git a/doc/drives.md b/doc/drives.md index f162bcd0..452b69a5 100644 --- a/doc/drives.md +++ b/doc/drives.md @@ -39,7 +39,7 @@ If you actually have a forty track drive, you need to tell FluxEngine. This is done by adding the special profile `40track_drive`: ``` -fluxengine write ibm360 40track_drive -i image.img -d drive:0 +fluxengine write ibm --360 40track_drive -i image.img -d drive:0 ``` It should then Just Work. This is supported by both FluxEngine and Greaseweazle diff --git a/doc/filesystem.md b/doc/filesystem.md index a7f6ecea..b2822e71 100644 --- a/doc/filesystem.md +++ b/doc/filesystem.md @@ -17,12 +17,14 @@ The following file systems are supported so far. |:-----------------------------------------|:-----:|:------:|-------| | Acorn DFS | Y | | | | Amiga FFS | Y | Y | Both OFS and FFS | +| AppleDOS / ProDOS | Y | Y | With a choice of sector remapping | | Brother 120kB | Y | Y | | | Commodore CbmFS | Y | | Only 1541 disks so far | | CP/M | Y | | Requires configuration for each machine | | FatFS (a.k.a. MS-DOS) | Y | Y | FAT12, FAT16, FAT32; not Atari (AFAIK!) | +| Hewlett-Packard LIF | Y | | | | Macintosh HFS | Y | Y | Only AppleDouble files may be written | -| Apple ProDOS | Y | | | +| pSOS' PHILE | Y | | Probably unreliable due to lack of documentation | | Smaky 6 | Y | | | {: .datatable } @@ -38,19 +40,19 @@ Using it To use, try syntax like this: ``` -fluxengine ls ibm180 -f drive:0 +fluxengine ls ibm --180 -f drive:0 ``` -`ibm180` is the format, which selects the most common filesystem automatically. -`-f drive:0` specifies a flux source/sink, in this case a real disk. You may -also specify a flux file (read only). Disk images may be specified with `-i -disk.img` (read/write). +`ibm --180` is the format, which selects the most common filesystem +automatically. `-f drive:0` specifies a flux source/sink, in this case a real +disk. You may also specify a flux file (read only). Disk images may be +specified with `-i disk.img` (read/write). Commands which take filename paramaters typically use `-p` to indicate the path on the disk, and `-l` for the local filename. For example: ``` -fluxengine putfile ibm180 -f drive:0 -p ondisk.pcx -l z.pcx +fluxengine putfile ibm --180 -f drive:0 -p ondisk.pcx -l z.pcx ``` This will copy the file `z.pcx` onto the disk and call it `ONDISK.PCX`. @@ -83,7 +85,7 @@ default; for example, Macintosh HFS filesystems are common on 3.5" floppies. You can do this as follows: ``` -fluxengine format ibm1440 -f drive:1 --filesystem.type=MACHFS +fluxengine format ibm --1440 -f drive:1 --filesystem.type=MACHFS ``` Some filesystems won't work on some disks --- don't try this with Amiga FFS, for diff --git a/doc/greaseweazle.md b/doc/greaseweazle.md index fb75a7e1..66a39a73 100644 --- a/doc/greaseweazle.md +++ b/doc/greaseweazle.md @@ -41,8 +41,9 @@ Supported features with the Greaseweazle include: `--usb.greaseweazle.bus_type=SHUGART` or `IBMPC`; the default is `IBMPC`) - Apple 5.25 floppy interfaces (via `--usb.greaseweazle.bus_type=APPLE2`) -Which device types are supported depend on the hardware. Genuine Greaseweazle hardware supports SHUGART and IBMPC. -APPLE2 is only supported with hand wiring and the Adafruit\_Floppy greaseweazle-compatible firmware. +Which device types are supported depend on the hardware. Genuine Greaseweazle +hardware supports SHUGART and IBMPC. APPLE2 is only supported with hand wiring +and the Adafruit\_Floppy greaseweazle-compatible firmware. What doesn't work ----------------- diff --git a/doc/screenshot-details.png b/doc/screenshot-details.png new file mode 100644 index 00000000..1a02039c Binary files /dev/null and b/doc/screenshot-details.png differ diff --git a/doc/technical.md b/doc/technical.md index 1a274561..de7d0c8f 100644 --- a/doc/technical.md +++ b/doc/technical.md @@ -95,41 +95,75 @@ For reference, here are the FDC pinouts: ```ditaa :-E -s 0.75 - +--+--+ +--+--+ - DISKCHG ---+34+33+ DISKCHG ---+34+33+ - +--+--+ +--+--+ - SIDE1 ---+32+31+ SIDE1 ---+32+31+ - +--+--+ +--+--+ - RDATA ---+30+29+ RDATA ---+30+29+ - +--+--+ +--+--+ - WPT ---+28+27+ WPT ---+28+27+ - +--+--+ +--+--+ - TRK00 ---+26+25+ TRK00 ---+26+25+ - +--+--+ +--+--+ - WGATE ---+24+23+ WGATE ---+24+23+ - +--+--+ +--+--+ - WDATA ---+22+21+ WDATA ---+22+21+ - +--+--+ +--+--+ - STEP ---+20+19+ STEP ---+20+19+ - +--+--+ +--+--+ - DIR/SIDE1 ---+18+17+ DIR/SIDE1 ---+18+17+ - +--+--+ +--+--+ - MOTEB ---+16+15+ MOTEB ---+16+15+ - +--+--+ +--+--+ - DRVSA ---+14+13+ DS3 ---+14+13+ - +--+--+ +--+--+ - DRVSB ---+12+11+ DS2 ---+12+11+ - +--+--+ +--+--+ - MOTEA ---+10+9 + DS1 ---+10+9 + - +--+--+ +--+--+ - INDEX ---+8 +7 + INDEX ---+8 +7 + - +--+--+ +--+--+ - n/c ---+6 +5 + DS4 ---+6 +5 + - +--+--+ +--+--+ - n/c ---+4 +3 + INU ---+4 +3 + - +--+--+ +--+--+ - REDWC ---+2 +1 + REDWC ---+2 +1 + - +--+--+ +--+--+ + +----+----+ +----+----+ + DISKCHG ---+ 34 + 33 + DISKCHG ---+ 34 + 33 + + +----+----+ +----+----+ + SIDE1 ---+ 32 + 31 + SIDE1 ---+ 32 + 31 + + +----+----+ +----+----+ + RDATA ---+ 30 + 29 + RDATA ---+ 30 + 29 + + +----+----+ +----+----+ + WPT ---+ 28 + 27 + WPT ---+ 28 + 27 + + +----+----+ +----+----+ + TRK00 ---+ 26 + 25 + TRK00 ---+ 26 + 25 + + +----+----+ +----+----+ + WGATE ---+ 24 + 23 + WGATE ---+ 24 + 23 + + +----+----+ +----+----+ + WDATA ---+ 22 + 21 + WDATA ---+ 22 + 21 + + +----+----+ +----+----+ + STEP ---+ 20 + 19 + STEP ---+ 20 + 19 + + +----+----+ +----+----+ + DIR/SIDE1 ---+ 18 + 17 + DIR/SIDE1 ---+ 18 + 17 + + +----+----+ +----+----+ + MOTEB ---+ 16 + 15 + MOTEB ---+ 16 + 15 + + +----+----+ +----+----+ + DRVSA ---+ 14 + 13 + DS3 ---+ 14 + 13 + + +----+----+ +----+----+ + DRVSB ---+ 12 + 11 + DS2 ---+ 12 + 11 + + +----+----+ +----+----+ + MOTEA ---+ 10 + 9 + DS1 ---+ 10 + 9 + + +----+----+ +----+----+ + INDEX ---+ 8 + 7 + INDEX ---+ 8 + 7 + + +----+----+ +----+----+ + n/c ---+ 6 + 5 + DS4 ---+ 6 + 5 + + +----+----+ +----+----+ + n/c ---+ 4 + 3 + INU ---+ 4 + 3 + + +----+----+ +----+----+ + REDWC ---+ 2 + 1 + REDWC ---+ 2 + 1 + + +----+----+ +----+----+ + DISKCHG ---+ 34 + 33 + DISKCHG ---+ 34 + 33 + + +----+----+ +----+----+ + SIDE1 ---+ 32 + 31 + SIDE1 ---+ 32 + 31 + + +----+----+ +----+----+ + RDATA ---+ 30 + 29 + RDATA ---+ 30 + 29 + + +----+----+ +----+----+ + WPT ---+ 28 + 27 + WPT ---+ 28 + 27 + + +----+----+ +----+----+ + TRK00 ---+ 26 + 25 + TRK00 ---+ 26 + 25 + + +----+----+ +----+----+ + WGATE ---+ 24 + 23 + WGATE ---+ 24 + 23 + + +----+----+ +----+----+ + WDATA ---+ 22 + 21 + WDATA ---+ 22 + 21 + + +----+----+ +----+----+ + STEP ---+ 20 + 19 + STEP ---+ 20 + 19 + + +----+----+ +----+----+ + DIR/SIDE1 ---+ 18 + 17 + DIR/SIDE1 ---+ 18 + 17 + + +----+----+ +----+----+ + MOTEB ---+ 16 + 15 + MOTEB ---+ 16 + 15 + + +----+----+ +----+----+ + DRVSA ---+ 14 + 13 + DS3 ---+ 14 + 13 + + +----+----+ +----+----+ + DRVSB ---+ 12 + 11 + DS2 ---+ 12 + 11 + + +----+----+ +----+----+ + MOTEA ---+ 10 + 9 + DS1 ---+ 10 + 9 + + +----+----+ +----+----+ + INDEX ---+ 8 + 7 + INDEX ---+ 8 + 7 + + +----+----+ +----+----+ + n/c ---+ 6 + 5 + DS4 ---+ 6 + 5 + + +----+----+ +----+----+ + n/c ---+ 4 + 3 + INU ---+ 4 + 3 + + +----+----+ +----+----+ + REDWC ---+ 2 + 1 + REDWC ---+ 2 + 1 + + +----+----+ +----+----+ PC interface Shugart interface diff --git a/doc/using.md b/doc/using.md index 0669bcf1..5e7f4a2e 100644 --- a/doc/using.md +++ b/doc/using.md @@ -11,6 +11,13 @@ moving too quickly for the documentation to keep up. It does respond to `--help` or `help` depending on context. There are some common properties, described below. +If possible, try using the GUI, which should provide simplified access for most +common operations. + +
+screenshot of the GUI in action +
+ ### Core concepts FluxEngine's job is to read magnetic data (called _flux_) off a disk, decode @@ -68,10 +75,10 @@ Here are some sample invocations: ``` # Read an PC 1440kB disk, producing a disk image with the default name # (ibm.img) -$ fluxengine read ibm1440 +$ fluxengine read ibm --1440 # Write a PC 1440kB disk to drive 1 -$ fluxengine write ibm1440 -i image.img -d drive:1 +$ fluxengine write ibm --1440 -i image.img -d drive:1 # Read a Eco1 CP/M disk, making a copy of the flux into a file $ fluxengine read eco1 --copy-flux-to copy.flux -o eco1.ldbs @@ -90,30 +97,31 @@ $ cat config.textpb encoder { ibm { trackdata { - emit_iam: false - } + emit_iam: false + } } } -$ fluxengine write ibm1440 config.textpb -i image.img +$ fluxengine write ibm --1440 config.textpb -i image.img ``` ...or you can specify them on the command line: ``` -$ fluxengine write ibm1440 -i image.img --encoder.ibm.trackdata.emit_iam=false +$ fluxengine write ibm --1440 -i image.img --encoder.ibm.trackdata.emit_iam=false ``` Both the above invocations are equivalent. The text files use [Google's protobuf syntax](https://developers.google.com/protocol-buffers), which is hierarchical, type-safe, and easy to read. -The `ibm1440` string above is actually a reference to an internal configuration -file containing all the settings for writing PC 1440kB disks. You may specify -as many profile names or textpb files as you wish; they are all merged left to -right. You can see all these settings by doing: +The `ibm` string above is actually a reference to an internal configuration file +containing all the settings for writing PC disks, and the `--1140` refers to a +specific definition inside it. You may specify as many profile names or textpb +files as you wish; they are all merged left to right. You can see all these +settings by doing: ``` -$ fluxengine write ibm1440 --config +$ fluxengine write ibm --1440 --config ``` The `--config` option will cause the current configuration to be dumped to the @@ -131,29 +139,30 @@ different task. Run each one with `--help` to get a full list of (non-configuration-setting) options; this describes only basic usage of the more common tools. - - `fluxengine read -s -o ` + - `fluxengine read -s -o ` - Reads flux (possibly from a disk) and decodes it into a file system image. - `` is a reference to an internal input configuration file - describing the format. + Reads flux (possibly from a disk) and decodes it into a file system image. + `` is a reference to an internal input configuration file + describing the format. `` may be any combination of options + defined by the profile. - `fluxengine write -i -d ` - Reads a filesystem image and encodes it into flux (possibly writing to a - disk). `` is a reference to an internal output configuration file - describing the format. + Reads a filesystem image and encodes it into flux (possibly writing to a + disk). `` is a reference to an internal output configuration file + describing the format. - `fluxengine rawread -s -d ` - Reads flux (possibly from a disk) and writes it to a flux file without - doing any decoding. You can specify a profile if you want to read a subset - of the disk. + Reads flux (possibly from a disk) and writes it to a flux file without doing + any decoding. You can specify a profile if you want to read a subset of the + disk. - `fluxengine rawwrite -s -d ` - Reads flux from a file and writes it (possibly to a disk) without doing any - encoding. You can specify a profile if you want to write a subset of the - disk. + Reads flux from a file and writes it (possibly to a disk) without doing any + encoding. You can specify a profile if you want to write a subset of the + disk. - `fluxengine merge -s -s -d -c -h -B` - Reads flux (possibly from a disk) and does various analyses of it to try - and detect the clock rate, display raw flux information, examine the - underlying data from the FluxEngine board, etc. There are lots of options - but the command above is the most useful. + Reads flux (possibly from a disk) and does various analyses of it to try and + detect the clock rate, display raw flux information, examine the underlying + data from the FluxEngine board, etc. There are lots of options but the + command above is the most useful. - `fluxengine rpm` - Measures the rotation speed of a drive. For hard-sectored disks, you - probably want to add the name of a read profile to configure the number of - sectors. + Measures the rotation speed of a drive. For hard-sectored disks, you + probably want to add the name of a read profile to configure the number of + sectors. - `fluxengine seek -c ` - Seeks a drive to a particular cylinder. + Seeks a drive to a particular cylinder. There are other tools; try `fluxengine --help`. @@ -198,19 +207,19 @@ FluxEngine supports a number of ways to get or put flux. When using the `-s` or - `drive:` - Read from or write to a specific drive. + Read from or write to a specific drive. - `` - Read from or write to a native FluxEngine flux file. + Read from or write to a native FluxEngine flux file. - `` - Read from or write to a Supercard Pro `.scp` flux file. + Read from or write to a Supercard Pro `.scp` flux file. - `` - Read from a Catweasel flux file. **Read only.** + Read from a Catweasel flux file. **Read only.** - `` @@ -218,8 +227,8 @@ FluxEngine supports a number of ways to get or put flux. When using the `-s` or - `kryoflux:` - Read from a Kryoflux stream, where `` is the directory containing the - stream files. **Read only.** + Read from a Kryoflux stream, where `` is the directory containing + the stream files. **Read only.** - `flx:` @@ -228,53 +237,54 @@ FluxEngine supports a number of ways to get or put flux. When using the `-s` or - `erase:` - Read nothing --- writing this to a disk will magnetically erase a track. - **Read only.** + Read nothing --- writing this to a disk will magnetically erase a track. + **Read only.** - `testpattern:` - Read a test pattern, which can be written to a disk to help diagnosis. - **Read only.** + Read a test pattern, which can be written to a disk to help diagnosis. + **Read only.** - `au:` - Write to a series of `.au` files, one file per track, which can be loaded - into an audio editor (such as Audacity) as a simple logic analyser. **Write - only.** + Write to a series of `.au` files, one file per track, which can be loaded + into an audio editor (such as Audacity) as a simple logic analyser. + **Write only.** - `vcd:` - Write to a series of `.vcd` files, one file per track, which can be loaded - into a logic analyser (such as Pulseview) for analysis. **Write only.** + Write to a series of `.vcd` files, one file per track, which can be loaded + into a logic analyser (such as Pulseview) for analysis. **Write only.** ### Image sources and destinations FluxEngine also supports a number of file system image formats. When using the `-i` or `-o` options (for input and output), you can use any of these strings: - - ``, ``, ``, ``, `` + - ``, ``, ``, ``, + `` - Read from or write to a simple headerless image file (all these formats are - the same). This will probably want configuration via the - `input/output.image.img.*` configuration settings to specify all the - parameters. + Read from or write to a simple headerless image file (all these formats are + the same). This will probably want configuration via the + `input/output.image.img.*` configuration settings to specify all the + parameters. - `` - Read from or write to a [DiskCopy - 4.2](https://en.wikipedia.org/wiki/Disk_Copy) image file, commonly used by - Apple Macintosh emulators. + Read from or write to a [DiskCopy + 4.2](https://en.wikipedia.org/wiki/Disk_Copy) image file, commonly used by + Apple Macintosh emulators. - `` - Read a [Sydex Teledisk TD0 - file](https://web.archive.org/web/20210420224336/http://dunfield.classiccmp.org/img47321/teledisk.htm) - image file. Note that only uncompressed images are supported (so far). + Read a [Sydex Teledisk TD0 + file](https://web.archive.org/web/20210420224336/http://dunfield.classiccmp.org/img47321/teledisk.htm) + image file. Note that only uncompressed images are supported (so far). - `` - Read from a JV3 image file, commonly used by TRS-80 emulators. **Read - only.** + Read from a JV3 image file, commonly used by TRS-80 emulators. **Read + only.** - `` @@ -382,38 +392,27 @@ behaviour. - `--drive.revolutions=X` - When reading, spin the disk X times. X - can be a floating point number. The default is usually 1.2. Some formats - default to 1. Increasing the number will sample more data, and can be - useful on dubious disks to try and get a better read. + When reading, spin the disk X times. X can be a floating point number. The + default is usually 1.2. Some formats default to 1. Increasing the number + will sample more data, and can be useful on dubious disks to try and get a + better read. - `--drive.sync_with_index=true|false` - Wait for an index pulse - before starting to read the disk. (Ignored for write operations.) By - default FluxEngine doesn't, as it makes reads faster, but when diagnosing - disk problems it's helpful to have all your data start at the same place - each time. + Wait for an index pulse before starting to read the disk. (Ignored for write + operations.) By default FluxEngine doesn't, as it makes reads faster, but + when diagnosing disk problems it's helpful to have all your data start at + the same place each time. - - `--drive.index_source=X` + - `--drive.index_mode=X` - Set the source of index pulses when reading or writing respectively. This - is for use with drives which don't produce index pulse data. `X` can be - `INDEXMODE_DRIVE` to get index pulses from the drive, `INDEXMODE_300` to - fake 300RPM pulses, or `INDEXMODE_360` to fake 360RPM pulses. Note this - has no effect on the _drive_, so it doesn't help with flippy disks, but is - useful for using very old drives with FluxEngine itself. If you use this - option, then any index marks in the sampled flux are, of course, garbage. - - - `--flux_source.rescale=X, --flux_sink.rescale=X` - - When reading or writing a floppy on a drive that doesn't match the - original drive RPM, the flux periods can be scaled to compensate. - - For example, to read or write a PC-98 1.2MB (360rpm) floppy using a 300rpm - floppy drive: - - `--flux_source.rescale=1.2 --flux_sink.rescale=1.2` + Set the source of index pulses when reading or writing respectively. This + is for use with drives which don't produce index pulse data. `X` can be + `INDEXMODE_DRIVE` to get index pulses from the drive, `INDEXMODE_300` to + fake 300RPM pulses, or `INDEXMODE_360` to fake 360RPM pulses. Note this + has no effect on the _drive_, so it doesn't help with flippy disks, but is + useful for using very old drives with FluxEngine itself. If you use this + option, then any index marks in the sampled flux are, of course, garbage. ## Visualisation @@ -439,8 +438,8 @@ wrote to do useful things. These are built alongside FluxEngine. - `brother120tool`, `brother240tool` - Does things to Brother word processor disks. These are [documented on the - Brother disk format page](disk-brother.md). + Does things to Brother word processor disks. These are [documented on the + Brother disk format page](disk-brother.md). ## The recommended workflow @@ -466,13 +465,13 @@ $ fluxengine read brother -s brother.flux -o brother.img --decoder.write_csv_to= Apart from being drastically faster, this avoids touching the (potentially physically fragile) disk. -If the disk is particularly dodgy, you can force FluxEngine not to retry -failed reads with `--retries=0`. This reduces head movement. **This is not +If the disk is particularly dodgy, you can force FluxEngine not to retry failed +reads with `--decoder.retries=0`. This reduces head movement. **This is not recommended.** Floppy disks are inherently unreliable, and the occasional bit -error is perfectly normal; FluxEngine will retry and the sector will read -fine next time. If you prevent retries, then not only do you get bad sectors -in the resulting image, but the flux file itself contains the bad read, so -attempting a decode of it will just reproduce the same bad data. +error is perfectly normal; FluxEngine will retry and the sector will read fine +next time. If you prevent retries, then not only do you get bad sectors in the +resulting image, but the flux file itself contains the bad read, so attempting a +decode of it will just reproduce the same bad data. See also the [troubleshooting page](problems.md) for more information about reading dubious disks.