%==============================================================================
% Document header
%==============================================================================
\documentclass[a4paper,11pt]{article}

% Color package
\usepackage[usenames,dvipsnames]{color}

% Hyperrefs
\usepackage[
  colorlinks = true,
  linkcolor  = Mahogany,
  citecolor  = Mahogany,
  urlcolor   = blue,
]{hyperref}

\usepackage{graphicx}
\usepackage{multirow}

\usepackage[toc,page]{appendix}

% Header and footer customization
\usepackage{fancyhdr}
\setlength{\headheight}{15.2pt}
\pagestyle{fancy}
\fancyhead[L]{\nouppercase{\leftmark}}
\fancyhead[R]{} 
\renewcommand{\footrulewidth}{0.4pt}

%==============================================================================
% Start of document
%==============================================================================
\begin{document}

%------------------------------------------------------------------------------
% Title
%------------------------------------------------------------------------------
\include{cern-title}

%------------------------------------------------------------------------------
% Revision history
%------------------------------------------------------------------------------
\thispagestyle{empty}
\section*{Revision history}

\centerline
{
  \begin{tabular}{l c p{.6\textwidth}}
  \hline
  \multicolumn{1}{c}{\textbf{Date}} & \multicolumn{1}{c}{\textbf{Version}} & \multicolumn{1}{c}{\textbf{Change}} \\
  \hline
  04-07-2013 & 0.1 & First draft \\
  26-07-2013 & 0.2 & Second draft \\
  07-08-2013 & 1.02 & Added pulse rejection to \textit{ctb\_pulse\_gen} \\
  14-08-2013 & 1.02 & Changed name of \textit{elma\_i2c} to \textit{vbcp\_wb} \\
  29-10-2013 & 2.00 & Added MultiBoot support to firmware \\
  \hline
  \end{tabular}
}

\pagebreak
\pagenumbering{roman}
\setcounter{page}{1}
\tableofcontents

%------------------------------------------------------------------------------
% List of figs, tables, abbrevs
%------------------------------------------------------------------------------
\pagebreak
\listoffigures
\listoftables

\section*{List of Abbreviations}
\begin{tabular}{l l}
DAC    & Digital-to-Analog Converter \\
FPGA   & Field-Programmable Gate Array \\
FSM    & Finite-State Machine \\
IC     & Integrated Circuit \\
I$^2$C & Inter-Intergrated Circuit (bus) \\
PLL    & Phase-Locked Loop \\
SPI    & Serial Peripheral Interface \\
SysMon & (ELMA) System Montior \\
VCXO   & Voltage-controlled oscillator \\
\end{tabular}

\pagebreak
\pagenumbering{arabic}
\setcounter{page}{1}

%==============================================================================
% SEC: Intro
%==============================================================================
\section{Introduction}
\label{sec:intro}

This document details the HDL implemented on the Spartan-6 FPGA on the CONV-TTL-BLO
board. The HDL (mostly implemented in VHDL) handles the following aspects of
the CONV-TTL-BLO capabilities:
\begin{itemize}
  \item pulse detection (on pulse rising edge)
  \item fixed-width pulse generation
  \item status retrieval via I$^2$C and VBCP
  \item remote reprogramming via I$^2$C and VBCP
\end{itemize}

Figure~\ref{fig:hdl-bd} shows a simplified block diagram of the HDL firmware. Each of the
blocks in the figure is presented in following sections.

\begin{figure}[h]
  \centerline{\includegraphics[width=\textwidth]{fig/hdl-bd}}
  \caption{Block diagram of FPGA firmware}
  \label{fig:hdl-bd}
\end{figure}

%------------------------------------------------------------------------------
% SUBSEC: Additional doc
%------------------------------------------------------------------------------
\subsection*{Additional documentation}

%\textcolor{red}{\textbf{!!!}}

\begin{itemize}
  \item CONV-TTL-BLO User Guide \cite{ctb-ug}
  \item CONV-TTL-BLO Hardware Guide \cite{ctb-hwguide}
\end{itemize}

%==============================================================================
% SEC: Clocks
%==============================================================================
\section{FPGA Clocks}
\label{sec:clocks}

There are two clock signals input to the FPGA (Figure~\ref{fig:clocks}).
The first is a 20~MHz signal from a VCXO. The second clock signal with a frequency
of 125~MHz is generated on-board via a Texas Instruments PLL IC from a 25~MHz VCXO.

Two DACs are provided on-board for controlling the two VCXOs. The DACs can be
controlled via SPI, but this feature is not yet implemented.

\begin{figure}
  \centerline{\includegraphics[width=\textwidth]{fig/clocks}}
  \caption{FPGA clock inputs}
  \label{fig:clocks}
\end{figure}

Table~\ref{tbl:clocks} lists the clock domains in the firmware.

\begin{table}[h]
  \caption{Clock domains}
  \label{tbl:clocks}
  \centerline
  {
    \begin{tabular}{c c l}
    \hline
    \textbf{Clock domain} & \textbf{Frequency} & \multicolumn{1}{c}{\textbf{Comments}} \\
    \hline
    \textit{clk125} & 125~MHz & Global clock input to all sequential logic \\
    \hline
    \end{tabular}
  }
\end{table}

%==============================================================================
% SEC: Reset gen
%==============================================================================
\section{Reset generator}
\label{sec:reset-gen}

%\begin{table}[h]
%  \caption{Reset generator}
%  \label{tbl:pulse-gen}
  \centerline
  {
    \begin{tabular}{l l l}
    \hline
    \textbf{Entity}   & \textit{reset\_gen}     & \\
    \textbf{Generics} & \textit{g\_reset\_time} & Reset time in \textit{clk\_i} cycles \\
    \textbf{Ports}    & \textit{clk\_i}         & Clock signal \\
                      & \textit{rst\_i}         & Active-high reset input \\
                      & \textit{rst\_n\_o}      & Active-low reset output \\
    \textbf{Usage}    & Global reset generation & 96~$ms$ reset \\
    \hline
    \end{tabular}
  }
%\end{table}

\vspace*{11pt}

The reset generator module (\textit{reset\_gen}) implemented inside the FPGA
generates a predefined-width reset signal when power is applied to the FPGA, or
when an external reset is triggered via the \textit{rst\_i} pin.

When a power-on reset occurs on the Xilinx FPGA, a counter inside the \textit{reset\_gen}
module starts counting up. While this counter is counting up, the active-low reset signal
is kept low, resetting synchronous logic inside the FPGA. When the counter reaches the
value of the reset width (specified via the \textit{g\_reset\_time} generic at synthesis
time), the reset signal is de-asserted, the counter is disabled and the \textit{reset\_gen}
module remains inactive.

The module reactivates on the power-on reset, or when a reset is triggered externally, via
the \textit{rst\_i} pin.

Note that the VHDL of this module is Xilinx and XST-specific and porting to a different
FPGA architecture is not guaranteed to provide the same results. The \textit{reset\_gen}
module has an initial value set for the counter signal after power-up, which is guaranteed
by XST to be set after the FPGA's GSR signal is de-asserted.

By default, the reset time is set to 96~$ms$.

%==============================================================================
% SEC: RTM detection
%==============================================================================
\section{RTM detection}
\label{sec:rtm-detect}

%\begin{table}[h]
%  \caption{RTM detection block}
%  \label{tbl:pulse-gen}
  \centerline
  {
    \begin{tabular}{l l l}
    \hline
    \textbf{Entity}   & \textit{rtm\_detector} & \\
    \textbf{Ports}    & \textit{rtmm\_i(2..0)} & RTM mainboard detection lines \\
                      & \textit{rtmp\_i(2..0)} & RTM piggyback detection lines \\
                      & \textit{rtmm\_ok\_o}   & RTM mainboard present \\
                      & \textit{rtmp\_ok\_o}   & RTM piggyback present \\
    \textbf{Usage}    & Light ERR status LED   & \\
    \hline
    \end{tabular}
  }
%\end{table}

\vspace*{11pt}

RTM detection is described in \cite{rtm-detect}. Since an RTMM/P missing would mean
all \textit{rtmm\_i}/\textit{rtmp\_i} lines are all-ones, the \textit{rtm\_detector}
module sets the \textit{rtmm\_ok} and \textit{rtmp\_ok} signals low if the
\textit{rtmm\_i} and \textit{rtmp\_i} input signals are respectively all-ones.

The \textit{rtmm\_ok} and \textit{rtmp\_ok} signals are NANDed together to light
the ERR status LED on the CONV-TTL-BLO.

\begin{figure}[h]
  \centerline{\includegraphics[width=.85\textwidth]{fig/rtm-detect}}
  \caption{\textit{rtm\_detector} block in CONV-TTL-BLO firmware}
  \label{fig:rtm-detect}
\end{figure}

The status of the RTM detection lines can also be read via their respective fields
in the CONV board status register (Appendix~\ref{app:memmap-csr}).


%==============================================================================
% SEC: Bicolor LEDs
%==============================================================================
\section{Bicolor LED controller}
\label{sec:bicolor-led}

%\begin{table}[h]
%  \caption{Bicolor LED controller block}
%  \label{tbl:pulse-gen}
  \centerline
  {
    \begin{tabular}{l l l}
    \hline
    \textbf{Entity}   & \textit{bicolor\_led\_ctrl}      & \\
    \textbf{Generics} & \textit{g\_NB\_COLUMN}           & Number of columns \\
                      & \textit{g\_NB\_LINE}             & Number of lines \\
                      & \textit{g\_CLK\_FREQ}            & Frequency (in Hz) of \textit{clk\_i} signal \\
                      & \textit{g\_REFRESH\_RATE}        & LED refresh rate (in Hz)\\
    \textbf{Ports}    & \textit{rst\_n\_i}               & Active-low reset input \\
                      & \textit{clk\_i}                  & Clock signal input \\
                      & \textit{led\_intensity\_i(6..0)} & 7-bit LED intensity vector \\
                      & \textit{led\_state\_i(..)}       & LED state vector, two bits per LED \\
                      & \textit{column\_o(..)}           & LED column vector, one bit per column \\
                      & \textit{line\_o(..)}             & LED line vector, one bit per line \\
                      & \textit{line\_oen\_o(..)}        & LED line enable vector, one bit per line\\
    \textbf{Usage}    & Light bicolor LEDS               & \\
    \hline
    \end{tabular}
  }
%\end{table}

\vspace*{11pt}

The \textit{bicolor\_led\_ctrl} block controls the lighting of a bicolor
LED matrix. Based on the refresh rate given via the \textit{g\_REFRESH\_RATE}
generic, the clock frequency (\textit{g\_CLK\_FREQ} generic) and the number of
lines and columns, the module controls lighting each LED in the LED matrix.

Figure~\ref{fig:bicolor-led} shows an example of controlling a three-line,
two-column red-and-green LED matrix. The FPGA ouputs for the columns~(C) are connected
to buffers and serial resistors and then to the LEDs. The FPGA outputs for lines~(L)
are connected to tri-state buffers and the to the LEDs. The FPGA outputs for line
output enables~(L\_OEN) are connected to the output enable of the tri-state buffers.

\begin{figure}[hbtp]
  \centerline{\includegraphics[width=\textwidth]{fig/bicolor-led}}
  \caption{3x2 bicolor LED matrix control}
  \label{fig:bicolor-led}
\end{figure}

The two-bit \textit{led\_state\_i} vector can be used to control the color of each
LED. Table~\ref{tbl:bicolor-led-state} lists the values that should be input on
\textit{led\_state\_i} to get the needed color. Definitions are provided in
the \textit{bicolor\_led\_ctrl\_pkg.vhd} file for setting the color of the LED
via \textit{led\_state\_i}; these constants are also listed in Table~\ref{tbl:bicolor-led-state}.

\begin{table}[h]
  \caption{LED state input}
  \label{tbl:bicolor-led-state}
  \centerline
  {
    \begin{tabular}{l l c}
    \hline
    \multicolumn{1}{c}{\textbf{State}} & \multicolumn{1}{c}{\textbf{Constant}} & \textbf{Value} \\
    \hline
    Off    & c\_LED\_OFF         & 00 \\
    Green  & c\_LED\_GREEN       & 01 \\
    Red    & c\_LED\_RED         & 10 \\
    Orange & c\_LED\_RED\_ORANGE & 11 \\
    \hline
    \end{tabular}
  }
\end{table}

Each LED's two-bit state is connected to \textit{led\_state\_i} on a column-first,
line-second basis.

%------------------------------------------------------------------------------
% SUBSEC: Board-level
%------------------------------------------------------------------------------
\subsection{Board-level view}
\label{sec:bicolor-led-brdlvl}

There are twelve bicolor LEDs on the CONV-TTL-BLO; they are connected in a two-line,
six-column pattern controlled by a \textit{bicolor\_led\_ctrl} block.
Table~\ref{tbl:bicolor-led-state-conn} shows the \textit{led\_state\_i} connections
for the bicolor status LEDs in the CONV-TTL-BLO firmware.

\begin{table}[h]
  \caption{LED state vector connections in the firmware}
  \label{tbl:bicolor-led-state-conn}
  \centerline
  {
    \begin{tabular}{l c l c c}
    \hline
    \textbf{Line} & \textbf{Column} & \multicolumn{1}{c}{\textbf{LED}} &  \textbf{LED state bits} & \textbf{Setting}\\
    \hline
    1 & 1 & WHITE\_RABBIT\_ADDR & \textit{1..0}   \\
    1 & 2 & WHITE\_RABBIT\_GMT  & \textit{3..2}   \\
    1 & 3 & WHITE\_RABBIT\_LINK & \textit{5..4}   \\
    1 & 4 & WHITE\_RABBIT\_OK   & \textit{7..6}   \\
    1 & 5 & MULTICAST\_ADDR\_1  & \textit{9..8}   \\
    1 & 6 & MULTICAST\_ADDR\_2  & \textit{11..10} \\
    2 & 1 & I2C                 & \textit{13..12} \\
    2 & 2 & TTL                 & \textit{15..14} \\
    2 & 3 & ERR                 & \textit{17..16} \\
    2 & 4 & PW                  & \textit{19..18} \\
    2 & 5 & MULTICAST\_ADDR\_4  & \textit{21..20} \\
    2 & 6 & MULTICAST\_ADDR\_8  & \textit{23..22} \\
    \hline
    \end{tabular}
  }
\end{table}

The states of the used LEDs can be found in Table 1 of \cite{ctb-ug}. They are
controlled by combinatorial multiplexers. The selection signals to these
multiplexers are set throughout the logic.

%==============================================================================
% SEC: Pulse gen
%==============================================================================
\pagebreak
\section{Pulse generator}
\label{sec:pulse-gen}

%\begin{table}[h]
%  \caption{Pulse generator blocks}
%  \label{tbl:pulse-gen}
  \centerline
  {
    \begin{tabular}{l l l}
    \hline
    \textbf{Entity} & \textit{ctb\_pulse\_gen} & \\
    \textbf{Generics} & \textit{g\_pwidth}     & Width of the output pulse in \textit{clk\_i} cycles \\
                      & \textit{g\_gf\_len}    & Length of glitch filter \\
    \textbf{Ports} & \textit{clk\_i}           & Clock signal \\
                   & \textit{rst\_n\_i}        & Active-low reset signal \\
                   & \textit{en\_i}            & Pulse generator enable \\ 
                   & \textit{gf\_en\_n\_i}     & Active-low glitch filter enable \\
                   & \textit{trig\_i}          & Pulse trigger \\
                   & \textit{pulse\_o}         & Pulse output \\
    \textbf{Usage} & Output pulse              & 1.2~$\mu$s pulses with min. period of 6~$\mu$s\\
    \hline
    \end{tabular}
  }
%\end{table}

\vspace*{11pt}

The \textit{ctb\_pulse\_gen} block generates pulses on the rising edge of the
\textit{trig\_i} input. The pulse width is configurable via the \textit{g\_pwidth}
generic. The block also incorporates a glitch filter with a configurable length
(\textit{g\_gf\_len}) that can be used to avoid pulses generated because of
glitches at the \textit{trig\_i} input.

Pulse widths at the output are limited internally to 1/5 duty cycle, to safeguard
the blocking output transformers.

Six \textit{ctb\_pulse\_gen} blocks (one per channel) are used for generating blocking and TTL
pulses at the outputs, based on trigger inputs arriving on the channels. The \textit{ctb\_pulse\_gen} blocks
are configured for 1.2~${\mu}s$ pulses (\textit{g\_pwidth = 150}, considering the 8~$ns$ clock input).

%------------------------------------------------------------------------------
% SUBSEC: Implem
%------------------------------------------------------------------------------
\subsection{Implementation}
\label{sec:pulse-gen-implem}

Figure~\ref{fig:pulse-gen} shows the implementation of the \textit{ctb\_pulse\_gen}
block. It employs a finite-state machine (FSM) that is used to generate
a fixed-width pulse at the output.

\begin{figure}[h]
  \includegraphics[width=\textwidth]{fig/pulse-gen}
  \caption{Pulse generator block}
  \label{fig:pulse-gen}
\end{figure}

The glitch filter can be used to decrease sensitivity to glitches in noisy environments.
It can be enabled via the \textit{gf\_en\_n\_i} input (connected to SW1.1 on the CONV-TTL-BLO).
The length of the filter can be set via the \textit{g\_gf\_len} generic.

Enabling the glitch filter will lead to the trigger being sampled using \textit{clk125}
and introduces leading-edge jitter on the \textit{pulse\_o} output. To avoid this
leading-edge pulse jitter, the glitch filter can be left disabled.

Regardless of whether the glitch filter is enabled or not, the FSM reacts to the
rising edge of one of its two start inputs. A rising edge on an input starts
the internal counter, which counts up to a maximum value of \textit{g\_pwidth}.
The behavior of the outputs are different, depending on the state of the glitch filter.

With the glitch filter disabled, the input pulse enables the
input flip-flop, which starts pulse generation. The pulse signal is then synchronized
in the \textit{clk125} domain and input to the synchronous FSM, which extends the
pulse to \textit{g\_pwidth}. The rising edge on \textit{SGF0} triggers the counter,
and when the counter reaches the value corresponding to the selected pulse width,
it sets the \textit{OGF0} output, which will reset the input flip-flop, thus ending the pulse.

With the glitch filter enabled, the rising edge on \textit{SGF1} sets \textit{OGF1},
and this will be kept high until the counter reaches the value corresponding to the
pulse width.

After the pulse generation period, the FSM goes into a pulse rejection state,
where the pulse reset is kept high. If any pulses arrive on the input while the FSM
is in this rejection state, they are not replicated at the output. The pulse rejection
phase lasts for 4*\textit{g\_pwidth}, yielding a maximum duty cycle of 1/5 for input pulses.

%------------------------------------------------------------------------------
% SUBSEC: Board-level
%------------------------------------------------------------------------------
\subsection{Board-level view}
\label{sec:pulse-gen-brdlvl}

Figure~\ref{fig:pulse-brd} shows the pulse replication mechanism on the
CONV-TTL-BLO. Here, the \textit{PG} block is the \textit{ctb\_pulse\_gen} block
with the necessary settings. Since the \textit{ctb\_pulse\_gen} block expects
a rising edge at its \textit{trig\_i} input in order to generate a pulse at
the output, logic external to the block caters for the different types of signals
that arrive on CONV-TTL-BLO inputs.

\begin{figure}[h]
  \centerline{\includegraphics[width=\textwidth]{fig/pulse-rep}}
  \caption{Board-level view of pulse replication mechanism}
  \label{fig:pulse-brd}
\end{figure}

Most of this external logic is on the TTL pulse side, where both TTL and TTL-BAR
pulses may arrive. As described in Section 4.3 of \cite{ctb-ug}, if a wire is not plugged in
when TTL-BAR pulses are input, a continuous logic high level on the line would inhibit
pulses arriving on the blocking side from triggering a pulse generation. This is why
the \textit{no sig. detect} block has been implemented.

The block's implementation is shown in Figure~\ref{fig:no-sig-detect}. It is implemented as
a counter which keeps the \textit{en\_o} signal high as long as it does not reach its maximum value.
The counter counts up when the \textit{cnt} input is high. By setting the maximum value
of the counter to 12499, it disables the line to the multiplexer if this stays high
for 100~${\mu}s$, thus allowing for blocking pulses at the input of the OR gate. The line
is re-enabled as soon as it goes back low, i.e., when a wire has been plugged in to the
channel.

\begin{figure}[h]
  \centerline{\includegraphics[width=.75\textwidth]{fig/no-sig-detect}}
  \caption{No signal detect block}
  \label{fig:no-sig-detect}
\end{figure}

%==============================================================================
% SEC: Mem-mapped periphs
%==============================================================================
\section{Memory-mapped peripherals}
\label{sec:periphs}

This section details the various peripherals mapped on the internal
Wishbone bus. Access to these peripherals is made through the two serial lines
on the VME P1 connector (\textit{SERCLK}, \textit{SERDAT}). The VBCP protocol
is used to access these peripherals. A bridge module translates VBCP transfers into
Wishbone transfers.

The complete memory map of the firmware can be found in Appendix~\ref{app:memmap}.

%------------------------------------------------------------------------------
% SUBSEC: Statregs
%------------------------------------------------------------------------------
\subsection{VBCP to Wishbone bridge}
\label{sec:elma-i2c}

The \textit{vbcp\_wb} module implements a bridge between the serial lines on the
VME P1 connector using VBCP and the Wishbone interconnect. The module provides
one I$^2$C slave interface for connecting to an ELMA SysMon and one Wishbone
master interface.

Details about the module's implementation can be found in its documentation, in
the \textit{conv\_ttl\_blo\_gw/doc/vbcp\_wb/} folder  (see Section~\ref{sec:fold-struct}).

%------------------------------------------------------------------------------
% SUBSEC: CSR
%------------------------------------------------------------------------------
\subsection{Control and status registers}
\label{sec:periphs-csr}

The status registers implemented in the firmware contain the current firmware
version, the position of the on-board switches and the values on RTM detection lines.

No control registers are currently implemented.

See Appendix~\ref{app:memmap-csr} for more information.

%------------------------------------------------------------------------------
% SUBSEC: MultiBoot
%------------------------------------------------------------------------------
\subsection{MultiBoot control}
\label{sec:periphs-multiboot}

The MultiBoot module offers the remote reprogramming capabilities for the
CONV-TTL-BLO board. It offers a set of registers for controlling writing a bitstream
to the M25P32 flash chip and for issuing the remote reprogramming command.

For information on the module, refer to its documentation under the
\textit{conv\_ttl\_blo\_gw/doc/multiboot/} folder (see Section~\ref{sec:fold-struct}).
The memory map of the module is also present in this manual, for quick reference
(see Appendix~\ref{app:memmap-multiboot}).

%======================================================================================
% SEC: Folder structure
%======================================================================================
\section{Folder Structure}
\label{sec:fold-struct}

The folder structure for the project is presented below.

\renewcommand{\labelitemi}{$\rightarrow$}
\renewcommand{\labelitemii}{$\rightarrow$}
\renewcommand{\labelitemiii}{$\rightarrow$}
\renewcommand{\labelitemiv}{$\rightarrow$}

\begin{itemize}
  \item ../ip\_cores/
  \item conv-ttl-blo-gw/doc/
  \begin{itemize}
    \item hdlguide/
    \item i2c\_slave/
    \item multiboot/
    \item vbcp\_wb/
  \end{itemize}
  \item conv-ttl-blo-gw/hdl/
  \begin{itemize}
    \item bicolor\_led\_ctrl/
    \begin{itemize}
      \item \textit{bicolor\_led\_ctrl.vhd}
      \item \textit{bicolor\_led\_ctrl\_pkg.vhd}
    \end{itemize}
    \item ctb\_pulse\_gen/
    \begin{itemize}
      \item rtl/
      \begin{itemize}
        \item \textit{ctb\_pulse\_gen.vhd}
      \end{itemize}
    \end{itemize}
    \item glitch\_filt/
    \begin{itemize}
      \item rtl/
      \begin{itemize}
        \item \textit{glitch\_filt.vhd}
      \end{itemize}
    \end{itemize}
    \item multiboot/
    \begin{itemize}
      \item rtl/
      \begin{itemize}
        \item \textit{multiboot\_fsm.vhd}
        \item \textit{multiboot\_regs.vhd}
        \item \textit{spi\_master.vhd}
        \item \textit{xil\_multiboot.vhd}
      \end{itemize}
    \end{itemize}
  \textbf
  {
    \item release/
    \begin{itemize}
      \item rtl/
      \begin{itemize}
        \item \textit{conv\_regs.vhd}
      \end{itemize}
      \item top/
      \begin{itemize}
        \item \textit{conv\_ttl\_blo.vhd}
        \item \textit{conv\_ttl\_blo.ucf}
      \end{itemize}
    \end{itemize}
  }
    \item reset\_gen/
    \begin{itemize}
      \item rtl/
      \begin{itemize}
        \item \textit{reset\_gen.vhd}
      \end{itemize}
    \end{itemize}
    \item rtm\_detector/
    \begin{itemize}
      \item rtl/
      \begin{itemize}
        \item \textit{rtm\_detector.vhd}
      \end{itemize}
    \end{itemize}
    \item vbcp\_wb/
    \begin{itemize}
      \item rtl/
      \begin{itemize}
        \item \textit{i2c\_slave.vhd}
        \item \textit{vbcp\_wb.vhd}
      \end{itemize}
    \end{itemize}
  \end{itemize}
\end{itemize}


The \textit{ip\_cores/} folder contains repository files that the firmware uses, such
as the Wishbone crossbar (\textit{xwb\_crossbar}).

Documentation such as this HDL guide and some HDL modules developed as part of the 
CONV-TTL-BLO project can be found in the \textit{conv-ttl-blo/doc/} folder.

Modules that have been developed as part of the CONV-TTL-BLO project are present in
their own folders as sub-nodes of the \textit{conv-ttl-blo/hdl/} folder. In general,
the module files are present under an \textit{rtl/} sub-folder. The I$^2$C bridge
module folder also contains the instantiated \textit{i2c\_slave} module.

The \textit{release/} folder is the main folder in the firmware package, as can be seen from the
fact that it is bolded in the folder structure above. It contains top-level files in the
\textit{top/} folder (HDL and UCF file for pin definitions) and other specific modules in
the \textit{rtl/} folder.

%======================================================================================
% SEC: Getting Around the Code
%======================================================================================
\section{Getting Around the Code}
\label{sec:get-around}

As described above, the main part of the release firmware can be found in the
\textit{conv-ttl-blo/hdl/release/} folder. The top-level file is \textit{conv\_ttl\_blo.vhd}.

Ports and signals usually follow the coding guideline at~\cite{coding-guidelines}. Most of the
top-level ports of the firmware are lower-case versions of their schematics counterparts. The
exceptions from this are due to either net names that could not be syntactically represented in
VHDL, or net names that have been made clearer in VHDL code. Input ports are assigned to architecture
signals and signals are assigned to output ports in each code section.

\begin{figure}[h]
  \centerline{\includegraphics[width=.7\textwidth]{fig/arch}}
  \caption{VHDL architecture}
  \label{fig:arch}
\end{figure}

The declarative part of the architecture is organized as shown in Figure~\ref{fig:arch}~(a).
Types are declared right after the architecture declaration, followed by con-
stant declarations, followed by component declarations, after which the var-
ious signals are declared.

The body of the architecture is organised as shown in in Figure~\ref{fig:arch}~(b). It begins
by instantiating a differential buffer for the 125~MHz system clock and instantiating the
\textit{reset\_gen} component. Then, the \textit{vbcp\_wb} bridge module is instantiated
along with the Wishbone crossbar that offers access to the rest of the Wishbone modules in
the design. Next, the CONV board CSR module is instantiated, followed by the instantiation
of twelve pulse generator modules, six for pulse repetition and six for the pulse LEDs.
This is followed by the logic for the status LEDs and the file ends with the RTM detection
modules.


%==============================================================================
% Appendices
%==============================================================================
\pagebreak
\begin{appendices}

%==============================================================================
% APP: Memmap
%==============================================================================
\section{Memory map}
\label{app:memmap}

Table~\ref{tbl:memmap} shows the complete memory map of the firmware. The
following sections list the memory map of each peripheral.

\begin{table}[h]
\caption{CONV-TTL-BLO memory map}
\label{tbl:memmap}
\centerline
{
  \begin{tabular}{l l l p{.4\textwidth}}
  \hline
  \multicolumn{1}{c}{\textbf{Periph.}} & \multicolumn{2}{c}{\textbf{Address}} & \multicolumn{1}{c}{\textbf{Description}} \\
  & \multicolumn{1}{c}{\textbf{Base}} & \multicolumn{1}{c}{\textbf{End}} & \\
  \hline
  CSR       & 0x000 & 0x0f & Control and status register \\
  MultiBoot & 0x040 & 0x5f & MultiBoot module \\
  \hline
  \end{tabular}
}
\end{table}

%------------------------------------------------------------------------------
% CSR
%------------------------------------------------------------------------------
\subsection{Control and status registers}
\label{app:memmap-csr}

\indent Base address: 0x000

\begin{table}[h]
    \begin{tabular}{l l p{.6\textwidth}}
    \textbf{Offset} & \textbf{Name} & \textbf{Description} \\
    0x0 & BID & Board ID register \\
    0x4 & SR  & Status register \\
    0x8 & \textit{Reserved} & Read undefined; write as 0 \\
    0xc & \textit{Reserved} & Read undefined; write as 0 \\
    \end{tabular}
\end{table}

%------------------------------------------------------------------------------
\subsubsection{Board ID register}

\begin{tabular}{l l c c l}
\textbf{Bits} & \textbf{Field} & \textbf{Access} & \textbf{Default} & \textbf{Description} \\
31..0         & ID             & R/O             & 0x424c4f32       & Board ID \\
\end{tabular}

\vspace*{11pt}

\noindent
{
  \begin{tabular}{l l}
  \textbf{Field} & \textbf{Description} \\
  ID             & Board ID (ASCII string \textbf{BLO2}) \\
  \end{tabular}
}

%------------------------------------------------------------------------------
\subsubsection{Status register}

\begin{tabular}{l l c c l}
\textbf{Bits} & \textbf{Field}    & \textbf{Access} & \textbf{Default} & \textbf{Description} \\
15..0         & FWVERS            & R/O             & X                & Firmware version \\
23..16        & SWITCHES          & R/O             & X                & Switch status \\
29..24        & RTM               & R/O             & X                & RTM detection lines \\
31..30        & \textit{Reserved} & R/O             & X                & \\
\end{tabular}

\noindent
{
  \begin{tabular}{l p{.8\textwidth}}

  \textbf{Field}  & \textbf{Description} \\
  FWVERS          & Firmware version \newline
                    -- leftmost byte \textit{hex value} is major release \textit{decimal value} \newline
                    -- rightmost byte \textit{hex value} is minor release \textit{decimal value} \newline
                    e.g. \newline
                    0x0101 -- v1.01\newline
                    0x0107 -- v1.07 \newline
                    0x0274 -- v2.74 \newline
                    etc. \\
  SWITCHES        & Current switch status \newline
                    bit 0 -- SW1.1 \newline
                    bit 1 -- SW1.2 \newline
                    ... \newline
                    bit 7 -- SW2.4 \newline
                    \textbf{1} -- switch is \textbf{OFF} \newline
                    \textbf{0} -- switch is \textbf{ON} \\
  RTM             & RTM detection lines status \newline
                      \textbf{0} -- line active \newline
                      \textbf{1} -- line inactive \\
  \textit{Reserved} & Write as '0'; read undefined \\                 
  \end{tabular}
}

%------------------------------------------------------------------------------
% MULTIBOOT
%------------------------------------------------------------------------------
\subsection{MultiBoot module}
\label{app:memmap-multiboot}

\indent Base address: 0x040

\vspace*{11pt}

\centerline
{
    \begin{tabular}{l l p{.6\textwidth}}
    \textbf{Offset} & \textbf{Name} & \textbf{Description} \\
    0x00 & CR    & Control Register \\
    0x04 & SR    & Status register \\
    0x08 & GBBAR & Golden Bitstream Base Address Register \\
    0x0c & MBBAR & Multiboot Bitstream Base Address Register \\
    0x10 & FAR   & Flash access register \\
    0x14 & \textit{Reserved} & Read undefined; write as 0 \\
    0x18 & \textit{Reserved} & Read undefined; write as 0 \\
    0x1c & \textit{Reserved} & Read undefined; write as 0 \\
    \end{tabular}
}

%------------------------------------------------------------------------------
\subsubsection{CR -- Control Register}
\label{app:memmap-multiboot-cr}

\begin{tabular}{l l c c l}
\textbf{Bits} & \textbf{Field}    & \textbf{Access} & \textbf{Default} & \textbf{Description} \\
31..18        & \textit{Reserved} & --              & X                &  \\
17            & IPROG             & R/W             & 0                & IPROG bit \\
16            & IPROG\_UNL        & R/W             & 0                & IPROG unlock bit \\
15..7         & \textit{Reserved} & --              & X                &  \\
6             & RDCFGREG          & R/W             & 0                & Read config register \\
5..0          & CFGREGADR         & R/W             & 0                & Config register address \\
\end{tabular}

\vspace*{11pt}

\noindent
{
  \begin{tabular}{l p{.7\textwidth}}
  \textbf{Field}    & \textbf{Description} \\
  \textit{Reserved} & Write as '0'; read undefined \\
  IPROG    & When 1, it triggers the FSM to send the IPROG command to the ICAP controller \newline
             This bit needs to be unlocked by setting the IPROG\_UNL bit in a previous cycle \\
  IPROG\_UNL & Unlock bit for the IPROG command. This bit needs to be set to 1 prior to writing
               the IPROG bit \\
  RDCFGREG & Initiate a read from the FPGA configuration register at address CFGREGADR \newline
             This bit is automatically cleared by hardware \\
  CFGREGADR & The address of the FPGA configuration register to read (see Configuration Registers
              section in~\cite{ug380})\\
  \end{tabular}
}

%------------------------------------------------------------------------------
\subsubsection{IMGR -- Image Register}
\label{app:memmap-multiboot-imgr}

\begin{tabular}{l l c c l}
\textbf{Bits} & \textbf{Field}    & \textbf{Access} & \textbf{Default} & \textbf{Description} \\
31..17        & \textit{Reserved} & --              & X                & \\
16            & VALID             & R/O             & 0                & Image register is valid \\
15..0         & CFGREGIMG         & R/O             & 0                & Config. register image \\
\end{tabular}

\vspace*{11pt}

\noindent
{
  \begin{tabular}{l p{.7\textwidth}}

  \textbf{Field}  & \textbf{Description} \\
  \textit{Reserved} & Write as '0'; read undefined \\
  VALID           & A read has been performed from the FPGA configuration
                    register at address CR.CFGREGADR, and its value is
                    present in CFGREGIMG \\
  CFGREGIMG       & Contains the value of the FPGA configuration register;
                    validated by the VALID bit (see Configuration Registers
                    section in~\cite{ug380}) \\
  \end{tabular}
}

%------------------------------------------------------------------------------
\subsubsection{GBBAR -- Golden Bitstream Base Address Register}
\label{app:memmap-multiboot-gbbar}

\begin{tabular}{l l c c l}
\textbf{Bits} & \textbf{Field}    & \textbf{Access} & \textbf{Default} & \textbf{Description} \\
31..24        & OPCODE            & R/W             & 0                & Flash chip read op-code \\
23..0         & GBA               & R/W             & 0                & Golden Bitstream Address \\
\end{tabular}

\vspace*{11pt}

\noindent
{
  \begin{tabular}{l p{.7\textwidth}}

  \textbf{Field}    & \textbf{Description} \\
  OPCODE            & Op-code for the flash chip read (or fast-read) command. Get
                      this value from the flash chip datasheet \\
  GBA               & Start address of the Golden bitstream on the flash chip \\
  \end{tabular}
}

\vspace*{11pt}

%Guidelines on selecting a GBBAR:
%
%\begin{itemize}
%  \item When generating the Header image via Xilinx ISE, the GBA is (normally)
%  automatically set by the software to 0x44
%  \item If different than the default, the starting address of the Golden
%  bitstream should be set to a flash sector boundary
%\end{itemize}

%------------------------------------------------------------------------------
\subsubsection{MBBAR -- MultiBoot Bitstream Base Address Register}
\label{app:memmap-multiboot-mbbar}

\begin{tabular}{l l c c l}
\textbf{Bits} & \textbf{Field}    & \textbf{Access} & \textbf{Default} & \textbf{Description} \\
31..24        & OPCODE            & R/W             & 0                & Flash chip read op-code \\
23..0         & MBA               & R/W             & 0                & MultiBoot Bitstream Address \\
\end{tabular}

\vspace*{11pt}

\noindent
{
  \begin{tabular}{l p{.7\textwidth}}

  \textbf{Field}    & \textbf{Description} \\
  OPCODE            & Op-code for the flash chip read (or fast-read) command. Get
                      this value from the flash chip datasheet \\
  MBA               & Start address of the MultiBoot bitstream on the flash chip \\
  \end{tabular}
}

\vspace*{11pt}

%Guidelines on selecting an MBBAR:
%
%\begin{itemize}
%  \item The MultiBoot bitstream should start on a flash sector boundary.
%\end{itemize}

%------------------------------------------------------------------------------
\subsubsection{FAR -- Flash Access Register}
\label{app:memmap-multiboot-far}

\begin{tabular}{l l c c l}
\textbf{Bits} & \textbf{Field}    & \textbf{Access} & \textbf{Default} & \textbf{Description} \\
31..29        & \textit{Reserved} & --              & 0                & Flash chip read op-code \\
28            & READY             & R               & 1                & SPI access status \\
27            & CS                & R/W             & 0                & SPI chip select \\
26            & XFER              & R/W             & 0                & Start SPI transfer \\
25..24        & NBYTES            & R/W             & 0                & Number of bytes to send \\
23..16        & DATA[2]           & R/W             & 0                & Data at offset 2 \\
15..8         & DATA[1]           & R/W             & 0                & Data at offset 1 \\
7..0          & DATA[0]           & R/W             & 0                & Data at offset 0 \\
\end{tabular}

\vspace*{11pt}

\noindent
{
  \begin{tabular}{l p{.7\textwidth}}

  \textbf{Field}    & \textbf{Description} \\
  \textit{Reserved} & Write as '0'; read undefined \\
  READY             & SPI transfer ready; NBYTES have been sent to the flash chip,
                      and NBYTES read from the chip present in DATA fields \\
  CS                & SPI chip select. Note that this pin has opposite polarity
                      than the normal SPI chip select pin: \newline
                      '1' -- flash chip is selected (CS pin = 0) \newline
                      '0' -- flash chip is not selected (CS pin = 1) \\
  XFER              & '1' -- starts SPI transfer \newline
                      This bit is automatically cleared by hardware \\
  NBYTES            & Number of DATA fields to send in one transfer \newline
                      0 -- send 1 byte (DATA[0]) \newline
                      1 -- send 2 bytes (DATA[0], DATA[1]) \newline
                      2 -- send 3 bytes (DATA[0], DATA[1], DATA[2]) \newline
                      3 -- \textit{Reserved} \\
  DATA[2]           & Write this register with the value of data byte 2 \newline
                      After an SPI transfer, this register contains the value of
                      data byte 2 read from the flash \\
  DATA[1]           & Write this register with the value of data byte 1 \newline
                      After an SPI transfer, this register contains the value of
                      data byte 1 read from the flash \\
  DATA[0]           & Write this register with the value of data byte 0 \newline
                      After an SPI transfer, this register contains the value of
                      data byte 0 read from the flash \\
  \end{tabular}
}

\end{appendices}

%==============================================================================
% Bibliography
%==============================================================================
\pagebreak
\bibliographystyle{ieeetr}
\bibliography{hdlguide-conv-ttl-blo}

\end{document}
