Merge pull request #135 from davidgiven/docs

Update docs.

README.md

@@ -79,7 +79,7 @@ people who've had it work).
 
 | Format                                   | Read? | Write? | Notes |
 |:-----------------------------------------|:-----:|:------:|-------|
-| IBM PC compatible                        |  🦄   |        | and compatibles (like the Atari ST) |
+| [IBM PC compatible](doc/disk-ibm.md)     |  🦄   |        | and compatibles (like the Atari ST) |
 | [Acorn ADFS](doc/disk-acornadfs.md)      |  🦄   |        | single- and double- sided           |
 | [Acorn DFS](doc/disk-acorndfs.md)        |  🦄   |        |                                     |
 | [Ampro Little Board](doc/disk-ampro.md)  |  🦖   |        |                                     |

doc/disk-ibm.md

@@ -0,0 +1,81 @@
+Disk: Generic IBM
+=================
+
+IBM scheme disks are _the_ most common disk format, ever. They're used by a
+huge variety of different systems, and they come in a huge variety of different
+forms, but they're all fundamentally the same: either FM or MFM, either single
+or double sided, with distinct sector header and data records and no sector
+metadata. Systems which use IBM scheme disks include but are not limited to:
+
+  - IBM PCs (naturally)
+  - Atari ST
+  - late era Apple machines
+  - Acorn machines
+  - the TRS-80
+  - late era Commodore machines (the 1571 and so on)
+  - most CP/M machines
+  - etc
+
+FluxEngine supports reading these. However, some variants are more peculiar
+than others, and as a result there are specific decoders which set the defaults
+correctly for certain formats (for example: on PC disks the sector numbers
+start from 1, but on [Acorn](disk-acorndfs.md) disks they start from 0). The
+IBM decoder described here is the generic one, and is suited for 'conventional'
+PC disks. While you can read all the variant formats with it if you use the
+right set of arguments, it's easier to use the specific decoder.
+
+The generic decoder is mostly self-configuring, and will detect the format of
+your disk for you.
+
+
+Reading disks
+-------------
+
+Just do:
+
+    fluxengine read ibm
+
+...and you'll end up with an `ibm.img` file. This should work on most PC disks
+(including FM 360kB disks, 3.5" 1440kB disks, 5.25" 1200kB disks, etc.) The size
+of the disk image will vary depending on the format.
+
+Configuration options you'll want include:
+
+  - `--sector-id-base`: specifies the ID of the first sector; this defaults
+    to 1. Some formats (like the Acorn ones) start at 0. This can't be
+	autodetected because FluxEngine can't distinguish between a disk which
+	starts at sector 1 and a disk which starts at sector 0 but all the sector
+	0s are missing.
+
+  - `--ignore-side-byte`: each sector header describes the location of the
+	sector: sector ID, track and side. Some formats use the wrong side ID, so
+	the sectors on side 1 are labelled as belonging to side 0. This causes
+	FluxEngine to see duplicate sectors (as it can't distinguish between the
+	two sides). This option tells FluxEngine to ignore the side byte completely
+	and use the physical side instead.
+
+
+Reading mixed-format disks
+--------------------------
+
+Some disks, usually those belonging to early CP/M machines, have more than one
+format on the disk at once. Typically, the first few tracks will be low-density
+FM encoded and will be read by the machine's ROM; those tracks contain new
+floppy drive handling code capable of coping with MFM data, and so the rest of
+the disk will use that, allowing them to store more data.
+
+FluxEngine copes with these fine, but the disk images are a bit weird. If track
+0 is FM and contains five sectors, but track 1 is MFM with nine sectors (MFM is
+more efficient and the sectors are physically smaller, allowing you to get more
+on), then the resulting image will have nine sectors per track... but track 0
+will only contain data in the first five.
+
+This is typically what you want as it makes locating the sectors in the image
+easier, but some emulators may require a different format. Please [get in
+touch](https://github.com/davidgiven/fluxengine/issues/new) if you have
+specific requirements (nothing's come up yet). Alternatively, you can tell
+FluxEngine to write a [`.ldbs`
+file](http://www.seasip.info/Unix/LibDsk/ldbs.html) and then use
+[libdsk](http://www.seasip.info/Unix/LibDsk/) to convert it to something
+useful.
+

doc/technical.md

@@ -59,53 +59,42 @@ Some useful and/or interesting numbers:
 
 ## Why don't I use an Arduino / STM32 / ESP32 / Raspberry Pi / etc?
 
-I've got a _lot_ of questions on this, and multiple Github issues of people
+-I've got a _lot_ of questions on this, and multiple Github issues of people
 debating it. It's complicated, but it's essentially a tradeoff between speed
-and complexity.
+and complexity.-
 
-FluxEngine's read process involves generating a lot of data using a fairly
-brute force sampling approach --- about 150kB per disk revolution, and
-sometimes it needs to record multiple revolutions. Most microcontrollers
-don't have enough RAM to buffer this, so instead I have to stream it over USB
-back to the host PC in real time. The disk won't wait, so I need to stream data faster
-than the disk is producing it: the total is about 800kB/s.
+**Update as of 2020-01-08:**
 
-Handling USB is pretty CPU-hungry, so my candidate microntroller has to be
-able to cope with the ruinously strict real-time requirements of the
-sampler's 12MHz clock as well as keeping up with 13,000 USB interrupts a
-second (one for each 64-byte frame) in order to transfer the data.
+Right. Well.
 
-The Atmels and STM32s I found were perfectly capable of doing the real-time
-sampling, using hand-tool assembly, but I very much doubt whether they could
-do the USB streaming as well (although I want to move away from the Cypress
-onto something less proprietary and easier to source, so I'd like to be
-proven wrong here).
+This section used to have a long explanation as to why these other platforms
+were unsuitable --- essentially, they're generally missing out on either the
+realtimeness to sample the data correctly (Raspberry Pi) or enough CPU to
+stream the data over USB while also sampling it (Arduino).
 
-The Raspberry Pi easily has enough processing power and memory, but it's also
-got terrible GPIO pin read performance --- [about
-1kHz](https://raspberrypi.stackexchange.com/questions/9646/how-fast-is-gpiodma-multi-i2s-input/10197#10197).
-That's a long way from the 12MHz I need.
+This is correct, but it turns out that the STM32 has some built-in features
+which support the FluxEngine's use case almost exactly: you can configure the
+DMA engine to sample the interval between pulses and write them directly into
+memory, and you can configure the PWM engine the read samples from memory and
+use them to time pulses to the output. There's a bit less functionality, so you
+can't do things like measure the signal voltages, and they're less convenient
+as you need an adapter cable or board, but this will allow you to replicate the
+FluxEngine hardware on a $2 Blue Pill.
 
-The PSoC5LP part I'm using has enough CPU to handle the USB side of things,
-and it _also_ has a whole set of FPGA-like soft programmable features,
-including 24 mini-ALU systems that are ideally suited to exactly this kind of
-sampling. I can read the disk and generate the byte stream describing the
-flux pattern entirely in 'hardware', without involving the main CPU at all.
-This is then DMAed directly into a set of ring buffers read for the USB
-system to pick up and relay back to the PC. It's incredibly simple and works
-well. (The same applies to writing flux back onto the disk.)
+I am _not_ planning on replacing the PSoC5 with a Blue Pill, because someone
+already has: [the GreaseWeazle](https://github.com/keirf/Greaseweazle/wiki) is
+a completely open source firmware package which will read and write Supercard
+Pro files via a standard Blue Pill. The GreaseWeazle's USB protocol is
+different from the FluxEngine's so they're not directly interchangeable. You
+can, however, read a Supercard Pro file with a GreaseWeazle and then use the
+FluxEngine client to decode it. It should work the other way around, too, but
+FluxEngine's SCP export [is curently
+broken](https://github.com/davidgiven/fluxengine/issues/134).
 
-The development board I'm using, the
-[CY8CKIT-059](https://www.cypress.com/documentation/development-kitsboards/cy8ckit-059-psoc-5lp-prototyping-kit-onboard-programmer-and),
-also has another big advantage: it's the right shape. It's got 17 holes in a
-row connected to GPIO pins, and it's a native 5V part, which means I can just
-connect a floppy drive connector directly to the board without needing to
-build any hardware. No adapter board, no level shifting, no special cable,
-nothing. This makes the FluxEngine hardware incredibly easy to assemble,
-which therefore means cheap.
+I _am_ considering adding direct support for the GreaseWeazle to the FluxEngine
+client, which will let you just plug one in and make it go as a direct
+replacement to the FluxEngine hardware.
 
-Speaking of which, the CY8CKIT-059 is $10. (Before shipping, which is
-admittedly expensive.)
 
 ### Some useful links