
% ===============================================================================
% Purpose: Software of the AIDA mini-TLU
% Author: Francesco Crescioli
% Created on: 2013-03-27
% ===============================================================================
\newcolumntype{C}[1]{>{\small\centering\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}

\section{Software}
\label{sec:Software}

The TLU control software is based on two main frameworks: EUDAQ\cite{ref:eudaq} and $\mu$HAL\cite{ref:uhal} framework.\\

\subsection{$\mu$HAL}

The $\mu$HAL hardware abstraction framework is a component of the wider CACTUS framework developed for the upgrades of the CMS Level-1 Trigger. It can be compiled and used separate from the rest of the CACTUS framework.\\
The $\mu$HAL library provides a simple and flexible way to describe the hardware registers and other memory elements. The hardware is described in XML files and it reflects also the internal hierarchy of the firmware.\\
The tree structure described in XML is made accessible with robust C++ classes with methods for I/O operations. On the other side of the interface the communication with the hardware is done using the UDP-based IPBus protocol. This abstraction layer provides an efficient separation between the firmware implementation and the C++ access to hardware memory elements.

\subsection{EUDAQ}

EUDAQ is a simple and easy to use data aquisition framework, written in C++. It was originally designed to be used for the EUDET JRA1 beam telescope.\\
It provides a simple and flexible structure to build a DAQ system.\\
The framework provides several GUI interfaces. For example the run controller is shown in figure \ref{fig:eudaq_runcontrol} and the histogram viewer for online monitoring is shown in figure \ref{fig:eudaq_monitor}.\\

\begin{figure}
  \centering
    \includegraphics[width=0.4\textwidth]{figs/eudaq_runcontrol.png}
  \caption{EUDAQ Run Controller}
  \label{fig:eudaq_runcontrol}
\end{figure}

\begin{figure}
  \centering
    \includegraphics[width=0.7\textwidth]{figs/eudaq_monitor.png}
  \caption{EUDAQ Online Monitor}
  \label{fig:eudaq_monitor}
\end{figure}


The other main components of the framework are networked deamons. The ``producers'' have the task to communicate with the hardware and produce the data stream. The ``data collector'' has the task to receive all data streams from the producers and collect them in a structured binary file for offline analysis.\\
The deamons communicate to the run controller and each other via TCP/IP. The run controller provides commands to coordinate the state transitions of all connected daemons (ie. to configure or to start a data taking run).

\subsubsection{TLU Producer}
The EUDAQ component for the mini-TLU is the TLU\_IPbusProducer.\\
This producer can access all TLU registers via the abstraction provided by $\mu$HAL.\\
\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Base address & Type \\ \hline
FirmwareVersion  & 0x00000000 & register \\ 
EMACHostbus      & 0x00000002 & subsystem \\ 
DUTInterfaces    & 0x00000020 & subsystem \\ 
TriggerInputs    & 0x00000040 & subsystem \\ 
TriggerLogic     & 0x00000060 & subsystem \\
EventBufferc     & 0x00000080 & subsystem \\
I2C              & 0x000000c0 & subsystem \\
TriggerGenerator & 0x000000e0 & subsystem \\
ShutterGenerator & 0x00000100 & subsystem \\
SpillGenerator   & 0x00000120 & subsystem \\
EventFormatter   & 0x00000140 & subsystem \\
\hline
\end{tabular}
\caption{Root level $\mu$HAL nodes}
\label{tab:uhal_top}
\end{table}

\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Leaf address & Type \\ \hline
SerdesRst  & 0x00000000 & register \\ 
\hline
\end{tabular}
\caption{Trigger inputs subsystem $\mu$HAL nodes}
\label{tab:uhal_triggerinputs}
\end{table}

\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Leaf address & Type \\ \hline
PostVetoTriggers        & 0x00000000 & register \\ 
PreVetoTriggers         & 0x00000001 & register \\ 
InternalTriggerInterval & 0x00000002 & register \\ 
TriggerMask             & 0x00000003 & register \\ 
TriggerVeto             & 0x00000004 & register \\ 
ExternalTriggerVeto     & 0x00000005 & register \\ 
ResetCounters           & 0x00000006 & register \\ 
\hline
\end{tabular}
\caption{Trigger logic subsystem $\mu$HAL nodes}
\label{tab:uhal_triggerlogic}
\end{table}

\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Leaf address & Type \\ \hline
EventFifoData           & 0x00000000 & register \\ 
EventFifoFillLevel      & 0x00000001 & register \\ 
EventFifoCSR            & 0x00000002 & register \\ 
EventFifoFillLevelFlags & 0x00000003 & register \\ 
\hline
\end{tabular}
\caption{Event buffer subsystem $\mu$HAL nodes}
\label{tab:uhal_eventbuffer}
\end{table}

\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Leaf address & Type \\ \hline
LogicClocksCSR          & 0x00000000 & register \\ 
LogicRst                & 0x00000001 & register \\ 
\hline
\end{tabular}
\caption{Logic clocks subsystem $\mu$HAL nodes}
\label{tab:uhal_logicclocks}
\end{table}

\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Leaf address & Type \\ \hline
TriggerLength           & 0x00000000 & register \\ 
TrigStartupDeadTime     & 0x00000001 & register \\ 
TrigInterpulseDeadTime  & 0x00000002 & register \\ 
TriggerDelay            & 0x00000003 & register \\ 
NMaxTriggers            & 0x00000004 & register \\ 
TrigEvtNumber           & 0x00000005 & register \\ 
RstTriggerCounter       & 0x00000006 & register \\ 
TrigRearmDeadTime       & 0x00000007 & register \\ 
\hline
\end{tabular}
\caption{Trigger generator subsystem $\mu$HAL nodes}
\label{tab:uhal_triggergenerator}
\end{table}

\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Leaf address & Type \\ \hline
ShutterLength           & 0x00000000 & register \\ 
ShutStartupDeadTime     & 0x00000001 & register \\ 
ShutInterpulseDeadTime  & 0x00000002 & register \\ 
ShutterDelay            & 0x00000003 & register \\ 
NMaxShutters            & 0x00000004 & register \\ 
ShutEvtNumber           & 0x00000005 & register \\ 
RstShutterCounter       & 0x00000006 & register \\ 
ShutRearmDeadTime       & 0x00000007 & register \\ 
\hline
\end{tabular}
\caption{Shutter generator subsystem $\mu$HAL nodes}
\label{tab:uhal_shuttergenerator}
\end{table}

\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Leaf address & Type \\ \hline
SpillLength              & 0x00000000 & register \\ 
SpillStartupDeadTime     & 0x00000001 & register \\ 
SpillInterpulseDeadTime  & 0x00000002 & register \\ 
SpillDelay               & 0x00000003 & register \\ 
NMaxSpills               & 0x00000004 & register \\ 
SpillEvtNumber           & 0x00000005 & register \\ 
RstSpillCounter          & 0x00000006 & register \\ 
SpillRearmDeadTime       & 0x00000007 & register \\ 
\hline
\end{tabular}
\caption{Spill generator subsystem $\mu$HAL nodes}
\label{tab:uhal_spillgenerator}
\end{table}

\begin{table}[t]
\centering
\begin{tabular}{|r|c|r|}
\hline
Node-Id & Leaf address & Type \\ \hline
EnableRecordData          & 0x00000000 & register \\ 
\hline
\end{tabular}
\caption{Event formatter subsystem $\mu$HAL nodes}
\label{tab:uhal_eventformatter}
\end{table}

The hierarchy of the various modules within the firmware is reproduced. The top level is described in table \ref{tab:uhal_top}. At top level the only accessible register is the firmware version, all the other memory elements are contained in a subsystem.\\
The available subsystems are described in tables \ref{tab:uhal_triggerinputs} to \ref{tab:uhal_eventformatter}. The IPBus address of each memory element can be computed by adding the ``leaf address'' to the ``base address'' of the subsystem. On the C++ TLU Producer software all memory elements are accessed by the ``Node-Id'' name.\\

The TLU Producer software handles the commands from run control and provides high level configuration to the TLU unit. It also reads the Event Buffer FIFO in the TLU and send the corresponding stream of data to the EUDAQ data formatter.\\
All functions of the TLU Producer are available in a standalone command line program for debugging purposes.
