felix-direct-readout API
========================

The felix-direct-readout interface provides very simple function to read ToHost DMA buffers.
An instance of the interface class reads a single DMA buffer defined by:

- a  host-level unique id defined as ``10 * device number + DMA ID``;
- the buffer size in units of ToHost blocks;
- the NUMA node on which the buffer must be allocated.

An instance is created using the factory function:

.. code-block:: C
   :linenos:

   felix_readout::FelixInputBufferInterface* felix_input_buffer_factory(unsigned int u_id, unsigned int size_blocks, unsigned int numa_node)


The interface enables reading of the enabled (e-)links in the DMA buffer.
The (e-)link fids contain the detector and connector identifier set by the registers
DETECTOR_ID_VALUE and CONNECTOR_ID_X_VALUE, provided that the corresponding DETECTOR_ID_VALID
and CONNECTOR_ID_X_VALID are true.

.. doxygenfunction:: felix_readout::FelixInputBufferInterface::get_enabled_elinks
  :no-link:

The blocks available, that is those in between the write pointer maintained by firmware and the
read pointer maintained by software are returned by:

.. doxygenfunction:: felix_readout::FelixInputBufferInterface::get_available_blocks
  :no-link:

The read pointer is advanced using a uint64_t block counter.

.. doxygenfunction:: felix_readout::FelixInputBufferInterface::set_read_ptr_blocks
  :no-link:


Example
.......
The felix-direct-readout interface is used by Data Handler, which loads the
implementation library dynamically using the `felix_proxy <https://gitlab.cern.ch/atlas-tdaq-software/felix_proxy>`_ wrapper.