\chapter{Software and diagnostics}
\label{softw}
%  svn Id  : $Id$

This chapter covers the software for i2c and j2c access to the ORI board. The JTAG interface and software are fully
described in chapter \ref{jtag}.

%-----------------------------------------------------------------------------
\section{Overview}
\label{softw:ov}

Due to limitations, the interface to the ORI is made via general purpose I/O pins of the TRAP chip (SEBD0..2).
The interface lines are in two groups:

\begin{enumerate}
\item RESET\_n and DIS\_JTG
\item TCK, TMS, TDI/TDO
\end{enumerate}

Please see fig. \ref{fig:block_jt_j2c}. For redundancy, each group of signals is connected to two TRAP chips.
During the reset phase of the TRAP, the SEBD pins of the TRAP act as reset outputs.
After reset, the SEBD pins are tri-stated with weak pull-ups. One of the TRAPs in each group should be left with
tri-stated SEBD pins. In the software the active MCMs in each group are labeled as \verb+chip_mode+ and
\verb+chip_jtag+.

The first group is always directly controlled by the DCS through scsn. In order to use any of the interfaces, first the
RESET\_n should be deactivated. For the j2c interface the DIS\_JTG signal should be 0, for i2c interface should be set to 1.

The second group of signals is controlled either by a TRAP CPU program or by the DCS board through scsn.

\begin{itemize}

\item
In the first case a TRAP CPU program gets a request from the DCS board for read/write at some address. The CPU
performs the transaction and stores the result, which is then read by the DCS board.

\item
In the second case the DCS board controls directly the SEBD pins via the scsn bus. Note that in order to send or
receive one bit serially, at least 3 scsn packets must be send: two for the clock and one for the data. The best
feature of this method is that it works independently from the TRAP CPUs.
\end{itemize}

The benefit when using the CPUs is the speed. Due to an undocumented limitation in the LTC chip, its i2c interface
expects some minimal frequency of
the i2c clock (SCL) signal of about 10 kHz. When implementing the i2c interface as TRAP CPU program this is not a
problem, while when trying to control the SEBD pins directly by the DCS board via the scsn bus, this speed is hardly to
achieve. {\bf Therefore the i2c access to the LTC chip should be done only using the TRAP CPUs}, the access to the EEPROM
and to the j2c bus(CPLD) can be done with both methods.

\section{TRAP}
\label{softw:trap}

The DCS software can request i2c or j2c access to ORI using the TRAP CPUs by writing the command and the input data to special addresses in TRAP, then starts the CPU using the test interrupt and reads back the status and the output data. The current definition of the addresses is:

\begin{verbatim}

srv_command  0xF0E0 // for the command
srv_indata   0xF0E1 // for the input data (write command)
srv_outdata  0xF0F0 // for the output data (read command)

\end{verbatim}



\section{DCS}
\label{softw:dcs}

\section{Configuration procedure}
\label{softw:cnf}

The first step is to determine the physical currents $I_{BIAS}$ and $I_{MOD}$.


\begin{enumerate}
\item Set the modulation current $I_{MOD}$ to zero
\item Clear the flag \reg{FLT\_CONFIG}\verb+.Over_current_en+ to avoid FAULT conditions
\item With step of 0.1~mA increase the bias current from 0 to about 5~mA and read back from the LTC chip the
actual bias current $I_{BIAS}$, the monitor diode current $I_{MD}$ (here the range \verb+T_NOM.Imd_rng+
should be properly selected - see table \ref{tab:ltc_Imd_rng}) and the voltage on the laser diode $V_{LD}$
(The expected curves are shown on fig. \ref{fig:laser_d_par})
\item Determine the $R_{DYN}$, $I_{THRES}$ and $\Delta I_{MD}/\Delta I_{BIAS}$
\item Using eq (\ref{i2c:ltc-conf:ltc_rdyn}) calculate the attenuation of the modulation current due to the current
divider shown in the inset of fig. \ref{fig:laser_d_par}
\item Using the proportionality between the optical power and the monitor current, calculate the monitor
current for the desired optical power
\item Using the already known $I_{THRES}$ and $\Delta I_{MD}/\Delta I_{BIAS}$, calculate the $I_{BIAS}$ for the desired monitor
current
\item Select the (max) modulation current at the laser diode as the difference between the $I_{BIAS}$ and $I_{THRES}$
\item Increase the modulation current to compensate for the attenuation calculated in (5)
\end{enumerate}

\begin{figure}[htb]
 \centering
 \includegraphics*[width=12cm]{chap_softw/ori_rdyn_ithr.eps}
 \caption[Determining the basic parameters of the laser diode]{Determining the basic parameters of the laser diode}
 \label{fig:laser_d_par}
\end{figure}

The laser diode in ORI is specified for bias currents up to 12~mA. The typical threshold current $I_{THRES}$
is about 0.8~mA, the bias current $I_{BIAS}$ for 200~$\mu$W is about 2-3~mA.
The typical $R_{DYN}$ is about 70-90~$\Omega$.

The next step is to convert the physical currents to integer settings for the LTC configuration registers.

\begin{enumerate}
\item Select the source current range \verb+Is_rng+ (0..3) using the sum of the $I_{BIAS}$ and $I_{MOD}$ and
taking into account, that the guaranteed current per range is not 9 but 8~mA
\item Calculate the \verb+Ib_nom+ setting (10 bit unsigned integer) using eq (\ref{i2c:ltc-conf:ltc_ib})
\item Combine the two integers in one word \reg{IB} as \verb+(Isrc_rng << 10) | Ib_nom+
\item Calculate \reg{IB\_LIMIT} from eq (\ref{i2c:ltc-conf:ib_limit}), as physical limit we use 8~mA
\item Select the average modulation current range \verb+Im_rang+ (0..3) taking into account, that the guaranteed current per
range is not 4.5 bit 3~mA
\item Calculate the modulation current setting \verb+Imod_nom+ (10 bit unsigned integer) using eq
(\ref{i2c:ltc-conf:ltc_im})
\item Combine the two integers in one word \reg{IM} as \verb+(Im_rng << 10) | Im_nom+
\item Select the proper range for the monitor current from table \ref{tab:ltc_Imd_rng} and put it in

\reg{T\_NOM}\verb+.Imd_rng+
\end{enumerate}

Now the complete configuration in CCC mode is ready. The temperature compensation coefficients
\reg{IB\_TC1}, \reg{IB\_TC2}, \reg{IM\_TC1}, \reg{IM\_TC2} can be set first all to 0. The values of the rest are
constants and were already given in chapter \ref{i2c:ltc-conf}.

\section{Diagnostics and test}
\label{softw:tst}

\subsection{Checklist - Optical power}
\label{softw:tst:opt}

Provided the interface to the LTC chip and to the EEPROM is working, the simplest diagnostics consists of reading the
EEPROM, LTC configuration, ADCs, DACs and status registers. Then the possible checks are the following:

\begin{enumerate}
\item Compare the configuration in the EEPROM and in the LTC chip using the table \ref{tab:eep-ltc}
\item Check the constants in the configuration: \reg{SYS\_CONFIG}=\verb+0x96+,
\reg{FLT\_CONFIG}=\verb+0x2C7+,
\reg{LOOP\_GAIN}=\verb+0x21+ and \reg{PEAKING}=\verb+0x10+
\item Check the status register \reg{FLT\_STATUS}, the only 3 bits expected to be 1 are 10..8 (see table 
\ref{tab:ltc-flt-status})
\item If some other bits in \reg{FLT\_STATUS} are set, try to read the status again, some flags will be cleared after
read and if they don't appear again, then there was no real problem
\item Read the FAULT pin of the LTC chip (the MSBit in \reg{N16W.H}, \reg{NBWPF}, \reg{NBWPR} - whatever was read as last), it
should be 1 (active low), 0 means the LTC chip is in FAULT state
\item Check the monitor current, the expected values are 40-200 $\mu$W (Be careful, if the
current is equal to the lower limit of the range \reg{T\_NOM}\verb+.Imd_rng+ in \ref{tab:ltc_Imd_rng},
then switch the range and measure again), see fig. \ref{fig:laser_d_par}

\item The optical power can be estimated from the monitor current as

  optical power [$\mu$W] $\approx$ 2.5 $\cdot$ modulation current [$\mu$A]

\item Check if the measured bias current eq~(\ref{i2c:ltc-conf:ibias_meas}) corresponds to the bias
current set in \reg{IB} eq~(\ref{i2c:ltc-conf:ltc_ib}), the deviations should be less than 50~$\mu$A
\item The optical power can be estimated from the bias current as

  optical power [$\mu$W] $\approx$ 135$\cdot$(bias current [mA] - 0.77)
  
\item Check if the measured source current corresponds to the \reg{IS\_DAC}
\item Check if the measured modulation current corresponds to the \reg{IM\_DAC}/2
\item Check the voltage drop on the laser diode, the expected values are 1.6 - 2.0~V,
see fig. \ref{fig:laser_d_par}
\item Check if the $R_{TERM}$ given by eq (\ref{i2c:ltc-conf:rterm}) is about 50~$\Omega$
\end{enumerate}

\subsection{Test of the data interface to the half-chamber merger}
\label{softw:tst:ori-hcm}

In order to test the data interface to the ORI (HCM - CPLD on fig. \ref{fig:block_ori}), independently on the optical transmission, send data packets of
known size and check the counters in ORI. On the chamber this can be done by configuring the TRAPs to send
uncompressed data without tracklets. The number of 16-bit data words sent in one event can be easily calculated.
Here an example for 30 samples, chamber with 4 readout boards. 
The data of one ADC channel are sent in 10 double words (3 samples in a dword).
Each MCM except for the board merger and the
half-chamber merger send 1 MCM header and 210 dwords with ADC data.
The half-chamber merger sends at least one header h[0] and some more \verb+(h[0] >> 14) & 7+.
The endmarkers for tracklet and raw data are sent twice, resulting in 4 dwords in total.
The expected number of dwords is:

\verb/   2 + (1 + (h[0] >> 14) & 7) + 64*(1 + 210) + 2/

Don't forget to multiply by 2 to get the number of 16-bit words, as the ORI counts 16-bit words.

\begin{enumerate}
\item First clear the counters by writing to some odd address via the j2c interface
\item Send one pretrigger to trigger one event
\item Read the 3 counters \reg{N16W}, \reg{NBWPF}, \reg{NBWPR} and mask the FAULT bit there
\item The two parity error counters \reg{NBWPF} and \reg{NBWPR} should be 0, this means no parity errors
\item The \reg{N16W} counter should correspond to the expected event size
\item Run many events and read the counters again, the two error counters should remain 0, the \reg{N16W} counter
should be equal to

\verb+(expected number of 16-bit words) mod 0x8000+

as the counter is 15-bit and wraps

\item Program some wrong values in the \reg{SPAPAR} register and repeat the test -
in this case the parity error counters should clip at 127
\end{enumerate}

\subsection{Test of the optical data transmission}
\label{softw:tst:opt-data}

This test uses data, generated in the CPLD. Please do not mix with the test pattern send by the TLK chip
(spare bit position = 10 in table \ref{tab:ori_mode}) - it is hard to use when the receiver (deserializer) chip
is not of the same type.

The full procedure is:

\begin{enumerate}
\item Clear the \reg{NED.o} bit in the half-chamber merger, normally it is cleared if the TRAP is configured, but
is set after reset
\item Clear the CPLD by pulling down the RESET\_n line for short time (see fig. \ref{fig:block_jt_j2c})
\item Go to the test pattern mode by writing 12 as position of the spare bit (see \reg{SPAPAR} and
table \ref{tab:ori_mode})
\item Stop the test pattern mode by writing anything below 10 as position of the spare bit
\item Read the transmitted data, the expected pattern is described in section \ref{j2c:cpld}
\end{enumerate}

The procedure above doesn't need configured TRAPs, except for (1). One shortcoming is that the 
length of the data packed is not well defined, as the start and stop is done by DCS software.

Provided the TRAPs are configured one can use the TRAP CPUs to start and stop the test-pattern (3-4) for well defined time
intervals. Sending $N$ (8-bit) to address 7 via the {\bf j2c} interface {\bf using the CPU} enables the test-pattern mode
in the CPLD for a time window
proportional to $N+1$, thus sending approx. $2000 \cdot (N+1)$ 16-bit words of test-pattern from the CPLD. Note that this feature
doesn't exist in the CPLD design, just the CPU j2c interface routine detects writing to address 7 and replaces it
with writing 0xC0 to address 0 (start test-pattern), delay, and writing 0 to address 0 (stop test-pattern).

In CPLD test-pattern mode the counter \reg{N16W} is not usable, it counts, but unfortunately gets a reset when
stopping, as any j2c write resets the counters.
