From 9120cabc673b63be46aea90a6f3b5daf1b2c519b Mon Sep 17 00:00:00 2001 From: Manuel Penschuck Date: Fri, 5 Apr 2013 13:26:53 +0200 Subject: [PATCH] Added small howto implement external trigger sources --- trb3/CtsHowtos.tex | 97 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 7 deletions(-) diff --git a/trb3/CtsHowtos.tex b/trb3/CtsHowtos.tex index 4018e8d..e4392b8 100644 --- a/trb3/CtsHowtos.tex +++ b/trb3/CtsHowtos.tex @@ -1,11 +1,20 @@ \newpage +\label{sec:cts_howto_external_trigger} \subsection{HowTo Implement an External Trigger Module} -\label{sec:cts_howto_external_trigger} + This short tutorial will guide you through the steps necessary to implement an External Trigger Module: + \begin{itemize*} + \item VHDL: Encapsulate the Trigger Logic into an entity (only the interface is discussed here - see section \ref{sec:cts_howto_etm_instantiation}) + \item VHDL: Instantiate the module and connected it to the system (see section \ref{sec:cts_howto_etm_instantiation}) + \item VHDL/Perl: Reserve a module id and implement the software support (see section \ref{sec:cts_howto_etm_instantiation}) + \end{itemize*} + \subsubsection{The module's interface} +\label{sec:cts_howto_etm_instantiation} An External Trigger Module (ETM) gives you the means to implement a high-level trigger criterion that does not require the preprocessing of the general purpose trigger inputs. A typical example is a network bridge. A CTS build can include at - most one ETM. The module is directly linked to the trigger channel with the highest priority. + most one ETM. The module is directly connected to the trigger channel with the highest priority, thus if the ETM asserts + the trigger line while the CTS is idle, the TrbNet Event Type of the next event is defined by the type configured for the ETM. Listing \ref{lst:cts_howto_etm_instantiation} shows a minimal ETM instantiation. For a better readability, it is highly recommended, that you keep the port's naming. Copy this into the top entity (\filename{trb3\_central.vhd}). Make sure @@ -13,10 +22,15 @@ signals, e.g. to interface with off-board electronics. The semantics of the CTS interface are very straight-forward: \begin{itemize*} - \item Assert the \signal{cts\_ext\_trigger} line to indicate an event. If the CTS is idle (as indicated by a - non-asserted \signal{trigger\_busy\_i}), a single pulse of 1 clock cycle suffices. + \item Synchronously assert the \signal{cts\_ext\_trigger} line to indicate an event. If the CTS is idle (as indicated by a + non-asserted \signal{trigger\_busy\_i}), a pulse of one clock cycle suffices. If you want the CTS to distribute + your event even if the system is busy, you have to keep the line asserted until the the busy line becomes low. However, + take into account, that in this case the trigger distribution might be delayed depending on the system's dead time, thus + introducing a jitter of several 100~ns. - \item The Read-Out Channel is directly connected to a FEE IPU Channel. See the HADES DAQ manual for more information. + \item If your module has to send information to the event build, you need to implement the read-out channel. Otherwise + just leave it unconnected - the default values instruct the frontend to send no data. The Read-Out Channel is directly + connected to a FEE IPU Channel. See the HADES DAQ manual for more information. \item \signal{cts\_ext\_control} offers you a 32~bit control register without any restrictions on the mapping. It is connected to a synchronous output of the CTS and controlled by the trigger logic. If you need more than 4~byte, @@ -51,7 +65,76 @@ THE_ETM: ); \end{lstlisting} -\subsubsection{Registering the module} - no content yet +\subsubsection{Obtaining a module id and registering the module} + As discussed in chapter \ref{sec:cts_slow_control}, the software identifies the capabilities of any given CTS by enumerating + over a sequence of module headers each containing a module id. The software then loads the drivers located in + \filename{daqtools/web/CtsPlugins/CtsMod.pm}. This is also the central database of module ids. Just choose + a free number, use the template shown in listing \ref{lst:cts_howto_driver_template}) to create a new driver and check it in, + to ensure nobody else takes this id. + + + + \begin{warning} + The ETM's id has to be provided to the CTS via the generic constant \genericname{EXTERNAL\_TRIGGER\_ID}. The trigger logic then + automatically reserves a memory block with two words payload (the status- and control register mentioned above). Even if your module, + does not require slow control access, it is vital that you specify an id: The constant also functions as an indicator for the + presence of an ETM. If the default value is not overridden, your trigger line is not routed to the trigger logic. + \end{warning} + + +\begin{lstlisting}[ + language=Perl, % + escapechar=!, % + basicstyle=\scriptsize, % + label=lst:cts_howto_driver_template, % + caption={[CTS Tool - Plug-In File: ETM Template] Each plug-in has to implement the \texttt{moduleName} + method, which is used for introspection purposes, and the \texttt{init} method, that defines all registers and properties. + Line 1 to 16 are identical (with expection to the header id and the module's name) in all plug-ins. Registers and + properties are created as attributes of the plug-in instance. They are automatically linked to the central file + by the parent class \texttt{CtsBaseModule}. This might, again, be useful for introspection purposes, as it allows + to determine which registers are defined by a plug-in during run-time. It is, however, currently not used. + } +] +package CtsMod!\textbf{}!; +@ISA = (CtsBaseModule); +use warnings, strict, TrbRegister; + +sub moduleName {"!\textbf{}!"} + +sub init { + my $self = shift; + my $address = shift; + my $cts = $self->{'_cts'} + my $regs = $self->{'_registers'}; + my $prop = $self->{'_properties'}; + my $header = $cts->{'_enum'}{!\textbf{}!}->read(); +# END OF TEMPLATE + +# registers + $regs->{"!\textbf{}!_config"} = new TrbRegister($address + 0, + $cts->getTrb, {}, + { + 'label' => $self->moduleName . "Config", # feel free to change + 'accessmode' => "rw", # control register: read/write access + 'monitor' => 1, # regularly fetch in monitoring mode + 'export' => 1 # save value when exporting CTS config + }); + + $regs->{"!\textbf{}!_status"} = new TrbRegister($address + 1, + $cts->getTrb, {}, + { + 'label' => $self->moduleName . " Status", #feel free to change + 'accessmode' => "ro", # status register: read-only access + 'monitor' => 1 # regularly fetch in monitoring mode + }); + +# human-readable itc assignment, e.g. displayed right to the ITC num in gui. +# feel free to change. + $cts->getProperties->{'itc_assignments'}[$header->{'itc_base'}] = $self->moduleName; + +# properties + $prop->{"!\textbf{}!"} = True; # or some non-false value +} 1; +\end{lstlisting} \ No newline at end of file -- 2.43.0