salfter/fluxengine
1
0
Fork 0
mirror of https://github.com/davidgiven/fluxengine.git synced 2025-10-24 11:11:02 -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`:
```
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

18
doc/filesystem.md
View File

@@ -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

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`)
- 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
-----------------

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

104
doc/technical.md
View File

@@ -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

189
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,
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
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 <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.
`<profile>` 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.
`<profile>` is a reference to an internal input configuration file
describing the format. `<options>` may be any combination of options
defined by the profile.
- `fluxengine write <profile> -i <image input> -d <flux destination>`
Reads a filesystem image and encodes it into flux (possibly writing to a
disk). `<profile>` 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). `<profile>` is a reference to an internal output configuration file
describing the format.
- `fluxengine rawread -s <flux source> -d <flux destination>`
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 <flux source> -d <flux destination>`
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 <fluxfile> -s <fluxfile...> -d <fluxfile`
@@ -165,20 +174,20 @@ more common tools.
- `fluxengine inspect -s <flux source> -c <cylinder> -h <head> -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 <cylinder>`
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:<n>`
Read from or write to a specific drive.
Read from or write to a specific drive.
- `<filename.flux>`
Read from or write to a native FluxEngine flux file.
Read from or write to a native FluxEngine flux file.
- `<filename.scp>`
Read from or write to a Supercard Pro `.scp` flux file.
Read from or write to a Supercard Pro `.scp` flux file.
- `<filename.cwf>`
Read from a Catweasel flux file. **Read only.**
Read from a Catweasel flux file. **Read only.**
- `<filename.a2r>`
@@ -218,8 +227,8 @@ FluxEngine supports a number of ways to get or put flux. When using the `-s` or
- `kryoflux:<directory>`
Read from a Kryoflux stream, where `<path>` is the directory containing the
stream files. **Read only.**
Read from a Kryoflux stream, where `<path>` is the directory containing
the stream files. **Read only.**
- `flx:<directory>`
@@ -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:<directory>`
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:<directory>`
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:
- `<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
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.
- `<filename.diskcopy>`
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.
- `<filename.td0>`
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).
- `<filename.jv3>`
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.**
- `<filename.dim>`
@@ -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.