update readme, start readout_parser docs (no content yet)

README.md

@@ -10,6 +10,8 @@ to build high-performance MVLC based DAQ readout systems are provided:
 * Configuration holding the setup and readout information for a single VME
   crate containing multiple VME modules.
 
+  JSON and YAML formats are currently implemented.
+
 * Multithreaded readout worker and listfile writer using fast data compression
   (LZ4 or ZIP deflate).
 
@@ -30,17 +32,18 @@ software.
 
 * [MVLC command format](doc/command_format.md)
 * [MVLC data format](doc/data_format.md)
+* [The readout_parser module](doc/readout_parser.md)
 * [mvme manual](https://mesytec.com/downloads/mvme/mvme.pdf)
 
-  The mvme manual contains a section about the MVLC Trigger/IO system. mvme VME
-  script supports all implemented MVLC commands.
+  The mvme manual contains a section about the MVLC Trigger/IO system. mvme *VME
+  scripts* supports all implemented MVLC commands.
 
 ## Building
 
 ```sh
 apt-get update && apt-get install -y --no-install-recommends \
-ca-certificates build-essential git cmake ninja-build zlib1g-dev \
-libzmq3-dev cppzmq-dev
+  ca-certificates build-essential git cmake ninja-build zlib1g-dev \
+  libzmq3-dev
 
 mkdir build && cd build
 cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=~/local/mesytec-mvlc .. \
@@ -50,6 +53,8 @@ ctest .
 
 Dockerfiles can be found [here](tools/dockerfiles).
 
+Pass `-DMVLC_BUILD_DEV_TOOLS=ON -DMVLC_BUILD_TOOLS=ON` to cmake to build additional tools.
+
 ## Tools
 
 * `mvlc-cli`: command line interface to the MVLC. Useful subcommands:
@@ -65,8 +70,6 @@ Dockerfiles can be found [here](tools/dockerfiles).
   files exported from mvme. Writes readout data to listfile and/or dumps it to
   console.
 
-Pass `-DMVLC_BUILD_DEV_TOOLS=ON -DMVLC_BUILD_TOOLS=ON` to cmake to build additional tools.
-
 * `mvlc-listfile-info <zipfile>`: Processes the input listfile, showing
   information about the contained configuration and decoded readout/system
   events. Quick as it does not process the actual readout data.

doc/readout_parser.md

@@ -0,0 +1,20 @@
+# MVLC readout_parser module
+
+## Problem
+
+Parse an incoming - possibly lossful - stream of buffers containing MVLC readout
+data into a stream of events containing module readout data.
+
+```
+input data: USB data stream or ETH packet stream
+
+                        +-----------------+    +-----------------+
+   +--------+           | output event N  |    | output event N+1|
+   | 0xF3.. |           +-----------------+    +-----------------+
+   | ...... |           | module0         |    | module0         |
+   | 0xF5.. |  ->       | payload         |    | payload         | ...
+   | ...... |           +-----------------+    +-----------------+
+   | ...... |           | module1         |    | module1         |
+   ..........           | payload         |    | payload         |
+   +--------+           +-----------------+    +-----------------+
+```