--- /dev/null
+@url{Shower2,
+key={SHW},
+title={Shower AddOn 2 Schematics},
+language={american},
+note={\url{http://hades-wiki.gsi.de/pub/DaqSlowControl/TDCReadoutBoardV2/shower-addon2-SCM.pdf}}
+}
+
+@url{MDCOEP,
+key={OEP},
+title={MDC Optical Endpoint 3 Schematics},
+language={american},
+note={\url{http://hades-wiki.gsi.de/pub/DaqSlowControl/TDCReadoutBoardV2/MDC_OEP3-SCM3.pdf}}
+}
+
+@url{Hub2,
+key={HUB},
+title={Hub AddOn 2 Schematics},
+language={american},
+note={\url{http://hades-wiki.gsi.de/pub/DaqSlowControl/TDCReadoutBoardV2/TRB-HUB2-SCM.pdf}}
+}
+
+
+@url{ADCM,
+key={RICH},
+title={RICH ADCM 3 Schematics},
+language={american},
+note={\url{http://hades-wiki.gsi.de/pub/DaqSlowControl/TDCReadoutBoardV2/RICH_ADCMv3.pdf}}
+}
--- /dev/null
+[General]
+img_extIsRegExp=false
+img_extensions=.eps .jpg .jpeg .png .pdf .ps .fig .gif
+kileprversion=2
+kileversion=2.0
+lastDocument=daqstartup.tex
+masterDocument=main.tex
+name=trbnet
+pkg_extIsRegExp=false
+pkg_extensions=.cls .sty
+src_extIsRegExp=false
+src_extensions=.tex .ltx .latex .dtx .ins
+
+[Tools]
+MakeIndex=
+QuickBuild=PDFLaTeX+ViewPDF
+
+[item:daqstartup.tex]
+archive=true
+column=212
+encoding=UTF-8
+highlight=LaTeX
+line=3
+open=true
+order=8
+
+[item:hubs.tex]
+archive=true
+column=28
+encoding=
+highlight=LaTeX
+line=56
+open=true
+order=6
+
+[item:ipudataformat.tex]
+archive=true
+column=0
+encoding=UTF-8
+highlight=LaTeX
+line=26
+open=true
+order=1
+
+[item:lvl1trigger.tex]
+archive=true
+column=153
+encoding=UTF-8
+highlight=LaTeX
+line=53
+open=true
+order=2
+
+[item:main.tex]
+archive=true
+column=41
+encoding=UTF-8
+highlight=LaTeX
+line=57
+open=true
+order=0
+
+[item:memory.tex]
+archive=true
+column=0
+encoding=UTF-8
+highlight=LaTeX
+line=0
+open=false
+order=8
+
+[item:networkaddresses.tex]
+archive=true
+column=0
+encoding=UTF-8
+highlight=LaTeX
+line=73
+open=true
+order=3
+
+[item:showerdata.tex]
+archive=true
+column=0
+encoding=UTF-8
+highlight=LaTeX
+line=0
+open=true
+order=7
+
+[item:slowcontrol.tex]
+archive=true
+column=11
+encoding=UTF-8
+highlight=LaTeX
+line=177
+open=true
+order=4
+
+[item:software.tex]
+archive=true
+column=0
+encoding=UTF-8
+highlight=LaTeX
+line=128
+open=true
+order=5
+
+[item:trbnet.kilepr]
+archive=true
+column=142153217
+encoding=
+highlight=
+line=0
+open=false
+order=-1
--- /dev/null
+
+\subsection{Overview}
+
+One of the advantages of the new slow control system is that all subsystems now can be addressed and configured with one common interface. There is no need to log in to several boards and execute system specific commands there.
+
+The startup procedure for each subsystem consists of several files:
+
+\begin{itemize}
+ \item A documentation that shows which steps have to be done in which order
+ \item Table with serial numbers (serials\_*.db)
+ \item Table with addresses / positions on the detector (addresses\_*.db)
+ \item Names of design files to load in the FPGAs (designfiles.db, in the main directory)
+ \item Settings that have to be loaded to the FPGA (register\_*.db)
+ \item Trbcmd-scriptfiles with specific sequences of commands (trbcmd\_*.db)
+ \item A script file with the commands to be executed (startup.script)
+\end{itemize}
+
+While the documentation is a simple text file, the other files follow some easy style rules to make them readable for both humans and scripts:
+
+\begin{itemize}
+ \item Comments are always preceded by a hash ``\#'' and mask the rest of the line from scripts
+ \item Columns of tables are aligned to be easily readable
+ \item Columns are separated by at least two spaces
+ \item Hexadecimal values always have a ``0x'' prefix
+ \item Empty columns should be filled with a ``0''
+\end{itemize}
+
+Despite these common rules the structure of each type of file will be different as explained below.
+
+
+
+\subsection{Script files}
+All tasks that have to be done during startup are listed in the \filename{startup.script}. This script is interpreted by the main startup script written in Perl. the available commands are:
+\begin{description}
+ \item[\cmdname{trbcmd \$command}] The \$command will be passed directly to trbcmd. \cmdname{-f \$filename} can be used to load a file with commands.
+ \item[\cmdname{daqop \$command}] The \$command will be passed directly to daqop.
+ \item[\cmdname{load\_register register\_*.db}] Loads registers with values as described in \ref{daqregisters}.
+ \item[\cmdname{set\_addresses serials\_*.db addresses\_*.db}] Sets the addresses of boards according to the two database files as described in \ref{daqserials}.
+ \item[\cmdname{exec\_script script\_*.script}] Executes the given script file as if the commands where given directly in the parent script file.
+ \item[\cmdname{check\_versions designfiles.db addresses\_*.db}] Checks if the loaded design files correspond to the given settings in the database. See \ref{daqdesignfiles}.
+ \item[\cmdname{load\_fpgas designfiles.db addresses\_*.db}] Loads the designs described in designfiles.db to the boards listed in the address database.
+\end{description}
+
+In the scriptfile conditional expressions can be used. For this, \cmdname{!ifdef \$name} and \cmdname{!ifndef \$name} are available. The part of code following such a statement will be skipped until the closing \cmdname{!endif} statement. The identifiers \cmdname{\$name} are given to the main script using the option \cmdname{-m} (See the code excerpt below for an example. Here different thresholds are selected using \cmdname{-m thresh\_experimental}).
+
+The script file that will be exectued can be select by using the \cmdname{-f} option on the main perl script. The option \cmdname{-e} selects the network name of the TRB on which the script will be executed.
+
+\lstset { caption ={Example: MDC startup.script}}
+\begin{lstlisting}
+#Assign addresses
+ set_addresses serials_mdcaddon.db addresses_mdcaddon.db
+ set_addresses serials_oep.db addresses_oep.db
+
+#Load settings for OEP
+#initialize ADC
+ trbcmd -f trbcmd_init_adc.trbnet
+#load thresholds
+!ifdef thresh_experimental
+ load_register register_thresholds_experimental.db
+!endif
+!ifndef thresh_experimental
+ load_register register_thresholds.db
+!endif
+
+#load channel masks
+ load_register register_channels.db
+
+#Initialize FEE
+ trbcmd w 0xfffd 0x20 1
+ trbcmd w 0xfffd 0xc1 0x00000000
+ load_register register_configuration.db
+\end{lstlisting}
+
+
+\subsection{Serial Numbers and Network Setup}
+\label{daqserials}
+
+To assign addresses to the endpoints, two things have to be known: First, a relationship between the serial number printed on each board and the internal unique id of the temperature sensor is needed. Second, the position on the detector and hence the network address has to be related to the serial number.
+
+For this purpose, two different config files are used: One is only modified during production of boards, the other can be changed whenever boards are replaced or newly installed on the detector. The name of both files should have a similar name that clearly identifies the type of board it belongs to.
+
+As shown in the examples below, the table with serial numbers has only two entries: The serial number and the unique id as returned by \texttt{trbcmd i}.
+
+The table with addresses has five columns, besides the address and the serial number of the board there is also the number of the FPGA (in case there is more than one FPGA) that gets this address. For boards with only one FPGA this number should also be there for compatibility reasons. The fourth column is an index to the table of design files and gives the information, which design file has to be loaded on this FPGA (see section ``design files''). The last column is the serial number of the TRB the board is connected to. In case of a stand-alone board, the TRB number is 0. This information is needed to log in on the TRB to load the design files into the FPGAs.
+
+
+\lstset { caption ={Example: serials\_oep.db}}
+\begin{lstlisting}
+#Serial numbers of OEP and their unique ids
+# s/n # unique id
+###########################
+ 021 0x62000001fc57e328
+ 022 0x5e000001fc535c28
+ 023 0x59000001fc488628
+ 025 0x15000001fc5c5328
+\end{lstlisting}
+
+
+\lstset { caption ={Example: addresses\_oep.db}}
+\begin{lstlisting}
+# Address # S/N # FPGA # Design # TRB #
+###################################################
+ 0x2000 021 1 12 0
+ 0x2001 025 1 12 0
+ 0x2002 024 1 12 0
+ 0x2003 023 1 12 0
+ 0x2004 022 1 12 0
+\end{lstlisting}
+
+
+\subsection{Registers}
+\label{daqregisters}
+The most common operation is to load some settings to registers on the FPGA. In many cases, different registers at different addresses have to be written which are different for each frontend board. For this reason, the register database file is the most complicated:
+\lstset { caption ={Example: register\_thresholds.db}}
+\begin{lstlisting}
+!Register table
+# Type # C0 # C1 # C2 # C3 # C4 # C5 #
+#######################################################
+ 1 0xA049 0xA04B 0xA04D 0xA04F
+ 2 0xA0CD 0xA0CF 0xA0D1 0xA0D3 0xA0D5 0xA0D7
+
+!Value table
+# OEP # Type # T0 # T1 # T2 # T3 # T4 # T5 #
+###################################################
+ 0x2000 1 0xff 0xff 0xff 0xff
+ 0x2001 2 0xff 0xff 0xff 0xff 0xff 0xff
+ 0x2002 2 0xff 0xff 0xff 0xff 0xff 0xff
+ 0x2003 1 0xff 0xff 0xff 0xff
+\end{lstlisting}
+
+The first part of the file lists the register addresses the data has to be written to. As you can see, in this case to different sets of registers do exist, marked with the type number. Depending on the type there might be a different number of registers.
+
+The second part lists the values for each endpoint individually: The first entry is the network address of the endpoint, the second one is the register set to use as listed in the first table. Then an appropriate number of values (max. 32bits each as defined by TrbNet) follows.
+
+Both tables is preceded by a marker (either ``!Register'' or ``!Value``) using ''!`` as an escape character to mark the start of the tables for the parser.
+
+\subsection{Trbcmd Scripts}
+\label{daqtrbcmd}
+For special tasks a standard trbcmd script file will be used to define the necessary operations. There can be an arbitrary number of distinct script files containing different procedures. One advantage of this format is that you are able to run these configuration scripts also independently from the startup using the \cmdname{trbcmd -f} option.
+
+\lstset { caption ={Example: script\_oep\_initadc.trbnet}}
+\begin{lstlisting}
+#Initialize ADC
+w 0xfffd 0x8001 0xd
+w 0xfffd 0x8001 0x9
+\end{lstlisting}
+
+
+\subsection{Design Files}
+\label{daqdesignfiles}
+The table of design files is one table for all subsystem (and thus in the ``main'' directory) which gives the information which FPGA on which type of board has to be loaded with which design files. Addtionally the compile time of the design will be given. This can be read out from the boards from register 0x40 and serves as a version number for the design.
+
+Since the unpacker should be able to work in a data-driven mode, the version of the event data format should be included in the header. This can be accomplished by writing the data version number to a register (t.b.d.) on all SubEvent-building nodes during startup. The number has a size of 4 bits and therefore the maximum value is 16.
+
+
+\lstset { caption ={Example: designfiles.db}}
+\begin{lstlisting}
+#ID# Board/FPGA #Comp. Time# Filename #IPU#
+##########################################################
+ 8 TRBSlwCtrl 0x4ab38e12 trb2_ctrl_20091030.stp 1
+ 9 MDCAddOnFPGA1 0x12347832 mdcopt_1_20091027.stp 1
+ 10 MDCAddOnFPGA2 0x12347832 mdcopt_2_20091027.stp 1
+\end{lstlisting}
+
+
--- /dev/null
+The block of VHDL entities that provide the interface between the application (the ``user'') and the network is called endpoint. The top level entity is \filename{trb\_net16\_endpoint\_hades\_full.vhd} on almost all frontends. Here, a frontend is defined as a data-collecting FPGA that only has connections to one other FPGA. FPGAs with more than one connection are Hubs (E.g. the Shower AddOn contains two frontends and one hub).
+
+The endpoint provides the logical interface for transporting data. Besides, one also needs a media interface entity that implements the logic needed to physically transport data from one FPGA to another. Which entity has to be used depends on the type of hardware. Its ports are all named \portname{Med\_*} and need no further description in this place.
+
+The majority of ports of the endpoint are used to interface all three channels on TrbNet, namely LVL1 trigger, IPU Data and Slow Control. The \portname{Stat\_*} and \portname{Ctrl\_*} ports are mainly used for debugging and can be left unconnected.
+
+The standard ports of the entity include a \portname{Clk} input (100MHz), a \portname{Reset} signal which is essential for the entity to work correctly and a \portname{Clk\_En}. The latter should be left unconncected despite there is a situation where the whole board whould be stopped.
+
+\subsection{Generic Settings}
+The endpoint features many generic settings to configure the behaviour for the users needs. Most of them should be kept at there default value and are not described here.
+
+The global settings for the endpoint are:
+\begin{description}
+ \item[\portname{Clock\_Frequency}] The frequency of the main clock in MHz. Normally 100 MHz.
+ \item[\portname{Address\_Mask}] The address mask used for replacement boards. See section \ref{ReplacementAddresses}
+ \item[\portname{Broadcast\_Bitmask}] The lower 8 bit of the specific broadcast address. See section \ref{BroadcastAddresses}
+ \item[\portname{Regio\_Init\_Address}] The initial network address. Should be a number above 0xF000.
+ \item[\portname{Regio\_Init\_Board\_Info}] 32bit word to give information about the board type, hardware version etc. Bits can be defined by user.
+ \item[\portname{Regio\_Init\_Endpoint\_Id}] The number of the FPGA on the board. For boards with one single FPGA 1.
+ \item[\portname{Regio\_Compile\_Time}] Unix timestamp when the design has been synthesized. There is an automatic perl script available that generates this value, but the user has to care about this.
+ \item[\portname{Regio\_Compile\_Version}] Version number of the design. Definition is up to user.
+ \item[\portname{Regio\_Hardware\_Version}] Version number of the hardware. Definition is up to user.
+\end{description}
+
+\subsection{Common Error and Status Bits}
+For each transmission there are 32 bits that give a rough overview of the status of the boards and transport error information. The meaning of the upper 16 bit depends on the channel while the lower 16 bit are the same on all channels. Their meaning is given in table \ref{commonerrorbits}. From these bits, only bit 4 can be set by the user, the rest is generated inside the network.
+
+
+\begin{table}
+\begin{center}
+\begin{tabularx}{\textwidth}{c|c|C}
+\textbf{Bits} & \textbf{Name} & \textbf{Description} \\
+0 & endpoint reached & At least one endpoint has been addressed by the transfer. If not set, no endpoint with the given address exists in the network. \\
+1 & collision detected & Used in the (theoretical) case that two active endpoints send data at the same time. The initial transfer this reply belongs to has been lost. \\
+2 & word missing & There was a mismatch between an internal packet counter and the length transported in an EOB packet.\\
+3 & checksum mismatch & There was a mismatch between an internally generated checksum and one received with a EOB or TRM packet. \\
+4 & don't understand & The addressed endpoint does not know how to treat the incoming data. \\
+5 & buffer mismatch & The numbers of sent EOB and received ACK do not match. \\
+6 & answer missing & An endpoint connected to a hub did not send an answer. \\
+7 - 15 & t.b.d & Bits not yet used. Reserved. \\
+\end{tabularx}
+\caption{Common Error- and Status information contained in the network termination packet on all channels}
+\label{commonerrorbits}
+\end{center}
+\end{table}
+
+
--- /dev/null
+\subsection{Status Registers}
+\label{hubstatusregs}
+\begin{description}
+ \item[0x80 - 0x83: Locked Ports] One register for each TrbNet channel. Each bit gives the status of one port: 1 when the hub is waiting for a reply on this port, 0 if not.
+ \item[0x84: Active Ports] Status of all ports. Each bit gives the current status of one port: 1 when the link is active and able to transport data, 0 if not.
+ \item[0x85: Uplinks] Configuration of the Ports. Each bit gives the configuration of one port: 1 if this port is configured as an uplink, 0 if not.
+ \item[0x86: Downlinks] Configuration of the Ports. Each bit gives the configuration of one port: 1 if this port is configured as downlink, 0 if not.
+ \item[0x87: IPU channel state] Shows the current state of the state machine handling the IPU channel.
+ \begin{description}
+ \item[0 - 3:] FSM state
+ \begin{description}
+ \item[0x0] IDLE
+ \item[0x1] Waiting for reply
+ \item[0x2] Waiting to get complete HDR data
+ \item[0x3] Checking event information
+ \item[0x4] Calculating length
+ \item[0x5] Wait for complete DHDR
+ \item[0x6] Checking DHDR
+ \item[0x7] Sending Data
+ \item[0x8] Enable arbiter, switching to next endpoint
+ \item[0x9] Sending padding
+ \item[0xA] Sending reply termination
+ \item[0xB] Waiting for init channel to finish
+ \item[0xF] Default value
+ \end{description}
+ \item[4 - 9:] don't care
+ \item[10 - 12:] current packet counter
+ \item[13 - 15:] read pointer to DHDR memory
+ \end{description}
+ \item[0x88 - 0x8B: Timeouts $\dagger$] One register for each TrbNet channel. Each bit gives the status of one port: 1 if there was a timeout on this port, 0 otherwise. These registers are cleared after being read.
+ \item[0x8C - 0x8F: Waiting for ACK] One register for each TrbNet channel. Each bit gives the status of one port: 1 if data transmission on this port is stopped because the receiver did not acknowledge previous EOB words, 0 otherwise.
+ \item[0xA0 - 0xA3: Error-/Status-Bits $\dagger$] One register for each TrbNet channel. Each register is the last Error-/Status-Bits, combined from all ports.
+ \item[0xA4: Slow Control Error $\dagger$] One bit for each port. 1 if either one of the Errorbits 1,3,6 on the slow control channel have been set before. This register is cleared after being read.
+ \item[0x4000 - 0x400F: IPU Packet counter] One register for each port. Each register is a 32 bit counter of the packets (with 64bit payload each) received on the IPU channel on this port. A write to 0x4000 resets all counters.
+ \item[0x4010 - 0x401F: Slow Control Packet counter] One register for each port. Each register is a 32 bit counter of the packets (with 64bit payload each) received on the slow control channel on this port. A write to 0x4010 resets all counters.
+ \item[0x4020 - 0x402F: Error Bits $\dagger$] One register for each port. Contents are part of the last Error-/Status-Bits received on this port:
+
+ \begin{itemize}
+ \item Bit 0 - 7 of each register: Bit 0 - 7 of Errorbits on LVL1 channel
+ \item Bit 8 - 15: Errorbits 16 - 23 on LVL1 channel
+ \item Bit 16 - 23: Errorbits 0 - 7 on IPU channel
+ \item Bit 24 - 31: Errorbits 16 - 23 on IPU channel
+ \end{itemize}
+
+\end{description}
+$\dagger$: Register is not reset during network reset
+
+\subsection{Control Registers}
+\label{hubcontrolregs}
+\begin{description}
+ \item[0xC0 - 0xC3: Port Switch] One register for each TrbNet channel. Each bit controls one port. 1: port is switched on (default). 0: port is switched off.
+ \item[0xC4: Port Disable] One bit for each port. Each bit controls one port. 1: port is powered down. 0: port is switched on (default).
+ \item[0xC5: Timeouts] Configure duration of timeout for each channel. Each hex digit controls one channel. 0xF switches off timeouts, values 0x0 - 0x7 set timeout to $2^{(2 \cdot value+1)}$ms (2,8,32,128ms;1,4,16,64s). Default is 0x106F (8ms on slow control, 1s on IPU, off on LVL1).
+ \item[0xC6: Network Reset] One bit for each port. Sends a network reset to the selected ports. 1: send network reset on port, 0: normal operation. Has to be cleared by user.
+\end{description}
+
+\subsection{RegIO Data Port}
+\begin{description}
+ \item[0x0000 - 0x00FF] Standard internal RegIO addresses
+ \item[0x1000 - 0x3FFF] Reserved in hub\_base for monitoring features
+ \item[0x4000 - 0x7FFF] Reserved in hub\_base
+ \item[0x8000 - 0xBFFF] Forwarded to \portname{REGIO} ports of hub\_base, reserved for GbE
+ \item[0xC000 - 0xFFFF] Forwarded to \portname{REGIO} ports of hub\_base, reserved for board specific funtions, e.g. 0xD000 - 0xD2FF for Flash programming
+\end{description}
+
--- /dev/null
+\subsection{Overview}
+
+The data collected after a LVL1 trigger has been received has to be stored inside a memory which is able to hold at least twenty to thirty normal-sized events or one maximum-sized event (this is the absolute minimum - the more the better).
+
+The start of each transmission is a network header (5x 16bit) which does not carry necessary information on the IPU channel. The end is formed by the network termination packet (again 5x 16bit), which can transport some basic error information. Every hub and every frontend contributes to this error information. Since this 32 bit wide information has the same meaning in every stage, it is shown in a seperated section (\ref{ipustatusbits}).
+
+These words are all generated by the endpoint and not by the user. The event information and data the user has to send is described in chapter \ref{ipudataformatfee}. How the structure of the data stream changes while being transported from the frontends through several hubs and to the final SubEvent structure is shown in the following chapters.
+
+
+\subsection{The IPU User Interface}
+The ports on the IPU interface are described in the following list. An exemplary timing diagram can be found in figure \ref{fig:ipudatauserinterface}:
+\begin{description}
+ \item[IPU\_NUMBER\_OUT] (16 bit) Number of the requested event. Is valid while \portname{IPU\_START\_READOUT} is high.
+ \item[IPU\_READOUT\_TYPE\_OUT] (4 bit) Reserved bits to select how data should be handled, i.e. LVL2 trigger decision. Is valid while \portname{IPU\_START\_READOUT} is high.
+ \item[IPU\_INFORMATION\_OUT] (8 bit) Additional reserved bits to transport detailed configuration for this readout. Bit 3 -- 0 are used to select one Eventbuilder from a table of up to 16 MAC/IP/Port combinations in SubEventBuilders. Is valid while \portname{IPU\_START\_READOUT} is high.
+ \item[IPU\_START\_READOUT\_OUT] The rising edge shows that a readout request has been received. While signal is high \portname{IPU\_NUMBER}, \portname{IPU\_TYPE} and \portname{IPU\_INFORMATION} are valid. The falling edge comes after the user set \portname{IPU\_\-READOUT\_\-FINSISHED} and the endpoint finished sending data.
+ \item[IPU\_DATA\_IN] (32 bit) The port on which the application sends data to the network / event builder.
+ \item[IPU\_DATAREADY\_IN] Shows that data on \portname{IPU\_DATA} is valid
+ \item[IPU\_READ\_OUT] High when the IPU interface is able to read data on \portname{IPU\_DATA}. Data is actually read when \portname{IPU\_DATAREADY} and \portname{IPU\_READ} are high at the same time.
+ \item[IPU\_READOUT\_FINISHED\_IN] Set by the user for one clock cycle after the last data word has been read by the ipu interface.
+ \item[IPU\_LENGTH\_IN] (16 bit) Length of data, counted in 32 bit words. Has to be valid from the first rising edge of \portname{IPU\_DATAREADY} until one clock cycle after \portname{IPU\_READ\_OUT} is set as well.
+ \item[IPU\_ERROR\_PATTERN\_IN] (32 bit) Status and error information bits. Has to be valid while \portname{IPU\_READOUT\_FINISHED} is high.
+\end{description}
+
+
+
+\begin{figure}
+ \centering
+ \includegraphics[width=0.9\textheight, angle= 90]{ipudata.png}
+ \caption[Timing Diagram: IPU User Interface]{A example timing diagram showing the signals on the IPU Data Interface for one full event containing three data words from the FEE plus DHDR and status information.}
+ \label{fig:ipudatauserinterface}
+\end{figure}
+
+
+\subsection{Data Format on Frontends}
+\label{ipudataformatfee}
+
+\begin{table}
+\begin{center}
+\begin{tabular}{l|c|c|c|c}
+\textbf{Bits} & \textbf{31 -- 24} & \textbf{23 -- 16} & \textbf{15 -- 8} & \textbf{7 -- 0} \\
+\hline
+\textbf{Event Information} & R R R P T T T T & Random Code & \multicolumn{2}{c}{Event Number} \\
+\hline
+\textbf{Data Header} & \multicolumn{2}{c|}{Length} & \multicolumn{2}{c}{Endpoint Address} \\
+\hline
+\textbf{Data Words} & \multicolumn{4}{c}{Data1} \\
+\textbf{Data Words} & \multicolumn{4}{c}{Data2} \\
+\textbf{Data Words} & \multicolumn{4}{c}{Data3} \\
+ & \multicolumn{4}{c}{...} \\
+\end{tabular}
+\caption{IPU Data sent from any frontend. Single letters are explained in the text}
+\label{IPUData_Overview}
+\end{center}
+\end{table}
+
+
+The data structure is shown in table \ref{IPUData_Overview}. The first word that is sent by each frontend is the Data header (DHDR) that contains event information, namely the 16 bit event number, the 8 bit wide random trigger code, the 4 bit wide trigger type (T) and a so-called ``pack-bit'' (P). The remaining three bits are reserved (R) for future use.
+
+The second word is formed by the IPU interface itself based on the information the user inputs on \portname{IPU\_LENGTH}.
+It contains the length of data following (counted in 32 bit words) and the TrbNet address of the frontend board. This dataword is generated automatically by the endpoint itself.
+
+Afterwards, all event data is sent. The datastructure depends on the specific requirements of the frontend. It is suggested to put a general data descriptor in the first word, then followed by event data and / or debug information if needed.
+
+The frontend has to send the event information and data header in any case, also when there is no event data available, e.g. because no hit was detected.
+
+All data on the IPU channel is organized in 32 Bit wide words. On the network, hidden from the user, these are transported in two 16 bit words, MSB first.
+
+
+
+\subsection{Data Stream generated by Hubs}
+A hub merges data from one or more senders into a single data stream. Table \ref{IPUData:Hub1} shows the resulting data stream in case of a hub with two connected frontends, one delivering two data words, the other only one data word.
+
+The event information word is read from all connected frontends, checked to be right for the expected event and then sent as a single word in the beginning of the data stream. Afterwards, the hub adds up the length information in the data header from all received data streams and generates a new data header, containing the overall length and the network address of the hub. Finally, all incoming data is forwarded starting with the data header of each data stream.
+
+
+\begin{table}
+\begin{center}
+\begin{tabular}{l|c|c|c|c}
+
+\textbf{Bits} & \textbf{31 -- 24} & \textbf{23 --. 16} & \textbf{15 -- 8} & \textbf{7 -- 0} \\
+\hline
+\textbf{Event Information} & R R R 1 T T T T & Random Code & \multicolumn{2}{c}{Event Number} \\
+\hline
+\textbf{Data Header Hub1} & \multicolumn{2}{c|}{Length (5)} & \multicolumn{2}{c}{Hub Address} \\
+\hline
+\textbf{Data Header FEE1} & \multicolumn{2}{c|}{Length (2)} & \multicolumn{2}{c}{FEE1 Address} \\
+\hline
+\textbf{Data Words} & \multicolumn{4}{c}{Data1 FEE1} \\
+ & \multicolumn{4}{c}{Data2 FEE1} \\
+\hline
+\textbf{Data Header FEE2} & \multicolumn{2}{c|}{Length (1)} & \multicolumn{2}{c}{FEE1 Address} \\
+\hline
+\textbf{Data Words} & \multicolumn{4}{c}{Data1 FEE2}
+
+\end{tabular}
+\caption{Hub merging data from two frontends in non-packing mode}
+\label{IPUData:Hub1}
+\end{center}
+\end{table}
+
+
+
+This operation mode is called non-packing mode. Opposed to that, the packing mode (table \ref{IPUData:Hub1_packing}) would remove the data headers received from the frontends. This can only be done if the remaining data stream still contains all information needed to unpack and process the data.
+
+Which of the two operating modes is used is chosen based on the ``pack-bits'' received in the event information word: If this bit is set in all received data streams, then (and only then) the packing is enabled. Data sent from frontends will always have the pack bit cleared, so that the address information is always kept.\footnote{Even though the RICH data format would allow to remove the length/source information from the frontends, it will be kept. The first argument is, that the overhead generated by these words is negligible. The second more important point is, that the SubEventBuilder has to be able to add his own data words to the end of the data stream and therefore needs to put its own length/source information to the data stream. Without this information it would not be possible to detect the end of event data and the start of SubEventBuilder information}
+
+The packing mode does not only reduce the amount of data, but has another advantage as well: In the non-packing mode, each additional layer of hubs would add another Data Header with a new overall length and a new hub address. Then the program unpacking the data is not able to know how many data headers will appear before the first data word without additional information (i.e. the number of hubs used) not contained in the data stream. Therefore, the first hub will set the pack-bit in its outgoing data stream in any case to allow (possible) next hub to remove its data header.
+
+Under this assumption, the number of data headers stays constant, no matter how many hubs the data is passed through. If the frontend data does not allow packing (e.g. MDC), there are two data headers before the first data word. If the frontend allows packing (e.g. RICH), there is only one data header.
+
+
+\begin{table}
+\begin{center}
+\begin{tabular}{l|c|c|c|c}
+
+\textbf{Bits} & \textbf{31 -- 24} & \textbf{23 -- 16} & \textbf{15 -- 8} & \textbf{7 -- 0} \\
+\hline
+\textbf{Event Information} & R R R 1 T T T T & Random Code & \multicolumn{2}{c}{Event Number} \\
+\hline
+\textbf{Data Header Hub1} & \multicolumn{2}{c|}{Length (3)} & \multicolumn{2}{c}{Hub Address} \\
+\hline
+\textbf{Data Words} & \multicolumn{4}{c}{Data1 FEE1} \\
+ & \multicolumn{4}{c}{Data2 FEE1} \\
+ & \multicolumn{4}{c}{Data1 FEE2}
+
+\end{tabular}
+\caption{Hub merging data from two frontends in packing mode}
+\label{IPUData:Hub1_packing}
+\end{center}
+\end{table}
+
+\subsection{Debugging Information from Hubs}
+To send debugging information, the hubs are allowed to add an own data header and an arbitrary number of data words to the end of each transfer. This data will then appear as if it comes from another endpoint but has the network address from the hub. Clearly this feature can only be used when the hub is used in a non-packing mode, since otherwise the hub debug data can not be detected properly.
+
+\begin{table}
+\begin{center}
+\begin{tabular}{l|c|c|c|c}
+
+\textbf{Bits} & \textbf{31 -- 24} & \textbf{23 -- 16} & \textbf{15 -- 8} & \textbf{7 -- 0} \\
+\hline
+\textbf{Event Information} & R R R 1 T T T T & Random Code & \multicolumn{2}{c}{Event Number} \\
+\hline
+\textbf{Data Header Hub1} & \multicolumn{2}{c|}{Length (7)} & \multicolumn{2}{c}{Hub Address} \\
+\hline
+\textbf{Data Header FEE1} & \multicolumn{2}{c|}{Length (2)} & \multicolumn{2}{c}{FEE1 Address} \\
+\hline
+\textbf{Data Words} & \multicolumn{4}{c}{Data1 FEE1} \\
+ & \multicolumn{4}{c}{Data2 FEE1} \\
+\hline
+\textbf{Data Header FEE2} & \multicolumn{2}{c|}{Length (1)} & \multicolumn{2}{c}{FEE1 Address} \\
+\hline
+\textbf{Data Words} & \multicolumn{4}{c}{Data1 FEE2}\\
+\hline
+\textbf{Data Header Hub} & \multicolumn{2}{c|}{Length (1)} & \multicolumn{2}{c}{Hub Address} \\
+\hline
+\textbf{Data Words} & \multicolumn{4}{c}{Data1 Hub}
+\end{tabular}
+\caption{Hub merging data from two frontends in non-packing mode and adding some debug information}
+\label{IPUData:Hub1_debug}
+\end{center}
+\end{table}
+
+
+\subsection{Streaming API}
+The streaming API (mostly included in a streaming port Hub is the place where data can be extracted from TrbNet and be sent on using another media, e.g. GbE. The corresponding interface consists of three parts:
+\begin{itemize}
+ \item Information about the IPU readout and the requested event. This interface (ports \portname{Cts\_*}) is equivalent to the ports on \filename{trb\_net16\_ipudata}.
+ \item The \portname{Fee\_*} ports are used to receive data sent by frontends.
+ \item The other half of \portname{Cts\_*} (again identical to \filename{trb\_net16\_ipudata}) is used to send status information or parts of the data to the CTS.
+\end{itemize}
+A typical transaction on these interfaces is shown in the timing diagrams.
+
+\begin{figure}
+ \centering
+ \includegraphics[width=0.9\textheight, angle= 90]{ipuinterface_start.png}
+ \includegraphics[width=0.9\textheight, angle= 90]{ipuinterface_end.png}
+ \caption[Timing Diagram: Streaming interface I]{Streaming interface I: Start of readout and data receiving from FEE.\\Streaming interface II: End of readout data from FEE}
+ \label{fig:ipudatastreaming1}
+\end{figure}
+
+\begin{figure}
+ \centering
+ \includegraphics[width=0.9\textheight, angle= 90]{ipu_interface_endcts.png}
+ \caption[Timing Diagram: Streaming interface III]{Streaming interface III: End of transaction, sending answer to CTS}
+ \label{fig:ipudatastreaming3}
+\end{figure}
+
+\subsection{The SubEventBuilder}
+Before data transported on TrbNet can be forwarded via Ethernet to the Event Builder, a SubEventHeader has to be added. This will always be done as the last processing step inside an FPGA, no matter whether the data is then directly sent via Gigabit Ethernet or piped through an Etrax CPU.
+(At least, this is our plan, for the meantime building subevents is up to the software)
+
+The SubEventBuilder reads the first two words, namely Event Information and the Data Header from the last hub, and generates a SubEventHeader based on this information.
+
+The bits 3 to 0 of \portname{Ipu\_Information\_Out} give the information, to which Eventbuilder the data has to be sent (see table \ref{IPUInformationBits}). These bits select the right entry from a table with up to 16 individual Eventbuilders. If a change occurs, the current UDP packet will be finished and sent, the new Eventbuilder address will be loaded and the next UDP packet will be created.
+
+\begin{table}[htbp]
+\begin{center}
+\begin{tabularx}{\textwidth}{l|l|X}
+\textbf{Bit} & \textbf{Name} & \textbf{Description} \\
+3 -- 0 & Eventbuilder ID & ID of the Eventbuilder data should be sent to \\
+7 -- 4 & reserved & \\
+\end{tabularx}
+\caption{IPU Information sent by CTS and interpreted on FEE and SubEventBuilders.}
+\label{IPUInformationBits}
+\end{center}
+\end{table}
+
+\begin{table}
+\begin{center}
+\begin{tabularx}{\textwidth}{l|C|C}
+\textbf{Bits} & \textbf{31 .. 16} & \textbf{15 .. 0} \\
+\hline
+\textbf{SubEventHeader} & \multicolumn{2}{c}{SubEventSize} \\
+ & \multicolumn{2}{c}{SubEventDecoding} \\
+ & \multicolumn{2}{c}{SubEventID (fixed network address of SubEventBuilder)} \\
+ & \multicolumn{2}{c}{SubEventTriggerNumber} \\
+\hline
+\textbf{Data Header} & Length FEE1 & FEE1 Adress \\
+\textbf{Data Words} & \multicolumn{2}{c}{Data1 FEE1} \\
+ & \multicolumn{2}{c}{...} \\
+\hline
+\textbf{Data Header} & Length FEE2 & FEE2 Adress \\
+\textbf{Data Words} & \multicolumn{2}{c}{Data1 FEE2} \\
+ & \multicolumn{2}{c}{...} \\
+\hline
+\textbf{Data Header} & Length SEB (1) & 0x5555 \\
+\textbf{Add. Information} & \multicolumn{2}{c}{SubEventInformation}
+\end{tabularx}
+\caption{Data output of the SubEventBuilder (here: non-packed format. In packed format, the data headers would be missing)}
+\label{IPUData:SubEventBuilder}
+\end{center}
+\end{table}
+
+\subsection{Network Termination Packet: Error and Status Information}
+\label{ipustatusbits}
+The network termination packet transports an overview of errors that happened during readout. There are 16 bits of information as shown in table \ref{Errorbits}.
+
+This information is transported in the same manner as hubs add debug data, namely with an additional data header in the end of the datastream.
+
+The first bits (16 -- 19) are generated by checks performed in every stage of data transfer in the network. These are consistency checks the user / endpoint can not affect. Bits 24 to 27 are used to transport error status information to the CTS, for example when there was a problem reading data from detector electronics such as TDC (e.g. ``token missing'').
+
+\begin{table}
+\begin{center}
+\begin{tabularx}{\textwidth}{c|c|X}
+\textbf{Bits} & \textbf{Name} & \textbf{Description}\\
+16 & evt. number mismatch & The event number in the data stream does not match the requested event number. Set by hubs or IPU interface. \\
+17 & trg. code mismatch & Mismatch in upper 16bit of DHDR word. Set by hubs or IPU interface. \\
+18 & wrong length & Length submitted in DHDR does not match real length. Set by Hubs. \\
+19 & answer missing & a board sent a short transfer instead of DHDR or no answer at all. Set by Hubs. \\
+20 & not found & requested event number does not match stored event number. Set by user. \\
+21 & partially not found & parts of the data are missing. Set by user. \\
+22 & severe problem & serious sync problem detected - intervention needed. Set by user. \\
+23 & single broken event & event data corrupted, next event most likely not affected. Set by user. \\
+24 & Ethernet link broken & Ethernet link to send data is down. Data has been lost. \\
+25 & SubEvent buffer almost full & The buffer to store events in the Ethernet interface is almost full, a stop within the next few events is likely \\
+26 & & \\
+27 & & \\
+28 & & \\
+29 & & \\
+30 & & \\
+31 & & \\
+\end{tabularx}
+\caption{Error- and Status information contained in the network termination packet}
+\label{Errorbits}
+\end{center}
+\end{table}
\ No newline at end of file
--- /dev/null
+
+
+\subsection{Trigger Procedure Overview}
+In the new system each trigger consists of to separated events: First, a timing trigger is received on the dedicated trigger input which delivers accurate timing information and starts the readout cycle.
+
+Some microseconds later (typically 2 - 3 us) the LVL1 trigger packet will be received over TrbNet. The information will be completely decoded internally in the endpoint and given to the user using the interface described in section \ref{LVL1userinterface}. This
+packet contains the trigger number, trigger type and additional information. In total, 52 Bits of information can be transported with each trigger packet.
+
+Despite the trigger number a second feature is used to identify events: The trigger packet contains a random code that has to be stored with the event data and is checked during readout. This gives a better protection from event mixing than a deterministic counter which can easily be screwed up by an erroneous increase signal.
+
+As soon as the frontend is able to handle the next timing trigger, the trigger is released (like the busy release in our old system) by setting the corresponding signal on the user interface along with basic error information as described in section \ref{LVL1Errorbits}.
+
+\subsection{Trigger-less Triggers}
+For calibration triggers the separation into timing trigger and LVL1 trigger packet causes some difficulties: The timing trigger would start the readout process, but some time later the trigger packet arrives stating that there is no normal event but a calibration should be done instead. This then would cause the readout logic to discard the gathered data and start readout again in calibration mode.
+
+Therefore, for calibration and similar triggers there will be no timing trigger but only a LVL1 trigger packet. To distinguish this situation from an error on the timing cable, the distinction is made based on the trigger type. Trigger types 0 to 7 are preceded by a timing trigger, types 8 to F are not. To allow for further checks, also Bit 7 of the trigger information will be set for LVL1 triggers without timing trigger. Additionally the user logic can provide some checks to assure that e.g. a normal trigger must always be preceded by a timing trigger.
+
+
+
+\subsection{User Interface}
+\label{LVL1userinterface}
+\begin{figure}
+ \centering
+ \includegraphics[width=0.9\textheight, angle= 90]{triggerinterface.png}
+ \caption[Timing Diagram: LVL1 Trigger Interface]{LVL1 Trigger Interface timing}
+ \label{fig:triggerinterface}
+\end{figure}
+
+\begin{description}
+ \item [Lvl1\_Trg\_Type\_Out] The trigger type, similar to the old system.
+ \item [Lvl1\_Trg\_Received\_Out] Rising edge marks that a LVL1 trigger information has been received. Falling edge comes after user set \portname{Lvl1\_Trg\_Release}. While high, \portname{Lvl1\_\-Trg\_\-Type}, \portname{Lvl1\_\-Trg\_Number}, \portname{Lvl1\_\-Trg\_\-Code} and \portname{Lvl1\_\-Trg\_\-In\-for\-mation} are valid.
+ \item [Lvl1\_Trg\_Number\_Out] (16 bit) Trigger number.
+ \item [Lvl1\_Trg\_Code\_Out] (8 bit) A random code generated by CTS that has to be stored and put to the IPU data stream.
+ \item [Lvl1\_Trg\_Information\_Out] (24 bit) Additional information about trigger as explained in the corresponding section.
+ \item [Lvl1\_Error\_Pattern\_In] (32 bit) Error and status bits as explained in the corresponding section. Must be valid when \portname{Lvl1\_\-Trg\_\-Release} is high.
+ \item [Lvl1\_Trg\_Release\_In] Must be set for at least one clock cycle to release the trigger (comparable to the old ``busy release'').
+ \item [Lvl1\_Int\_Trg\_Number\_Out] (16 bit) The internal trigger counter counting the received timing triggers. Will be valid 5 clock cycles after a timing trigger has been received until \portname{Lvl1\_\-Trg\_\-Received} goes down.
+ \item [Trigger\_Monitor\_In] Here are pulse for each received timing trigger has to be connected. This allows the endpoint to generate the \portname{Lvl1\_Int\_Trg\_Number\_Out}.
+\end{description}
+
+\subsection{Status and Error Bits}
+\label{LVL1errorbits}
+The channel specific status and error bits contain information about mismatches between timing triggers and LVL1 trigger information
+
+In general it is preferable to have soft interrupts before a buffer runs full instead of hard stops when the is nearly an overflow. Therefore information about the fill level of data buffers is included in the status bits. The CTS might then block some triggers to give the readout system the possibility to empty buffers again.
+
+In case a board has not been configured correctly to deliver proper data, this information is transported as well. The complete list of bits can be found in table \ref{LVL1Errorbits}
+
+\begin{table}
+\begin{center}
+\begin{tabularx}{\textwidth}{c|c|C}
+\textbf{Bits} & \textbf{Name} & \textbf{Description} \\
+16 & trg. counter mismatch & The internal trigger number does not match the received trigger number. Set by trigger interface or user. \\
+17 & timing trg missing & A LVL1 trigger has been received which needs a timing trigger, but no timing trigger was seen. Set by trigger interface or user. \\
+18 & t.b.d. & Not yet defined \\
+19 & t.b.d. & Not yet defined \\
+20 & buffers half full & The event data buffers are filled halfway. Set by user. \\
+21 & buffers almost full full & The event data buffers are almost full. Set by user. \\
+22 & not configured & Frontend is not configured correctly to handle triggers, an initilization is needed. Set by user. \\
+23 - 31 & t.b.d. & Not yet defined \\
+\end{tabularx}
+\caption{Error- and Status information contained in the network termination packet}
+\label{LVL1Errorbits}
+\end{center}
+\end{table}
+
+
+\subsection{Trigger Types}
+The trigger types don't need a long explanation. As in the old system there are different trigger types for normal triggers and calibration triggers. See table \ref{Triggertypes} for details.
+
+In case a particular trigger type is not supported by one frontend, an empty event will be generated and during readout only a DHDR will be send. No error bit has to be set in this case.
+
+\begin{table}
+\begin{center}
+\begin{tabular}{c|c}
+\textbf{Number} & \textbf{Description} \\
+0 & \\
+1 & Normal Trigger\\
+2 & \\
+3 & \\
+4 & \\
+5 & \\
+6 & \\
+7 & \\
+8 & \\
+9 & MDC Calibration\\
+A & Shower Calibration\\
+B & Shower Pedestals\\
+C & RICH Calibration\\
+D & \\
+E & \\
+F & \\
+\end{tabular}
+\caption{Trigger Types. List is not complete. Triggers 8 to F are not sent in combination with a timing trigger.}
+\label{Triggertypes}
+\end{center}
+\end{table}
+
+\subsection{Trigger Information}
+Each LVL1 trigger contains 24 bits of additional information, transporting details about the trigger and the requested readout procedure such as data format or pre-processing of data.
+
+The lowest bit marks triggers that are not preceded by a timing trigger like the calibration trigger for MDC. The upper 16 bit are used for detector specific information. For RICH this will be information about the desired pre-processing of data. Bits for other systems will be reserved upon request and are not yet defined. See table \ref{LVL1TrgInformation} for a list of bits.
+
+The CTS will include features to set these bits via slow control either to a static value or to select them dynamically, e.g. to be different every hundredth event.
+
+\begin{table}
+\begin{center}
+\begin{tabularx}{\textwidth}{c|c|C}
+\textbf{Bits} & \textbf{Name} & \textbf{Description} \\
+0 & Suppress Output & Run a normal trigger as requested but suppress writing all data to the IPU channel. Small status words or debug output are acceptable. \\
+1 - 6 & t.b.d. & Not yet defined \\
+7 & no timing trigger & Marks a LVL1 trigger which was not preceded by a timing trigger (e.g. calibration) \\
+8 - 10 & RICH & RICH data configuration bits \\
+11 - 13 & Shower & 11: update pedestals, 12: calibrate even (0) or odd (1) channels, 13: tbd\\
+14 - 23 & t.b.d. & Not yet defined \\
+\end{tabularx}
+\caption{Trigger Information Bits.}
+\label{LVL1TrgInformation}
+\end{center}
+\end{table}
--- /dev/null
+
+\documentclass[11pt,a4paper]{scrartcl} %twoside
+
+%Einstellungen der Seitenr�nder
+\usepackage[left=4.0cm,right=2.5cm,top=2.5cm,bottom=2.5cm,includeheadfoot]{geometry}
+
+\usepackage[utf8]{inputenc}
+\usepackage{amsfonts}
+\usepackage[american]{babel}
+\usepackage[T1]{fontenc}
+\usepackage[pdftex]{graphicx}
+\usepackage{pslatex}
+\usepackage{xcolor}
+\usepackage{array}
+\usepackage{rotating}
+\usepackage{multirow}
+\usepackage{tabularx}
+\usepackage{url}
+\linespread{1.15}
+\usepackage{booktabs}
+\usepackage{longtable}
+\usepackage{ltxtable}
+\usepackage{upgreek}
+\usepackage{listings}
+\usepackage{scrtime}
+
+\definecolor{darkblue}{rgb}{0,0,.5}
+\usepackage[linkbordercolor={0 0 0},
+ pdfborder={0 0 0},
+ bookmarks,
+ citecolor=blue,
+ linkcolor=darkblue,
+ colorlinks=true,
+ urlcolor=darkblue]{hyperref}
+\usepackage{cite}
+
+
+\newcolumntype{C}{>{\centering\arraybackslash}X}
+
+\usepackage{fancyhdr}
+\pagestyle{headings}%{fancy}
+\fancyhf{}
+\fancyhead[R]{\nouppercase{\leftmark}}
+\renewcommand{\headrulewidth}{0.5pt}
+\fancyfoot[C]{\thepage}
+%\renewcommand{\footrulewidth}{0}
+%\usepackage[sort,square]{natbib}
+%\usepackage{mathptmx}
+%\usepackage{pslatex}
+
+\title{DaqNet - A Preliminary Handbook}
+\date{\today ~-~\thistime}
+\author{Jan Michel}
+
+
+\newcommand{\filename}[1]{\textit{#1}}
+\newcommand{\portname}[1]{\textsc{#1}}
+\newcommand{\genericname}[1]{\textsc{#1}}
+\newcommand{\constname}[1]{\textsc{#1}}
+\newcommand{\netname}[1]{\textsc{#1}}
+\newcommand{\cmdname}[1]{\texttt{#1}}
+\bibliographystyle{alpha}
+
+\usepackage{remreset}
+\makeatletter\@removefromreset{footnote}{chapter}\makeatother
+
+\lstset{ %language = VHDL,
+ numbers =left,
+ stepnumber =1,
+ frame =single,
+ captionpos=b,
+ breaklines=true
+ % basicstyle=\footnotesize,
+ %identifierstyle=\footnotesize,
+ stringstyle=\footnotesize,
+ numberstyle=\footnotesize,
+ fontadjust=true}
+
+\begin{document}
+\newcounter{line}
+\newcounter{ct}
+
+\maketitle
+\tableofcontents
+\clearpage
+% \chapter{The Endpoint}
+% \input{trigger}
+\part{Network and Startup}
+
+\section{DAQ Startup Config Files}
+ \input{daqstartup}
+
+\clearpage
+\section{Network Addresses}
+ \input{networkaddresses}
+
+
+\clearpage
+\part{Endpoint and Channels}
+\section{The Endpoint}
+ \input{endpoint}
+
+\clearpage
+\section{Channel 0: LVL1 Trigger}
+ \input{lvl1trigger}
+
+
+\clearpage
+\section{Channel 1: IPU Data}
+ \input{ipudataformat}
+
+\clearpage
+\section{Channel 3: Slow Control Endpoint}
+ \input{slowcontrol}
+
+\clearpage
+\part{Detectors and Subsystems}
+\section{Shower}
+ \input{showerdata}
+
+\clearpage
+\section{MDC}
+ \input{mdc}
+
+\clearpage
+\section{RICH}
+ \input{rich}
+
+\clearpage
+\section{Network Hubs}
+ \input{hubs}
+
+
+\clearpage
+\part{Software}
+ \input{software}
+
+\clearpage
+\bibliography{biblio}
+
+\end{document}
\ No newline at end of file
--- /dev/null
+The schematics of the MDC OEP v3 can be found in \cite{MDCOEP}. The schematics of the new MDC Concentrator are nto yet available.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{IPU Data Format}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Memory Map}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{table}[hb]
+\begin{center}
+\begin{tabularx}{\textwidth}{l|l|X}
+\textbf{Address} & \textbf{Name} & \textbf{Description} \\
+8000 - 803F & ADC & Voltage monitoring ADC. see table \ref{MDCOEPADCMemoryMap} \\
+A000 - A0FF & Config. Mem. & Configuration memory for thresholds and TDC settings \\
+D000 & SPI Status Reg. & see section SPI Flash \\
+D001 & SPI Control Reg. & see section SPI Flash \\
+D100 - D13F & SPI Data Mem. & see section SPI Flash \\
+D200 & Flash select & select Flash ROM image \\
+E000 & TDC Readback Fifo & Fifo for readback values from TDC \\
+\end{tabularx}
+\caption{Memory map for MDC OEP}
+\label{MDCOEPMemoryMap}
+\end{center}
+\end{table}
+
+\subsubsection{MDC Optical Endpoint Voltage Monitoring}
+
+
+\begin{table}[hb]
+\begin{center}
+\begin{tabularx}{\textwidth}{l|l|X}
+\textbf{Address} & \textbf{Name} & \textbf{Description} \\
+8000 & Control & Bit 0: ADC enable, 1: single measurement, 2: reset, 3: compare enable\\
+8001 & Overview & 1 nibble for each voltage. Values: 0: voltage ok, 1: too low, 2: too high or combinations thereof. Too low / too high flags are stored until ADC reset. \\
+8010 - 8017 & Current voltage & One register for each channel. Bits 11 - 0 show the current voltage, measured in millivolt.\\
+8018 - 801F & Threshold & One register for each channel. Bits 11 - 0 show the current low threshold, Bits 27 - 16 contain the current high threshold in millivolt. \\
+8020 - 8027 & Min/Max & One register for each channel. Bits 11 - 0 contain the lowest measured value, bits 27 - 16 show the highest measured value. Register are reset on ADC reset.\\
+\end{tabularx}
+\caption{Memory map for MDC OEP voltage monitoring ADCs. The voltages assigned to each channel are shown in table \ref{MDCOEPADCChannels}}
+\label{MDCOEPADCMemoryMap}
+\end{center}
+\end{table}
+
+\begin{table}[hb]
+\begin{center}
+\begin{tabular}{l|l|l}
+\textbf{Channel} & \textbf{Voltage} & \textbf{Nominal Voltage}\\
+0 & 5V input & 5.8V \\
+1 & 5V regulated & 5.0V \\
+2 & 3.6V input & 3.8V \\
+3 & 3.3V regulated & 3.35V\\
+4 & 1.8V input & 1.8V\\
+5 & 1.2V regulated & 1.20V\\
+6 & 3.0V input & 3.0V\\
+7 & -3.0V input & -3.0V\\
+\end{tabular}
+\caption{ADC Channels for MDC OEP voltage monitoring. -3.0V are reported to be +3.0V by ADC. Both 5V channels are connected using a voltage divider, thus reading 2.5V at nominal voltage.}
+\label{MDCOEPADCChannels}
+\end{center}
+\end{table}
+\begin{small}\begin{footnotesize} \end{footnotesize}\end{small}
\ No newline at end of file
--- /dev/null
+The documentation of network addresses can be found in the wiki:
+\url{http://hades-wiki.gsi.de/cgi-bin/view/DaqSlowControl/NetworkAddresses}
+
+\subsection{Addressing scheme}
+On boards with two or more FPGAs each FPGA gets its own address. The FPGA providing the uplink gets the lowest address (usually with 0 as 4th digit), the other FPGAs are numbered in the order they are placed on the board starting with 1 as the last digit.
+
+
+
+\begin{table}[hb]
+\begin{center}
+\begin{tabularx}{\textwidth}{l|l|X}
+\textbf{Address(es)} & \textbf{Board(s)} & \textbf{Description} \\
+0001 & CTS & \\
+0002 & Slow Control & \\
+0003 & 2nd Slow Control & if needed for monitoring \\
+0004 - 00FF & Other CTS-like boards \\
+1000 - 17FF & MDC Concentrator & 2nd digit: inner(0) / outer(1) MDC; 3rd digit: sector (0-5), 4th digit FPGA (0-4) \\
+2000 - 2FFF & MDC OEP & 2nd digit: MDC layer (0-3); 3rd digit: sector (0-5); 4th digit MBO (0-F) \\
+3000 - 31FF & RICH ADCM & 3rd digit: sector (0-5); 4th digit: segment (0-4) \\
+3200 - 37FF & Shower AddOn & 3rd digit: sector (0-5); 4th digit: FPGA (0-2) \\
+4000 - 40FF & Start/Veto & 1 TRB for both detectors \\
+4400 - 47FF & Wall & 3 TRBs for forward wall \\
+4800 - 4BFF & RPC & 3rd digit: sector (0-5), 4th digit: segment (0-3) \\
+4C00 - 4FFF & TOF & 3rd digit: sector (0-5); 4th digit: 0 for normal TRB, 1 for additional TRB to resemble broken channels\\
+5555 & SEB & Dummy Address used in headers generated by SubEventBuilders \\
+8000 - 80FF & CTS Hub & central hub\\
+8100 - 81FF & MDC Hub & Hub for inner MDC (3rd digit 0) or outer MDC (3rd digit 1)\\
+8300 - 83FF & RICH Hubs & Hubs for RICH, last digit: sector divided by 2 \\
+8400 - 84FF & RPC Hubs & Hubs for RPC, last digit: sector divided by 3 \\
+8500 - 85FF & Shower Hub & \\
+8600 - 86FF & TOF Hub & \\
+F000 - FEFF & Test Setups & \\
+FF00 - FFFF & Broadcasts &
+\end{tabularx}
+\caption{Network Addresses}
+\label{networkaddresses}
+\end{center}
+\end{table}
+
+
+\subsection{Replacement Boards}
+\label{ReplacementAddresses}
+If a TRB gets replaced, it is vital to keep track of these changes in analysis. Therefore, the replacement board gets a different address than the original board. These replacement addresses are always similar to the normal ones plus additional bits set. For this purpose, bits 8, 9 and 12 of the address are reserved. This results in 8 reserved replacement addresses for each board.
+
+\subsection{Broadcasts}
+\label{BroadcastAddresses}
+The address range above 0xFF00 is used for broadcasts. The address 0xFFFF is a global broadcast while other addresses are used for selective broadcasts based on a bitmask. Whenever one of the lower eight bits in the address is not set, only boards with this special bitmask will accept the network access. The list of bits is given in table \ref{broadcastbitmask}.
+
+If the bitmask configuration of an endpoint contains two unset bits it will answer to a transfer ignoring both unset bits which means it is accesible by two different selective broadcast addresses.
+
+\begin{table}[hb]
+\begin{center}
+\begin{tabular}{c|c|c}
+\textbf{Not set Bit} & \textbf{Broadcast Address} & \textbf{Board Type} \\
+- & FFFF & All boards \\
+0 & FFFE & Hubs\\
+1 & FFFD & MDC OEPB \\
+2 & FFFB & RICH ADCM \\
+3 & FFF7 & Shower \\
+4 & FFEF & TOF TRB \\
+5 & FFDF & RPC TRB \\
+6 & FFBF & \\
+7 & FF7F & Ethernet Bridges \\
+\end{tabular}
+\caption{Broadcast Addresses}
+\label{broadcastbitmask}
+\end{center}
+\end{table}
+
+
+\subsection{SubEventIDs}
+\label{subeventids}
+The subevent ids are assigned based on the trbnet addresses of the board forming the subevent. The range in which TRBs are located is restricted due to demands of the unpacking software.
+
+In summary, the only boards that send subevents are the Hubs, MDC Concentrators and Shower AddOns as well as the CTS. This sums up to 59 individual SubEvents.
+
+\begin{table}[hb]
+\begin{center}
+\begin{tabularx}{\textwidth}{l|l|l|X}
+\textbf{System} & \textbf{ID} & \textbf{Number} & \textbf{Description} \\
+CTS & 0000 - 00FF & 1 & \\
+MDC & 1000 - 17FF & 12 & second digit is inner(0) or outer(1) MDC, 3rd digit is the sector \\
+Shower & 3200 - 33FF & 6 & 3rd digit is the sector \\
+Start/Veto & 4000 - 43FF & 1 & \\
+Forw. Wall & 4400 - 47FF & 3 & last digit is the segment of FW \\
+RPC & 4800 - 4BFF & 24 & 3rd digit is the sector, last digit normal(0) or additional(1) TRB \\
+TOF & 4C00 - 4FFF & 9 & 3rd digit is normal(0) or additional(1) TRB, last digit is the sector \\
+RICH & 8300 - 83FF & 3 & last digit is the sector divided by 2 \\
+RPC *) & 8400 - 84FF & 2 & RPC readout via GbE \\
+TOF *) & 8600 - 86FF & 1 & TOF readout via GbE \\
+Wall/Start/Veto & 8000 - 80FF & 1 & Start / Veto / Forward Wall readout via GbE \\
+\end{tabularx}
+\caption{Reserved SubEvent IDs Ranges. The star marks possible future setups which are not implemented now but might come later. In that case, data from several TRB (only from one subsystem) will be merged into one SubEvent. The id of each TRB is still available inside the data stream.}
+\label{subeventidtable}
+\end{center}
+\end{table}
--- /dev/null
+The schematics of the RICH ADCM 3 can be found in \cite{ADCM}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{IPU Data Format}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Memory Map}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\ No newline at end of file
--- /dev/null
+The schematics of the Shower AddOn v2 can be found in \cite{Shower2}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{IPU Data Format}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+The data format generated by Shower is based on its physical structure: 32 columns times 32 rows times 3 planes. The ADCs deliver 10bit of data for each detector pad, which is compared against thresholds and only included in the data stream if it is above threshold. One FPGA serves for one half sector, one SubEvent contains data from one complete sector. Thus, there are 12 FPGAs with ADC and 6 SubEvents for the Shower detector.
+
+The different parts of data (pad address and ADC data) is packed into one 32 bit data word as shown in table \ref{showerdatanormal}. If a data word is viewed in raw hex format, the different parts can easily be recognized due to the nibble boundaries involved: $0xPRRCCDDD$ where D is data, C is column, R is row and P is plane. A structure for debug and status words is not yet set up.
+
+\begin{table}
+\begin{center}
+\begin{tabularx}{\textwidth}{c|C|C|C}
+\textbf{Bits} & \textbf{Phys. Trigger} & \textbf{Ped. Trigger} & \textbf{Calib. Trigger} \\
+9 - 0 & ADC Data & Pedestal value & ADC Data \\
+11 - 10 & \multicolumn{3}{c}{---} \\
+16 - 12 & \multicolumn{3}{c}{Column} \\
+19 - 17 & \multicolumn{3}{c}{---} \\
+24 - 20 & \multicolumn{3}{c}{Row} \\
+27 - 25 & \multicolumn{3}{c}{---} \\
+29 - 28 & \multicolumn{3}{c}{Plane (0: Pre, 1: P1, 2: P2)} \\
+30 & \multicolumn{3}{c}{---} \\
+31 & \multicolumn{3}{c}{0: normal data, 1: debug/status word} \\
+
+\end{tabularx}
+\caption{The shower data format (as seen in software and detector hardware)}
+\label{showerdatanormal}
+\end{center}
+\end{table}
+
+From the hardware point of view, the bits in the data word can be renamed to make their relationship to the hardware on the Shower AddOn board clearer. This is shown in table \ref{showerdatahardware}.
+
+For most pedestal triggers there is no ADC data sent to the Eventbuilders. Here, either an empty event or an event containing one or more status information words are sent. Only when the real pedestal value is calculated (e.g. after taking 64 pedestal values) these values are sent inside the event data. This is triggered by the CTS which also controls the time when the pedestal calculation is being done.
+
+\begin{table}
+\begin{center}
+\begin{tabularx}{\textwidth}{c|C|C|C}
+\textbf{Bits} & \textbf{Phys. Trigger} & \textbf{Ped. Trigger} & \textbf{Calib. Trigger} \\
+9 - 0 & ADC Data & Pedestal value & ADC Data \\
+11 - 10 & \multicolumn{3}{c}{---} \\
+16 - 12 & \multicolumn{3}{c}{Column} \\
+19 - 17 & \multicolumn{3}{c}{---} \\
+22 - 20 & \multicolumn{3}{c}{ADC Channel} \\
+23 & \multicolumn{3}{c}{ADC Number (counted per FPGA) divided by 3} \\
+24 & \multicolumn{3}{c}{FPGA number (hardcoded, also used for address assignment)} \\
+27 - 25 & \multicolumn{3}{c}{---} \\
+29 - 28 & \multicolumn{3}{c}{ADC Number modulo 3} \\
+30 & \multicolumn{3}{c}{---} \\
+31 & \multicolumn{3}{c}{0: normal data, 1: debug/status word} \\
+
+\end{tabularx}
+\caption{The shower data format as seen from a readout-hardware point of view}
+\label{showerdatahardware}
+\end{center}
+\end{table}
+
+The full data inside the Subevent will consist of several parts. Due to the structure of the readout system, there will be one SubEvent from each sector. According to table \ref{subeventidtable}, the SubEventIds are 0x8400, 0x8410 ... 0x8450. Inside the SubEvent, there will be data from up to four different sources. From each source there is a DHDR sent, followed by some data. The first two sources are the two FPGA on the Shower AddOn board, containing the physics data. The third source is the hub located in the third FPGA which can send some debugging information. The fourth and last source is the SubEventBuilder which will add one data word containing the status and error bits for the event.
+
+The addresses of each of the sources are also defined in table \ref{networkaddresses}. They are 0x32S1 and 0x32S2 (where S is the sector, numbered from 0 to 5) for the two FPGA equipped with ADC, 0x32S0 for the hub in the third FPGA and 0x5555 for the SubEventBuilder. The overall structure containing SubEventHeader, event information, DHDR and data is shown in table \ref{IPUData:SubEventBuilder}.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Memory Map}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{table}[hbtp]
+\begin{center}
+\begin{tabularx}{\textwidth}{l|l|X}
+\textbf{Address} & \textbf{Name} & \textbf{Description} \\
+A000 - ABFF & Thresh./Ped. Mem.& Memory for pedestal and threshold values, see table \ref{ShowerADCMemory} \\
+D000 & SPI Status Reg. & see section SPI Flash \\
+D001 & SPI Control Reg. & see section SPI Flash \\
+D100 - D13F & SPI Data Mem. & see section SPI Flash \\
+E000 & Spy Fifo & Fifo for debugging signals \\
+\end{tabularx}
+\caption{Memory map for FPGA 1 and 2 on Shower AddOn2}
+\label{ShowerADCFPGAMemoryMap}
+\end{center}
+\end{table}
+
+\begin{table}[htbp]
+\begin{center}
+\begin{tabularx}{\textwidth}{l|l|X}
+\textbf{Address Bit} & \textbf{Name} & \textbf{Description} \\
+4 - 0 & Column & Column of detector \\
+7 - 5 & Channel & ADC Channel \\
+8 & Ped/Thresh & 1: pedestals, 0: thresholds \\
+11 - 9 & ADC & ADC Number \\
+\end{tabularx}
+\caption{Memory map for ADC pedestals and thresholds on Shower AddOn2}
+\label{ShowerADCMemory}
+\end{center}
+\end{table}
+
+Data in memory for ADC pedestals is 16 bit wide and contains the current value of the pedestal adder, i.e. its value depends on the time when it is read relative to the number of pedestal triggers already sent. This memory is read-only from slow control and will be written by the automatic pedestal logic only.
+
+The threshold memory contains 10 bit data for each pad in the frontends. To be able to switch off / override automatic pedestal calculation, this memory is read/write from slow control and read/write from the internal logic. An arbiter controls the write access, i.e. writing from slow control is only possible while the LVL1 busy signal is low. According to the specification, the logic will respond with a ``no more data'' signal on slow control, while LVL1 busy is high.
+
--- /dev/null
+The slowcontrol endpoint (``RegIO'') allows to read and write data from and to the endpoints. For this purpose it uses 16 bit wide addresses and 32 bit wide data words along with read/write strobe signals for all operations.
+
+Internally it also has logic to readout the 1-wire temperature logic and to assign network addresses. Other features include a global timer and configurable easy-to-use status and control registers. Additional, more complex logic can be connected to an internal data bus.
+
+
+
+
+\subsection{User Interface}
+The ports on the user interface can be divided into several sets:
+\paragraph{Registers}
+There are four types of registers provided by RegIO: Common registers that are defined for all boards in the same way and user specific resgisters. These two sets are further divided into status registers that can be written by the internal logic and control registers that can be written over the network. The registers have a size of 32 bits each. The number of user registers in each of the four groups can be set using generics (see \ref{regiogenerics}).
+
+For each register there is a strobe signal that shows read access (in case of status register) or write access (in case of control registers) from the network side. The following listing shows the name of all ports:
+
+\lstset { caption ={Register Ports on RegIO}}
+\begin{lstlisting}
+Regio_Common_Stat_Reg_In (std_comstatreg*32-1 downto 0)
+Regio_Common_Ctrl_Reg_Out (std_comctrlreg*32-1 downto 0)
+Regio_Registers_In (32*2**(num_stat_regs)-1 downto 0)
+Regio_Registers_Out (32*2**(num_ctrl_regs)-1 downto 0)
+
+Common_Stat_Reg_Strobe(std_comstatreg-1 downto 0)
+Common_Ctrl_Reg_Strobe(std_comctrlreg-1 downto 0)
+Stat_Reg_Strobe(2**(num_stat_regs)-1 downto 0)
+Ctrl_Reg_Strobe(2**(num_ctrl_regs)-1 downto 0)
+\end{lstlisting}
+
+
+\paragraph{Onewire}
+The temperature sensor on each board is connected to the following ports. In case no temperature sensor is connected directly, the generic setting \genericname{Regio\_Use\_1wire\_Interface} has to be set accordingly.
+
+\begin{description}
+ \item[Regio\_Onewire\_Inout] Direct connection to a 1-wire temperature sensor
+ \item[Regio\_Onewire\_Monitor\_Out] Outputs a copy of the signals on the 1-wire bus. Used to transport information to another FPGA.
+ \item[Regio\_Onewire\_Monitor\_In] The corresponding input to monitor traffic on a 1-wire bus if no sensor is connected directly to the fpga.
+\end{description}
+
+
+
+\paragraph{Timers}
+\begin{description}
+ \item[\portname{Global\_Time\_Out}] The global time measured in microseconds. This time will be synchronized on all boards from time to time to keep descrepancies between the boards low. E.g. used for marking debugging and status information.
+ \item[\portname{Local\_Time\_Out}] The local time is used to measure in the sub-microsecond range. It counts with the internal clock frequency (standard: 100 MHz) and is reset each microsecond.
+ \item[\portname{Time\_Since\_Last\_Trg\_Out}] The time since the last timing trigger has been received, measured in clock cycles.
+ \item[\portname{Timer\_Us\_Tick\_Out}] A tickmark that is set every microsecond for one clock cycle. Can be used to clock internal slow running logic.
+ \item[\portname{Timer\_Ms\_Tick\_Out}] A tickmark that is set every 1024 us for one clock cycle. Can be used to clock internal slow running logic.
+\end{description}
+
+
+
+\paragraph{Internal Data Bus}
+An access cycle on the internal data bus consists of two actions: First, RegIO sends a read or a write strobe. At the same time \portname{address} and \portname{data\_out} are valid. Afterwards it waits up to 32 clock cycles for a reaction of the connected logic. This can be either of \portname{dataready}, \portname{no\_more\_data}, \portname{write\_ack} or \portname{unknown\_addr} as described below. If the logic fails to answer, an automatic timeout is generated.
+
+\begin{description}
+ \item[\portname{Regio\_Addr\_Out}] (16 bit) address port. Address is valid when either of \portname{read\_enable} and \portname{write\_enable} is high.
+ \item[\portname{Regio\_Read\_Enable\_Out}] Read enable strobe.
+ \item[\portname{Regio\_Write\_Enable\_Out}] Write enable strobe.
+ \item[\portname{Regio\_Data\_Out}] (32 bit) Data output of regIO, input to the user. Valid when \portname{write\_enable} is high.
+ \item[\portname{Regio\_Data\_In}] (32 bit) Data input to regIO, output from the user. Valid when \portname{dataready\_in} is high.
+ \item[\portname{Regio\_Dataready\_In}] User signal to show that \portname{data\_in} is valid. May only be used after a strobe on \portname{read\_enable}.
+ \item[\portname{Regio\_No\_More\_Data\_In}] User signal. After a read strobe: User has no more data to read from this address. After a write strobe: User is not able to handle more data on this address now.
+ \item[\portname{Regio\_Write\_Ack\_In}] User signal. Acknowledge after a strobe on \portname{write\_enable} and writing was successful.
+ \item[\portname{Regio\_Unknown\_Addr\_In}] User signal. After either read or write strobe: The given address is not in use.
+ \item[\portname{Regio\_Timeout\_Out}] About 24 to 32 clock cycles after a read or write strobe RegIO terminates the access assuming the user logic does not react.
+ \end{description}
+
+\paragraph{Generic Settings}
+\label{regiogenerics}
+\begin{description}
+ \item[\portname{Regio\_Num\_Stat\_Regs}] The number of status registers (addr. 0x80 ff). This value is log2 of the desired number of 32bit registers
+ \item[\portname{Regio\_Num\_Ctrl\_Regs}] The number of control registers (addr. 0xc0 ff). This value is log2 of the desired number of 32bit registers
+ \item[\portname{Regio\_Init\_Ctrl\_Regs}] The initial value of all control registers. This generic has a fixed size of 8x32 bits
+ \item[\portname{Regio\_Use\_Dat\_Port}] Selects to have an internal data port to connect own registers to in the address space above 0x0100
+ \item[\portname{Regio\_Use\_1wire\_Interface}] Set to \constname{c\_Yes} means a temperature sensor is connected, \constname{c\_\-Mon\-itor} means there is a 1-wire data stream sent by another FPGA, \constname{c\_No} means temperature and unique id are written using some user supplied logic.
+\end{description}
+
+
+\subsection{RegIo Bus Handler}
+If you want to connect several registers or function blocks to the internal data bus, you can use the RegIO Bus Handler. This special entity (\filename{trb\_net16\_regio\_bus\_handler}) simplifies to generate several address sub-spaces on the internal data bus. It is configured using three generic values as shown in this listing:
+
+\lstset { caption ={Configuration of RegIO Bus Handler}}
+\begin{lstlisting}
+The_Regio_Bus_Handler : trb_net16_regio_bus_handler
+ generic map(
+ Port_Number => 2,
+ Port_Addresses => (0=>x"A000", 1=>x"8000", others=>x"0000"),
+ Port_Addr_Mask => (0=>8, 1=>6, others=>0)
+ )
+\end{lstlisting}
+
+This setting introduces two address spaces: One starting at 0xA000 with a size of 2**8 addresses, i.e. from 0xA000 to 0xA0FF, and one starting at 0x8000 with 2**6 addresses, i.e. from 0x8000 to 0x803F.
+
+The behaviour on the data busses is identical to the original RegIO interface. Connecting to the different address spaces can be done in a convenient form as shown in the following piece of code:
+
+\lstset { caption ={Excerpt from the regio\_bus\_handler used in MDC OEP.}}
+\begin{lstlisting}
+ THE_REGIO_BUS_HANDLER : trb_net16_regio_bus_handler
+ generic map(
+ PORT_NUMBER => 6,
+ PORT_ADDRESSES =>
+ (0 => x"A000", 1 => x"8000", others => x"0000"),
+ PORT_ADDR_MASK =>
+ (0 => 8, 1 => 6, others => 0)
+ )
+ port map(
+ clk => clk_100,
+ reset => reset_internal,
+ --I/O to RegIO
+ dat_addr_in => regio_addr_out,
+ dat_data_in => regio_data_out,
+ dat_data_out => regio_data_in,
+ dat_read_enable_in => regio_read_enable_out,
+ dat_write_enable_in => regio_write_enable_out,
+ dat_timeout_in => regio_timeout_out,
+ dat_dataready_out => regio_dataready_in,
+ dat_write_ack_out => regio_write_ack_in,
+ dat_no_more_data_out => regio_no_more_data_in,
+ dat_unknown_addr_out => regio_unknown_addr_in,
+ --Bus Handler (Threshold memory)
+ bus_read_enable_out(0) => thresh_mem_read,
+ bus_write_enable_out(0) => thresh_mem_write,
+ bus_data_out(0*32+15 downto 0*32) => thresh_mem_data,
+ bus_data_out(0*32+31 downto 0*32+16)=> open,
+ bus_addr_out(0*16+8 downto 0*16) => thresh_mem_addr,
+ bus_addr_out(0*16+15 downto 0*16+9) => open,
+ bus_timeout_out(0) => open,
+ bus_data_in(0*32+15 downto 0*32) => thresh_mem_data_out,
+ bus_data_in(0*32+31 downto 0*32+16) => x"0000",
+ bus_dataready_in(0) => last_reg_regio_read,
+ bus_write_ack_in(0) => reg_regio_write,
+ bus_no_more_data_in(0) => '0',
+ bus_unknown_addr_in(0) => '0',
+ --Bus Handler (ADC)
+ bus_read_enable_out(1) => adc_read,
+ bus_write_enable_out(1) => adc_write,
+ bus_data_out(1*32+31 downto 1*32) => adc_data_in,
+ bus_addr_out(1*16+5 downto 1*16) => adc_addr,
+ bus_addr_out(1*16+15 downto 1*16+6) => open,
+ bus_timeout_out(1) => adc_timeout,
+ bus_data_in(1*32+31 downto 1*32) => adc_data_out,
+ bus_dataready_in(1) => adc_dataready,
+ bus_write_ack_in(1) => adc_write_ack,
+ bus_no_more_data_in(1) => adc_no_more_data,
+ bus_unknown_addr_in(1) => adc_unknown_addr,
+ [...]
+\end{lstlisting}
+
+
+
+
+
+
+\subsection{Register Map}
+Table \ref{regioaddressmap} shows a list of most defined registers within the slow control endpoint. The common status and control registers are further explained in the next section.
+
+\begin{table}[htbp]
+\begin{center}
+\begin{tabularx}{\textwidth}{c|c|C}
+\textbf{Address} & \textbf{Name} & \textbf{Description} \\
+\hline
+00 & common status register 0 & Basic Error Flags and Temperature (see below) (r) \\
+01 & common status register 1 & LVL1 trigger number (Bits 15..0), timing Trigger number (Bits 31..16) (r) \\
+20 & common control register 0 & Strobes for board resets and test triggers (see below) (w)\\
+21 & common control register 1 & Sets LVL1 trigger number (Bits 15..0) (r/w)\\
+40 & information ROM 0 & Compile Time (set by generic) (r)\\
+41 & information ROM 1 & Design Version (set by generic) (r) \\
+42 & information ROM 2 & Hardware Information (set by generic) (r)\\
+50 & global time & Global Time (r/w)\\
+51 & time since trigger & Time since last timing trigger (r)\\
+80 - BF & user status registers & User status registers \\
+C0 - FF & user control registers & User control registers \\
+0100 - 7FFF & reserved & Reserved addresses on internal data port (e.g. for monitoring and other features)\\
+8000 - FFFF & user defined & User defined address space on the internal data bus \\
+\end{tabularx}
+\caption{Register Map of the Slow Control Endpoint.}
+\label{regioaddressmap}
+\end{center}
+\end{table}
+
+\begin{table}[htbp]
+\begin{center}
+\begin{tabularx}{\textwidth}{c|c|C}
+\textbf{Address} & \textbf{Name} & \textbf{Description} \\
+\hline
+A000 - CFFF & FEE & Thresholds, Pedestals, Frontend settings \\
+D000 - D13F & Flash & Control for SPI Flashes \\
+E000 - FFFF & Debugging & Memories and Registers for Debugging \\
+\end{tabularx}
+\caption{Register Map of the Slow Control Endpoint. Suggested usage of the user defined registers.}
+\label{regioaddressmapsuggested}
+\end{center}
+\end{table}
+
+
+\paragraph{Common Control and Status Registers}
+
+The first common status register is described in table \ref{CommonStatReg0}. It is used for error flags and readback of the boards temperature. The second status register is used to read the LVL1 trigger number of the last timing trigger (Bits 15 - 0) and the number of the event last read on the IPU channel (Bits 31 - 16).
+
+
+The first common control register consists of strobe signals for dummy timing triggers and reset signals as shown in table \ref{CommonCtrlReg0}. The second common control register is used to set the current LVL1 trigger number (Bits 15 - 0) and the number of received timing triggers (Bits 31-16).
+
+\begin{table}
+\begin{center}
+\begin{tabular}{c|c}
+\textbf{Bits} & \textbf{Description} \\
+\hline
+0 & serious error flag \\
+1 & error flag \\
+2 & warning flag \\
+3 & note flag\\
+4 & LVL1 trigger counter mismatch \\
+5 & IPU channel counter mismatch \\
+20 - 31 & temperature \\
+\end{tabular}
+\caption{Common Status Register 0}
+\label{CommonStatReg0}
+\end{center}
+\end{table}
+
+\begin{table}
+\begin{center}
+\begin{tabular}{c|c}
+\textbf{Bits} & \textbf{Description} \\
+\hline
+0 & reset frontends \\
+1 & reset trigger logic \\
+2 & empty IPU chain / reset IPU logic \\
+3 & master reset \\
+10 & reset sequence counter \\
+15 & reboot FPGA \\
+16 - 23 & dummy timing triggers \\
+24 - 31 & user defined \\
+\end{tabular}
+\caption{Common Control Register 0}
+\label{CommonCtrlReg0}
+\end{center}
+\end{table}
--- /dev/null
+\section{Overview}
+Currently, there are three main software tools for accessing TrbNet: trbcmd, trbflash and daqop. All are based on one common library, libtrbnet, that provides all features needed to communicate with any FPGA inside the network using the ETRAX CPU located on a central slow control TRB.
+
+\begin{description}
+ \item[trbcmd] A general purpose tool to execute every possible access on TrbNet endpoints. Scripting capabilities and verbose error messages are included.
+ \item[daqop] A command line tool which accepts keywords as options and executes the corresponding TrbNet accesses without having the user to bother with network and register addresses.
+ \item[trbflash] A specialized tool to write, read and verify Flash ROMs used to boot FPGAs. Currently, MDC OEP and RICH ADCM are supported, Shower AddOn and MDC AddOn will follow.
+ \item[readout\_mdc] Simulates the CTS using a TRB by sending first a pseudo timing trigger via slow control, then a LVL1 trigger and finally an IPU readout request. Data is sent via UDP to an Eventbuilder. Primarily written for MDC, but should be compatible to other detectors as well.
+ \item[startup.pl] Executes script files to load many registers during startup or for reconfiguration.
+ \end{description}
+
+
+\section{DaqOp}
+\begin{itemize}
+ \item Commands use standard notation like (a|b|c) for choices, (a)? for optional parts and \$ab for placeholders.
+ \item Most output is ordered by the network address
+ \item If no address is given, command is sent to all boards using a broadcast (Unless specified otherwise)
+ \item The order of keywords and values in the command is arbitrary. Only in few places the order is relevant. \verb|$channel| and \verb|$port| must always directly follow their corresponding keyword.
+ \item Some commands can be modified by one of the keywords \verb|dec|, \verb|decimal|, \verb|hex| or \verb|raw|. \verb|hex| forces the output in hexadecimal form, \verb|dec| in decimal form and \verb|raw| gives the raw content of the addressed registers.
+\end{itemize}
+
+Placeholders are defined as follows:
+\begin{description}
+ \item[\$addr] TrbNet address, 16bit long, preceded by \verb|ax| prefix in the form, example: \verb|ax1234| or system name (\$system)
+ \item[\$channel] A value identifying a TrbNet channel. Usually either 0,1 or 3.
+ \item[\$read] A keyword, one of \verb|read| and \verb|get|
+ \item[\$port] A value identifying one port of a hub. Usually a number between 0 and 12.
+ \item[\$select] A keyword, one of \verb|select|, \verb|set| and \verb|switch|
+ \item[\$string] Any string of characters
+ \item[\$system] A keyword identifying a subsystem: \verb|hub|, \verb|oep|, \verb|rich|, \verb|tof|, \verb|shower|, \verb|rpc| or an \$addr
+ \item[\$value] An integer value, either hexadecimal (\verb|0x1234|), a bit position (\verb|0b5|, the sixth bit in the register) or a decimal value)
+ \item[\$write] A keyword, one of \verb|send|, \verb|set| and \verb|write|
+\end{description}
+
+\subsection{Network Management}
+\paragraph*{reset network \\ \$write hub port \$port reset \$addr} ~\\
+Sends a network reset through the network. Either all boards or all boards connected below the given board respectively the given port will receive the reset. Note that the first works in all cases, but the latter two require a still working slow control channel. The reset phase is dominated by the delay in the optical link state machines which are around 5 seconds.
+
+\paragraph*{\$read ids} optional: \verb|$addr| \\
+Reads the unique ids of boards with the given address. The first value returned is the network address, the second the 64bit wide unique id, the last the FPGA number.\\
+Example output: \verb|0xf102 0x120000011234234 0x02|
+
+\paragraph*{reboot \$system} optional: \verb|$addr| \\
+Triggers a reboot of the addressed FPGA. Only available on systems with on-board Flash ROM such as OEP, MDC, RICH and Shower.
+
+
+\subsection{Basic Information}
+\paragraph*{\$read compile time} optional: \verb|$addr|, \verb|raw| \\
+Reads the timestamp the currently loaded FPGA design has been compiled. The \verb|raw| modifier gives back the unix timestamp, standard is a decimal representation. \\
+Example output: \verb|0xf102 2010-01-01 10:32|
+
+\paragraph*{\$read temp \\ \$read temperature} optional: \verb|$addr|, \verb|raw| \\
+Reads the temperature of the addressed boards. Output is in degrees Celsius (standard) or in raw hexadecimal format.
+
+\subsection{Trigger}
+\paragraph*{\$read global time \\ \$write global time \$value} optional: \verb|$addr|, \verb|dec|, \verb|raw| \\
+Reads or writes the global time register on the addressed boards. The \verb|dec| option gives back a decimal representation in seconds, raw is a hexadecimal representation of microseconds since the timer has been started. An overflow will occur every 72 minutes.
+
+\paragraph*{\$read trigger time} optional: \verb|$addr|, \verb|dec|, \verb|raw| \\
+Equivalent to \verb|$read compile time| but gives back the time since the last timing trigger has been received, counting in 10ns steps. An overflow will occur within less than a minute.
+
+\paragraph*{\$read trigger number \\ \$write trigger number \$value} optional: \verb|$addr|, \verb|dec| \\
+Reads or writes the internal trigger number counter on the addressed endpoints. Output can be either hexadecimal (standard) or decimal.
+
+\paragraph*{\$write timing trigger \$value} optional: \verb|$addr| \\
+Sends a fake timing trigger using the slow control channel and the upper 16bit of control register 0 in all endpoints. \verb|$value| is the type of timing trigger in the range 0 to 15.
+
+
+
+
+\subsection{MDC}
+
+\paragraph*{\$read flash oep } optional: \verb|$addr| \\
+Reads back the current status of the Flash select switch on the OEP. Value is either 1 for flash 0, 2 for flash 1 or 3 in case of an error.
+
+\paragraph*{\$select flash (0|1) oep} optional: \verb|$addr| \\
+Selects either Flash chip 0 or 1 on the OEP. 0 is the ``golden image'', 1 is the working setup.
+
+\paragraph*{adc oep (init|on|off|single)} optional: \verb|$addr| \\
+Sets the operation mode of the voltage monitoring ADC on the OEP. \\
+\verb|init| Initializes the ADC, switches it on and starts continous conversions.\\
+\verb|on| Switches the ADC on and starts continous conversions.\\
+\verb|off| Stops ADC measurements.\\
+\verb|single| Runs a single conversion for all 8 monitored voltages, then switches off the ADC.\\
+
+\paragraph*{\$read oep voltages (long)?} optional: \verb|$addr|, \verb|raw| \\
+Reads the voltages of the addressed OEP. Standard output is a human-readable status information. For each voltages, the status is shown as one of ``ERR'' (measurement error), ``ok'', ``low'', ``was low'' (voltage was too low, but is ok now), ``high'', ``was high'' (voltage was too high, but is ok now), ``high/low'' (voltage was too low and too high before, currently either too high or too low) or ``vary/ok'' (voltage is ok now, but was too high and too low before). The \verb|raw| option gives back the raw content of the register, i.e. a list of 8 hexadecimal numbers for each board.
+The long format gives back the exact voltage levels measured.
+
+\paragraph*{\$read oep voltage \$value} optional: \verb|$addr|, \verb|raw| \\
+Reads the value of a single voltage on the addressed OEP. Additionally, the lowest and highest measured value is shown. \verb|$value| is the voltage to be shown, in the range of 0 to 7 according to the following list (voltages are either on the measured on the input of the OEP (input) or after the voltage regulator (output): (0: 5.6V input, 1: 5V output, 2: 3.5V input, 3: 3.3V output, 4: 1.6V input, 5: 1.2V output, 6: +3V input, 7: -3V input).
+
+
+\subsection{Network Hubs}
+
+\paragraph*{\$read hub setup} optional: \verb|$addr|, \verb|raw| \\
+Reads the uplink-/downlink-configuration of the addresses network hubs. The output is two strings for either up- and downlinks. Each digit marks a connection where that is configured as uplink respectively downlink or a dash if this functionality is disabled. Ports that are listed in neither list do not exist at all. The numbers themselves are inserted to gain a better readability and represent the port number only.\\
+Example output: \verb|0xf123 up: --------------10 down: -----a9876--3210|
+
+\paragraph*{\$read hub connected} optional: \verb|$addr|, \verb|raw| \\
+Reads the current status of the hub, which ports are actually connected and have a link established. The output format is similar to the one described above. A dash marks an existing port without a connection, a number marks an established link.
+
+\paragraph*{\$read hub timeout} optional: \verb|$addr|, \verb|raw| \\
+Gives back information about hub ports on which a timeout occured. Standard output is plain text: \\
+Example output: \verb|Timeout on hub f123 channel 0 port 7| \\
+The raw option gives the same information but as one 32bit value per channel and board with one bit set for each port with a timeout.
+
+\paragraph*{\$read hub packets} optional: \verb|$addr|, \verb|raw|, \verb|port $port| \\
+Reads the amount of packets received on IPU and slow control channel on the given hub and port or for all ports if now port number is given. The raw option outputs one 32bit number, lower 16bit are the packet counter on IPU, upper 16 bit are the packet counter on the slow control channel.
+
+\paragraph*{\$read hub waiting (channel \$channel)?} optional: \verb|$addr|, \verb|raw| \\
+Shows all ports and channels on the addressed hubs that are currently waiting for a reply (more precisely: waiting for a TRM in the reply channel). Although channel can be chosen freely, the value read on channel 3 is accurate, but all connected channels will always be marked as waiting. This is the case since there actually is a transfer going on - namely this request itself. If no channel is selected, information from all channels 0 and 1 is shown. The output is either in plain text (standard) or in raw format.
+
+\paragraph*{\$read hub ack channel \$channel \\ \$read hub acknowledge channel \$channel} optional: \verb|$addr|, \verb|raw| \\
+Shows all ports and channels on the addressed hub that are blocked because the sender is waiting for two acknowledge (ACK) packets from the receiver side for too long. This kind of error usually corresponds to a broken communication, e.g. mixed up TX and RX lines. If no channel is selected, information from all 3 channels is shown. The output is either in plain text (standard) or in raw format.
+
+\paragraph*{switch hub port \$port (channel \$channel)? \$addr (on|off)} ~\\
+This command is used to switch a specific port on a specific channel on a specific hub on or off. Switching one channel of a port off means, that no request is sent on this port any more and no data is accepted on this port. This command must be issued including all three pieces of information (namely port, channel and address), otherwise it will return an error ``Parsing input failed.'' for security reasons. Please be adviced that it is no good idea to switch off the uplink of any hub! If this happens, a network reset is inevitable.
+If \verb|channel $channel| is not specified, the whole port will be powered down. Currently, this feature is not correctly implemented.
+
+\paragraph*{\$read hub error(bits)? \\ \$read hub error(bits)? channel \$channel} optional: \verb|$addr| \\
+Reads the merged status- and errorbits from the last transfer from the addressed hub. If no channel is specified, all channels are read out. The output is one 32bit data word according to the corresponding status- and errorbit definitions.
+
+\paragraph*{\$read hub error(bits)? ports \\ \$read hub error(bits)? port \$port} optional: \verb|$addr|, \verb|raw| \\
+Reads some error- and statusbits from all ports or the selected port from the addressed hub. Included are parts of the errorbits from LVL1 and IPU channel. For each channel, Bits 0-7 and 16-23 are included while the rest is omitted to reduce ressource consumption. The standard output shows the bits in the right positions while the raw output shows the bits merged into one value.
+
+\paragraph*{\$read hub ipu stat(us|e)} optional: \verb|$addr|, \verb|raw| \\
+Reads the current status of the IPU state machine from the addresses hubs. The standard output gives a description of the current state, the part of TrbNet packet that will be sent next and the part of the HDR/DHDR that is currently analyzed.
+
+\paragraph*{\$read hub ctrl error} optional: \verb|$addr|, \verb|raw| \\
+Reads the error log for the slow control on hubs. One bit for each port. 1 if there was a transfer with either error bit 1, 3 or 6 set, 0 otherwise. Cleared after each read.
+
+\paragraph*{\$read hub time limit \\ \$write hub time limit \$value } optional: \verb|$addr|, \verb|raw| \\
+Reads or writes the setting for timeouts on hub ports. For details see the entry for register 0xC5 in \ref{hubcontrolregs}.
+
+\subsection{Other features}
+\paragraph*{trbcmd \$string \\ trbflash \$string} ~\\
+These two commands execute trbcmd or trbflash with the given string of attributes.
+
+\paragraph*{watch \$float} ~\\
+The watch option can be added to any command (depsite trbcmd and trbflash) to execute the given command in an endless loop. The \verb|$float| value gives the period in seconds.
\ No newline at end of file
jspc29 / daqdocu.git / commitdiff
