=====================================
VME / Analysis Template System (VATS)
=====================================

Note: To get a listing of which templates are loaded and which modules are defined start mvme and
use 'Tools -> VME/Analysis Template System Info'.

Note: User defined module typeIds start at 160. Ids < 160 are reserved!


Each subdirectory contains the template data for one VME module. Exceptions are
the special auxiliary_scripts/, event/ and mvlc_trigger_io/ directories. Event
templates are described below, the auxiliary_scripts and mvlc_trigger_io
scripts are handled differently (see src/template_system.cc).


Event Templates
---------------

The special 'event' directory should contain 4 vmescript files:

  event_daq_start.vmescript         Executed at DAQ start time. Used for multicast Counter reset and
                                    Acq start.
  event_daq_stop.vmescript          Executed at DAQ stop time. Used for multicast Acq stop.
  readout_cycle_start.vmescript     Start of the readout commands. Currently empty.
  readout_cycle_end.vmescript       End of the readout commands. Used for multicast readout reset.

These files are loaded when the user creates a new event via the GUI.


Module Templates
----------------

Version 2 (single .mvmemodule file)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Newer way of storing module and meta information. Uses a single .mvmemodule
json file with two root keys: 'ModuleConfig' containing the serialized json
data and 'ModuleMeta' containing module meta information stored in a json
object. Compatible files can be created via the 'Save Module to File' context
menu entry in the vme config tree.

Multiple .mvmemodule files can be put in the same module subdirectory.


Version 1 (script files in subdirectory)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Other subdirectories represent VME modules. The layout is:

  module_dir/
    module_info.json
    analysis/
      default_filters.analysis
    vme/
      init-00-Module Init.vmescript
      init-01-VME Interface Settings.vmescript
      readout.vmescript
      reset.vmescript

Description of the per module files and directories:

* module_info.json
    - typeId (required):
      The _unique_ module identifier used in the listfile event header (8 bit
      ModuleTypeMask).

    - typeName (required):
      The _unique_ module type name used in VME and analysis configuration
      files.

    - displayName (required):
      User visible name of the module.

    - eventHeaderFilters (optional):
      List of { "filter": <str>, "description": <str> } structures.
      The filter strings are used to split multievent readout data from the
      module into single events. Multiple filters can be specified if the module
      has more than one header format, e.g. for MDPP sampling and non-sampling
      modes.
      The placeholder 'S' in each filter word is used to extract the number of
      data words following the module header.
      The optional placeholder 'M' can be used to extract a module id from the
      header word as a consistency check.

    - vmeBaseAddress (optional):
      A string(!) that is parseable as a unsigned 32 bit value which is used as
      the suggested VME module address when creating a new module of this type.

  Important: typeIds and typeNames must not be changed once they're in use for a module. Doing so
  would break listfile and config file compatibility!

* vme/
  readout.vmescript     The readout commands for this module. Becomes part of the readout stack for the
                        corresponding event.
  reset.vmescript       Special module reset script. Used at DAQ start time before configuring the
                        module. Should leave the module in a clean default state.

  init-00-Module Init.vmescript
  init-01-VME Interface Settings.vmescript
  ... More scripts as required by the module. These scripts are loaded in alphabetical order when
      creating a new module. At DAQ start time the scripts are executed in order to initialize the
      module. The part after the second '-' and before the filename extension is used in the GUI as
      the script title.

Analysis filter templates
^^^^^^^^^^^^^^^^^^^^^^^^^

* analysis/
  - default_filters.analysis:
    An analysis file created via the GUI which is used when choosing the
    'Generate default filters' action and when adding a new filter: The file is
    loaded as a standard analysis file and new internal object ids are
    generated. Then all objects are moved to the target modules event context
    and all data sources are assigned to the target module.

Obsolete  Module Type IDs
-------------------------

Removed Module Type IDs
^^^^^^^^^^^^^^^^^^^^^^^
* 21    vmmr_1ns (consolidated with the vmmr module)

Previous Module Type Enum
^^^^^^^^^^^^^^^^^^^^^^^^^
Before adding the VATS a hardcoded enum was used to hold the module type IDs. The original values
are included for reference:

enum class VMEModuleType
{
    Invalid = 0,
    MADC32  = 1,
    MQDC32  = 2,
    MTDC32  = 3,
    MDPP16  = 4,
    MDPP32  = 5,
    MDI2    = 6,

    MesytecCounter = 16,
    VHS4030p = 21,
};
