.. _felix-trickle:

felix-trickle
===========================

`felix-trickle` is a `felix-star` application that sends configuration data
towards Front-End electronics.
Like `felix-toflx`, the application receives messages from the network,
encodes them into FromHost messages and transfers them to the corresponding
Trickle DMA buffer.

   .. note::
    The `trickle` DMA buffer has one major difference from `felix-toflx`:
    it is a ring buffer, that the firmware will continuously read once
    the trickle configuration is written in it.

Trickle
----------------------

The top-level class is `Trickle`, used to build two executables: `felix-trickle`
that works with a FELIX card and `felix-trickle2file` that emulates the hardware.
`Trickle` is templated to support both use cases.
The template parameters are three: the configuration parameters, the type of FromHost DMA buffer
(that interfaces with the FELIX driver or not) and the type of FELIX device
(real or emulated).
`Trickle` owns (by composition) devices, DMA buffers and writers.
It is responsible for creating a `TrickleManager` instance for each FELIX device,
and a `Receiver` for each buffer.

.. note::
   The Receiver can only be unbuffered, and uses only the TCP network mode.


.. doxygenclass:: trickle::Trickle
  :no-link:
  :members:


TrickleManager
----------------------

`TrickleManager` is the class that implements the API that allows to receive a
trickle configuration and write it into the DMA buffer.
The most important thing to know is that the commands received from the client
are all in JSON format.

.. doxygenclass:: trickle::TrickleManager
  :no-link:
  :members:


FromHost Buffer
----------------------
The buffer handling is managed by FromHost Buffer, which can be referenced in
:ref:`felix-toflx`.
The class has been enhanced with some methods for trickle configuration.

.. doxygenfunction:: FromHostBuffer::trickle_padding
.. doxygenfunction:: FlxFromHostBuffer::dma_start_circular_trickle_buffer
.. doxygenfunction:: FlxFromHostBuffer::set_oneshot_trickle_buffer
.. doxygenfunction:: FileFromHostBuffer::dma_start_circular_trickle_buffer
.. doxygenfunction:: FileFromHostBuffer::set_oneshot_trickle_buffer