salfter/fluxengine
1
0
Fork 0
mirror of https://github.com/davidgiven/fluxengine.git synced 2025-10-31 11:17:01 -07:00
Code Issues Packages Projects Releases Wiki Activity

Polish documentation.

Browse Source
This commit is contained in:
David Given
2023-05-25 20:07:33 +02:00
parent 53adcd92ed
commit 69ece3ffa0
6 changed files with 177 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/drives.md
View File

@@ -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`: 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 It should then Just Work. This is supported by both FluxEngine and Greaseweazle

18
doc/filesystem.md
View File

@@ -17,12 +17,14 @@ The following file systems are supported so far.
|:-----------------------------------------|:-----:|:------:|-------| |:-----------------------------------------|:-----:|:------:|-------|
| Acorn DFS | Y | | | | Acorn DFS | Y | | |
| Amiga FFS | Y | Y | Both OFS and FFS | | Amiga FFS | Y | Y | Both OFS and FFS |
| AppleDOS / ProDOS | Y | Y | With a choice of sector remapping |
| Brother 120kB | Y | Y | | | Brother 120kB | Y | Y | |
| Commodore CbmFS | Y | | Only 1541 disks so far | | Commodore CbmFS | Y | | Only 1541 disks so far |
| CP/M | Y | | Requires configuration for each machine | | CP/M | Y | | Requires configuration for each machine |
| FatFS (a.k.a. MS-DOS) | Y | Y | FAT12, FAT16, FAT32; not Atari (AFAIK!) | | 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 | | 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 | | | | Smaky 6 | Y | | |
{: .datatable } {: .datatable }
@@ -38,19 +40,19 @@ Using it
To use, try syntax like this: 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. `ibm --180` is the format, which selects the most common filesystem
`-f drive:0` specifies a flux source/sink, in this case a real disk. You may automatically. `-f drive:0` specifies a flux source/sink, in this case a real
also specify a flux file (read only). Disk images may be specified with `-i disk. You may also specify a flux file (read only). Disk images may be
disk.img` (read/write). specified with `-i disk.img` (read/write).
Commands which take filename paramaters typically use `-p` to indicate the path Commands which take filename paramaters typically use `-p` to indicate the path
on the disk, and `-l` for the local filename. For example: 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`. 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: 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 Some filesystems won't work on some disks --- don't try this with Amiga FFS, for

5
doc/greaseweazle.md
View File

@@ -41,8 +41,9 @@ Supported features with the Greaseweazle include:
`--usb.greaseweazle.bus_type=SHUGART` or `IBMPC`; the default is `IBMPC`) `--usb.greaseweazle.bus_type=SHUGART` or `IBMPC`; the default is `IBMPC`)
- Apple 5.25 floppy interfaces (via `--usb.greaseweazle.bus_type=APPLE2`) - 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. Which device types are supported depend on the hardware. Genuine Greaseweazle
APPLE2 is only supported with hand wiring and the Adafruit\_Floppy greaseweazle-compatible firmware. hardware supports SHUGART and IBMPC. APPLE2 is only supported with hand wiring
and the Adafruit\_Floppy greaseweazle-compatible firmware.
What doesn't work What doesn't work
----------------- -----------------

BIN
doc/screenshot-details.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

70
doc/technical.md
View File

@@ -95,41 +95,75 @@ For reference, here are the FDC pinouts:
```ditaa ```ditaa
:-E -s 0.75 :-E -s 0.75
+--+--+ +--+--+ +----+----+ +----+----+
DISKCHG ---+ 34 + 33 + DISKCHG ---+ 34 + 33 + DISKCHG ---+ 34 + 33 + DISKCHG ---+ 34 + 33 +
+--+--+ +--+--+ +----+----+ +----+----+
SIDE1 ---+ 32 + 31 + SIDE1 ---+ 32 + 31 + SIDE1 ---+ 32 + 31 + SIDE1 ---+ 32 + 31 +
+--+--+ +--+--+ +----+----+ +----+----+
RDATA ---+ 30 + 29 + RDATA ---+ 30 + 29 + RDATA ---+ 30 + 29 + RDATA ---+ 30 + 29 +
+--+--+ +--+--+ +----+----+ +----+----+
WPT ---+ 28 + 27 + WPT ---+ 28 + 27 + WPT ---+ 28 + 27 + WPT ---+ 28 + 27 +
+--+--+ +--+--+ +----+----+ +----+----+
TRK00 ---+ 26 + 25 + TRK00 ---+ 26 + 25 + TRK00 ---+ 26 + 25 + TRK00 ---+ 26 + 25 +
+--+--+ +--+--+ +----+----+ +----+----+
WGATE ---+ 24 + 23 + WGATE ---+ 24 + 23 + WGATE ---+ 24 + 23 + WGATE ---+ 24 + 23 +
+--+--+ +--+--+ +----+----+ +----+----+
WDATA ---+ 22 + 21 + WDATA ---+ 22 + 21 + WDATA ---+ 22 + 21 + WDATA ---+ 22 + 21 +
+--+--+ +--+--+ +----+----+ +----+----+
STEP ---+ 20 + 19 + STEP ---+ 20 + 19 + STEP ---+ 20 + 19 + STEP ---+ 20 + 19 +
+--+--+ +--+--+ +----+----+ +----+----+
DIR/SIDE1 ---+ 18 + 17 + DIR/SIDE1 ---+ 18 + 17 + DIR/SIDE1 ---+ 18 + 17 + DIR/SIDE1 ---+ 18 + 17 +
+--+--+ +--+--+ +----+----+ +----+----+
MOTEB ---+ 16 + 15 + MOTEB ---+ 16 + 15 + MOTEB ---+ 16 + 15 + MOTEB ---+ 16 + 15 +
+--+--+ +--+--+ +----+----+ +----+----+
DRVSA ---+ 14 + 13 + DS3 ---+ 14 + 13 + DRVSA ---+ 14 + 13 + DS3 ---+ 14 + 13 +
+--+--+ +--+--+ +----+----+ +----+----+
DRVSB ---+ 12 + 11 + DS2 ---+ 12 + 11 + DRVSB ---+ 12 + 11 + DS2 ---+ 12 + 11 +
+--+--+ +--+--+ +----+----+ +----+----+
MOTEA ---+ 10 + 9 + DS1 ---+ 10 + 9 + MOTEA ---+ 10 + 9 + DS1 ---+ 10 + 9 +
+--+--+ +--+--+ +----+----+ +----+----+
INDEX ---+ 8 + 7 + INDEX ---+ 8 + 7 + INDEX ---+ 8 + 7 + INDEX ---+ 8 + 7 +
+--+--+ +--+--+ +----+----+ +----+----+
n/c ---+ 6 + 5 + DS4 ---+ 6 + 5 + n/c ---+ 6 + 5 + DS4 ---+ 6 + 5 +
+--+--+ +--+--+ +----+----+ +----+----+
n/c ---+ 4 + 3 + INU ---+ 4 + 3 + n/c ---+ 4 + 3 + INU ---+ 4 + 3 +
+--+--+ +--+--+ +----+----+ +----+----+
REDWC ---+ 2 + 1 + REDWC ---+ 2 + 1 + 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 PC interface Shugart interface

97
doc/using.md
View File

@@ -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, `--help` or `help` depending on context. There are some common properties,
described below. described below.
If possible, try using the GUI, which should provide simplified access for most
common operations.
<div style="text-align: center">
<a href="doc/screenshot-details.png"><img src="doc/screenshot-details.png" style="width:60%" alt="screenshot of the GUI in action"></a>
</div>
### Core concepts ### Core concepts
FluxEngine's job is to read magnetic data (called _flux_) off a disk, decode 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 # Read an PC 1440kB disk, producing a disk image with the default name
# (ibm.img) # (ibm.img)
$ fluxengine read ibm1440 $ fluxengine read ibm --1440
# Write a PC 1440kB disk to drive 1 # 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 # 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 $ fluxengine read eco1 --copy-flux-to copy.flux -o eco1.ldbs
@@ -94,26 +101,27 @@ encoder {
} }
} }
} }
$ 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: ...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 Both the above invocations are equivalent. The text files use [Google's
protobuf syntax](https://developers.google.com/protocol-buffers), which is protobuf syntax](https://developers.google.com/protocol-buffers), which is
hierarchical, type-safe, and easy to read. hierarchical, type-safe, and easy to read.
The `ibm1440` string above is actually a reference to an internal configuration The `ibm` string above is actually a reference to an internal configuration file
file containing all the settings for writing PC 1440kB disks. You may specify containing all the settings for writing PC disks, and the `--1140` refers to a
as many profile names or textpb files as you wish; they are all merged left to specific definition inside it. You may specify as many profile names or textpb
right. You can see all these settings by doing: 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 The `--config` option will cause the current configuration to be dumped to the
@@ -131,11 +139,12 @@ different task. Run each one with `--help` to get a full list of
(non-configuration-setting) options; this describes only basic usage of the (non-configuration-setting) options; this describes only basic usage of the
more common tools. more common tools.
- `fluxengine read <profile> -s <flux source> -o <image output>` - `fluxengine read <profile> <options> -s <flux source> -o <image output>`
Reads flux (possibly from a disk) and decodes it into a file system image. Reads flux (possibly from a disk) and decodes it into a file system image.
`<profile>` is a reference to an internal input configuration file `<profile>` is a reference to an internal input configuration file
describing the format. describing the format. `<options>` may be any combination of options
defined by the profile.
- `fluxengine write <profile> -i <image input> -d <flux destination>` - `fluxengine write <profile> -i <image input> -d <flux destination>`
@@ -145,9 +154,9 @@ more common tools.
- `fluxengine rawread -s <flux source> -d <flux destination>` - `fluxengine rawread -s <flux source> -d <flux destination>`
Reads flux (possibly from a disk) and writes it to a flux file without Reads flux (possibly from a disk) and writes it to a flux file without doing
doing any decoding. You can specify a profile if you want to read a subset any decoding. You can specify a profile if you want to read a subset of the
of the disk. disk.
- `fluxengine rawwrite -s <flux source> -d <flux destination>` - `fluxengine rawwrite -s <flux source> -d <flux destination>`
@@ -165,10 +174,10 @@ more common tools.
- `fluxengine inspect -s <flux source> -c <cylinder> -h <head> -B` - `fluxengine inspect -s <flux source> -c <cylinder> -h <head> -B`
Reads flux (possibly from a disk) and does various analyses of it to try Reads flux (possibly from a disk) and does various analyses of it to try and
and detect the clock rate, display raw flux information, examine the detect the clock rate, display raw flux information, examine the underlying
underlying data from the FluxEngine board, etc. There are lots of options data from the FluxEngine board, etc. There are lots of options but the
but the command above is the most useful. command above is the most useful.
- `fluxengine rpm` - `fluxengine rpm`
@@ -218,8 +227,8 @@ FluxEngine supports a number of ways to get or put flux. When using the `-s` or
- `kryoflux:<directory>` - `kryoflux:<directory>`
Read from a Kryoflux stream, where `<path>` is the directory containing the Read from a Kryoflux stream, where `<path>` is the directory containing
stream files. **Read only.** the stream files. **Read only.**
- `flx:<directory>` - `flx:<directory>`
@@ -239,8 +248,8 @@ FluxEngine supports a number of ways to get or put flux. When using the `-s` or
- `au:<directory>` - `au:<directory>`
Write to a series of `.au` files, one file per track, which can be loaded 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 into an audio editor (such as Audacity) as a simple logic analyser.
only.** **Write only.**
- `vcd:<directory>` - `vcd:<directory>`
@@ -252,7 +261,8 @@ FluxEngine supports a number of ways to get or put flux. When using the `-s` or
FluxEngine also supports a number of file system image formats. When using the 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: `-i` or `-o` options (for input and output), you can use any of these strings:
- `<filename.adf>`, `<filename.d81>`, `<filename.img>`, `<filename.st>`, `<filename.xdf>` - `<filename.adf>`, `<filename.d81>`, `<filename.img>`, `<filename.st>`,
`<filename.xdf>`
Read from or write to a simple headerless image file (all these formats are Read from or write to a simple headerless image file (all these formats are
the same). This will probably want configuration via the the same). This will probably want configuration via the
@@ -382,20 +392,19 @@ behaviour.
- `--drive.revolutions=X` - `--drive.revolutions=X`
When reading, spin the disk X times. X When reading, spin the disk X times. X can be a floating point number. The
can be a floating point number. The default is usually 1.2. Some formats default is usually 1.2. Some formats default to 1. Increasing the number
default to 1. Increasing the number will sample more data, and can be will sample more data, and can be useful on dubious disks to try and get a
useful on dubious disks to try and get a better read. better read.
- `--drive.sync_with_index=true|false` - `--drive.sync_with_index=true|false`
Wait for an index pulse Wait for an index pulse before starting to read the disk. (Ignored for write
before starting to read the disk. (Ignored for write operations.) By operations.) By default FluxEngine doesn't, as it makes reads faster, but
default FluxEngine doesn't, as it makes reads faster, but when diagnosing when diagnosing disk problems it's helpful to have all your data start at
disk problems it's helpful to have all your data start at the same place the same place each time.
each time.
- `--drive.index_source=X` - `--drive.index_mode=X`
Set the source of index pulses when reading or writing respectively. This 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 is for use with drives which don't produce index pulse data. `X` can be
@@ -405,16 +414,6 @@ behaviour.
useful for using very old drives with FluxEngine itself. If you use this 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. 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`
## Visualisation ## Visualisation
When using `fluxengined read` (either from a real disk or from a flux file) you When using `fluxengined read` (either from a real disk or from a flux file) you
@@ -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 Apart from being drastically faster, this avoids touching the (potentially
physically fragile) disk. physically fragile) disk.
If the disk is particularly dodgy, you can force FluxEngine not to retry If the disk is particularly dodgy, you can force FluxEngine not to retry failed
failed reads with `--retries=0`. This reduces head movement. **This is not reads with `--decoder.retries=0`. This reduces head movement. **This is not
recommended.** Floppy disks are inherently unreliable, and the occasional bit recommended.** Floppy disks are inherently unreliable, and the occasional bit
error is perfectly normal; FluxEngine will retry and the sector will read error is perfectly normal; FluxEngine will retry and the sector will read fine
fine next time. If you prevent retries, then not only do you get bad sectors next time. If you prevent retries, then not only do you get bad sectors in the
in the resulting image, but the flux file itself contains the bad read, so resulting image, but the flux file itself contains the bad read, so attempting a
attempting a decode of it will just reproduce the same bad data. decode of it will just reproduce the same bad data.
See also the [troubleshooting page](problems.md) for more information about See also the [troubleshooting page](problems.md) for more information about
reading dubious disks. reading dubious disks.