mirror of
https://github.com/davidgiven/fluxengine.git
synced 2025-10-31 11:17:01 -07:00
Polish documentation.
This commit is contained in:
David Given
189
doc/using.md
189
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.
|
||||
|
||||
<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.
|
||||
|
||||
Reference in New Issue
Block a user