move docs around, write a bit of README, new dockerfile for debian:testing

Author: flueke

.dockerignore

@@ -0,0 +1 @@
+build/

README.md

@@ -1,4 +1,4 @@
-# mesytec-mvlc - driver and utilities for the [mesytec MVLC VME Controller](https://mesytec.com/products/nuclear-physics/MVLC.html)
+# mesytec-mvlc - driver and utilities for the mesytec MVLC VME Controller
 
 *mesytec-mvlc* is a driver and utility library for the [Mesytec MVLC VME
 controller](https://mesytec.com/products/nuclear-physics/MVLC.html) written in
@@ -24,4 +24,64 @@ to build high-performance MVLC based DAQ readout systems are provided:
 * Various counters for monitoring the system.
 
 mesytec-mvlc is used in the [mvme](https://mesytec.com/downloads/mvme.html) DAQ
-software to implement MVLC support.
+software.
+
+## Documentation
+
+* [MVLC command format](doc/command_format.md)
+* [MVLC data format](doc/data_format.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.
+
+## 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
+
+mkdir build && cd build
+cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=~/local/mesytec-mvlc .. \
+cmake --build . --target all
+ctest .
+```
+
+Dockerfiles can be found [here](tools/dockerfiles).
+
+## Tools
+
+* `mvlc-cli`: command line interface to the MVLC. Useful subcommands:
+  - scanbus: Scans the upper 16 bits of the VME address space for (mesytec) VME modules.
+  - register_read/register_write: Internal register access.
+  - vme_read/vme_write: Single cycle VME access.
+  - stack_info: Print readout command stack and trigger information.
+  - show_usb_devices: Info about MVLC USB devices found on the system.
+
+  `mvlc-cli -h -a` shows help for all implemented commands.
+
+* `mvlc-mini-daq`: Standalone minimal DAQ tool. Configuration via .yaml/json
+  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.
+
+* `decode-mvlc-frame-header`: reads raw frame headers from stdin, attempts to
+  decode and print information:
+  ```
+   $ ./decode-mvlc-frame-header 0xf380001f
+   0xf380001f -> StackResultFrame (len=31, stackNum=0, ctrlId=0, frameFlags=continue)
+   ```
+
+* `decode-mvlc-eth-headers <header0> <header1>`: decodes the ETH frame header words:
+  ```
+  ./decode-mvlc-eth-headers 0x00070004 0x00010000
+  header0 = 0x00070004, header1 = 0x00010000
+  header0: packetChannel=0, packetNumber=7, controllerId=0, dataWordCount=4
+  header1: udpTimestamp=16, nextHeaderPointer=0x0000, isHeaderPointerPresent=1
+  ```

doc/command_format.md

@@ -47,7 +47,7 @@ vme_read_mem 0x09 d16 0x0000
 ```
 
 In combination with **read_to_accu** and **mask_shift_accu** this can be used to
-read a transfer count from a module and use it to create a fake block transfer.
+read a transfer count from a module to create a fake block transfer.
 
 **signal_accu** creates an MVLC internal IRQ signal using the current accu
 *value. This can be used to dispatch

doc/framing_and_eth.md doc/data_format.md

@@ -1,3 +1,6 @@
+
+** Incomplete, old and untested **
+
 Using the mesytec-mvlc library {#usage-guide}
 =============================================
 

doc/Registers_User_CMDs.pdf doc/dev/Registers_User_CMDs.pdf

@@ -0,0 +1,21 @@
+# syntax=docker/dockerfile:1.5
+# vim:ft=dockerfile
+
+# Dockerfile building the mesytec-mvlc library in debug mode and running the
+# libraries unit tests.
+
+# Example docker build invocation from the root of the source tree:
+#   DOCKER_BUILDKIT=1 docker build  -f ./tools/dockerfiles/Dockerfile.debian-testing_ctest .
+
+FROM debian:testing
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates build-essential git cmake ninja-build zlib1g-dev \
+    libzmq3-dev cppzmq-dev
+
+COPY . /sources
+WORKDIR /build
+
+# Run cmake then compile and install the server binary.
+RUN cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/install /sources \
+    && ninja && ninja install && ctest .