]> jspc29.x-matter.uni-frankfurt.de Git - daqdocu.git/commitdiff
Added small howto implement external trigger sources
authorManuel Penschuck <manuel.penschuck@stud.uni-frankfurt.de>
Fri, 5 Apr 2013 11:26:53 +0000 (13:26 +0200)
committerManuel Penschuck <manuel.penschuck@stud.uni-frankfurt.de>
Fri, 5 Apr 2013 11:26:53 +0000 (13:26 +0200)
trb3/CtsHowtos.tex

index 4018e8d8cef766429cd29d00877377237831d6e2..e4392b8c207e6ed70c03ab0729da40e2a38d6725 100644 (file)
@@ -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
    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: <your-entity-here>
    );
 \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