[PATCH 25/25] efw-downloader: add README formatted by reStructuredText

[Takashi Sakamoto]

This commit adds README so that developers and users can get description
about this tool easily.

Signed-off-by: Takashi Sakamoto <o-takashi at sakamocchi.jp>
---
 efw-downloader/README.rst | 167 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 efw-downloader/README.rst

diff --git a/efw-downloader/README.rst b/efw-downloader/README.rst
new file mode 100644
index 0000000..8d35ee3
--- /dev/null
+++ b/efw-downloader/README.rst
@@ -0,0 +1,167 @@
+==============
+efw-downloader
+==============
+
+2020/08/21
+Takashi Sakamoto
+
+Introduction
+============
+
+This tool is designed to operate on-board flash memory for devices with Fireworks board module. The
+goal is to download firmware for the module.
+
+At present, the tool can perform read operation from flash memory, and parse operation for firmware
+file, therefore it's unlikely to make your device bricked.
+
+Target devices
+==============
+
+* LOUD Audio, LLC (Mackie)
+
+    * Onyx 400F
+    * Onyx 1200F
+
+* Echo Digital Audio corporation
+
+    * Audiofire 12 (with DSP)
+    * Audiofire 12 (with FPGA)
+    * Audiofire 8 (with DSP)
+    * Audiofire 8 (with FPGA)
+    * Audiofire 2
+    * Audiofire 4
+    * Audiofire Pre8
+
+* Gibson guitar corporation
+
+    * Robot Interface Pack (RIP)
+
+Background
+==========
+
+Echo Digital Audio corporation shipped Fireworks board module. This module is designed for audio and
+music units on IEEE 1394 bus with rich features for direct monitoring, on-board routing, and so on.
+
+The module consists of two combinations of two ICs:
+
+* A combination:
+
+    * Texus Instruments TSB43Cx43A (IceLynx Micro)
+    * Texus Instruments TMS320C6713B (DSP)
+
+* Another combination:
+
+    * Texus Instruments TSB43Cx43A (IceLynx Micro)
+    * Xilinx Spartan XC35250E (FPGA)
+
+The module has on-board flash memory to store firmware for the above ICs and allows software to
+read, erase, and write to the memory by Fireworks protocol.
+
+For your information, Echo Digital Audio corporation have US patent. The patent describes that two
+processors are used for data processing in IEEE 1394 bus, and for sample processing from/to DAC/ADC.
+These two processors independently run via memory bank. I guess that IceLynx Micro is used for the
+former role, and DSP/FPGA is used for the latter role.
+
+Echo Digital Audio corporation provided a series of firmware blob to their customers and bundled the
+firmware to driver package for Windows and macOS. The firmware blob has specific structure designed
+by Echo Digital Audio corporation.
+
+Prerequities
+============
+
+Dependencies for build and runtime
+-------------------------------------
+
+* libglib-2.0 and libgobject v2.34 or later. (https://gitlab.gnome.org/GNOME/glib)
+* libhinawa v2.1 or later (https://github.com/alsa-project/libhinawa)
+* zlib (https://zlib.net/)
+
+For build
+---------
+
+* Meson Build system (https://mesonbuild.com/) is used.
+
+For runtime
+-----------
+
+* ALSA fireworks driver uses the same address space on 1394 OHCI controller for Fireworks protocol,
+  therefore it's better to unload the driver in advance of using the tool.
+* FFADO applications should be stopped to avoid misfortune.
+
+Build and Install
+=================
+
+::
+
+    $ meson (--prefix=xxx, -Dman=false). build
+    $ cd build
+    $ ninja
+    $ meson install
+
+* The ``man`` meson option is to install online manual for the tool. Default is ``true``.
+
+Instruction
+===========
+
+The tool consists of two sub commands; ``device`` and ``file``. The former is to operate on-board
+flash memory, and the latter is to handle file of firmware blob.
+::
+
+    efw-downloader SUBCOMMAND OPTIONS ...
+
+    SUBCOMMAND = device | file
+
+    OPTIONS = ( depends on subcommand )
+
+The ``device`` sub command consists of several operations. At present, ``read`` operation is just
+supported but the other operations are planned to add for future release.
+::
+
+    efw-downloader device PATH OPERATION ARGUMENTS
+
+    PATH   The path to special file for firewire character device corresponding to node of Fireworks board module.
+
+    OPERATION
+           One of read , and help operations.
+
+    ARGUMENTS for read operation
+
+           efw-downloader device PATH read OFFSET SIZE [ --debug | --help | -h ]
+
+           The offset argument is the hexadecimal number of offset on flash memory.
+
+           The size argument is the hexadecimal number of size to read, aligned to quadlet automatically.
+
+           The optional --debug argument is to enable debug output for Fireworks protocol.
+
+           The optional --help and -h arguments are for help message.
+
+    ARGUMENTS for help operation
+
+           efw-downloader device PATH help
+
+           The help operation have no arguments.
+
+The ``file`` sub command consists of several operations as well. At present, ``parse`` operation is
+just supported but the other operations are planned to add for future release.
+::
+
+    efw-downloader file FILEPATH OPERATION ARGUMENTS
+
+    FILEPATH
+           The path to file of firmware blob included in driver package shipped by vendors.
+
+    OPERATION
+           One of parse , and help operations.
+
+    ARGUMENTS for parse operation
+
+           efw-downloader file FILEPATH parse [ --help | -h ]
+
+           The --help and -h argument is for help message.
+
+    ARGUMENTS for help operation
+
+           efw-downloder file FILEPATH help
+
+           The help operation have no arguments.
-- 
2.25.1