\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
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,
);
\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<lower-case-hex-id>.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{<ETM-ID>}!;
+@ISA = (CtsBaseModule);
+use warnings, strict, TrbRegister;
+
+sub moduleName {"!\textbf{<Human Readable Name of ETM>}!"}
+
+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{<ETM-ID>}!}->read();
+# END OF TEMPLATE
+
+# registers
+ $regs->{"!\textbf{<ETM-ABBR>}!_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{<ETM-ABBR>}!_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{<ETM-ABBR>}!"} = True; # or some non-false value
+} 1;
+\end{lstlisting}
\ No newline at end of file
jspc29 / daqdocu.git / commitdiff