%%This is a very basic article template.
%%There is just one section and two subsections.
\documentclass[a4paper,11pt]{article}
\usepackage[pdfborder = 0 0 0 1]{hyperref}
\usepackage{graphicx}
\usepackage{appendix}

%%\usepackage{draftwatermark}
%%\SetWatermarkLightness{0.9}
%%\SetWatermarkScale{5}


\begin{document}
\title{\textbf{{\LARGE SPI master multifield\\ HDL core}}}
\author{Carlos Gil Soriano\\BE-CO-HT\\
\hypersetup{
  colorlinks   =  true,
  urlcolor     =  blue
  pdftitle     = {SPI master multifield HDL core},
  pdfauthor    = {Carlos Gil Soriano},
  pdfsubject   = {Reference guide for SPI master multifield HDL core},
  pdfkeywords  = {SPI, VHDL, core, register, mapping}
}
\href{mailto:carlos.gil.soriano@cern.ch}{\textbf{\textit{carlos.gil.soriano@cern.ch}}}}
\date{\today}
\maketitle
\thispagestyle{empty}
\begin{figure}[htb]
   \begin{center}
      \includegraphics[scale=0.5,
      keepaspectratio]{../../../doc/OHWR/Pictures/Figures/OHRlogo.png}
      \includegraphics[scale=0.25,
      keepaspectratio]{../../../doc/OHWR/Pictures/Figures/CERN-Logo.png}
   \end{center}
\end{figure}

\begin{abstract}
  A configurable SPI master multifield HDL core is depicted. Features:

  \begin{itemize}
     \item Wishbone interface. 
     \item Support to the four operation modes. 
     \item Three independent write fields with selectable length.
     \item One independent read field with selectable length.
     \item Protection against bad configurations.
  \end{itemize}

  
  The core is specially targeted for
  writing  blocks of EEPROM memories which typically requiere three fields.\\
 \end{abstract}

  \vspace{2cm}
  \begin{center}
  \begin{tabular}{|p{2.5cm}|p{3.75cm}|p{3cm}|}
  \hline
  \multicolumn{3}{|c|}{\textbf{Revision history}}\\
     \hline
     \hline
     \textbf{HDL version} & \textbf{Module} & \textbf{Date}\\
        \hline
        0.1 & SPI master multifield & July 20, 2012\\
        \hline
        0.9 & SPI master multifield & Sept. 20, 2012\\
        \hline
  \end{tabular}
  \end{center}

\pagebreak

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

Copyright CERN 2012.\\

This documentation describes Open Hardware and is licensed under the
CERN OHL v.1.1.\\

You may redistribute and modify this documentation under the terms of the CERN
OHL v.1.1. (\url{http://ohwr.org/cernohl}). This documentation is distributed WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, INCLUDING OF MERCHANTABILITY, SATISFACTORY QUALITY AND FITNESS FOR A PARTICULAR PURPOSE.\\

Please see the CERN OHL variable.1.1 for applicable conditions.\\

\pagebreak

\setcounter{tocdepth}{3}
\tableofcontents
\listoftables
\listoffigures
\pagebreak

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

\section{Structure}
  The SPI module contains several blocks related the following way:\\
  
  --  spi\_master\_top.vhd 
  
  ----- spi\_master\_regs.vhd
  
  ----- spi\_master\_slave\_core.vhd
  
  --------- FIFO\_dispatcher.vhd
  
  --------- gc\_counter.vhd
  
  --------- gc\_clk\_divider.vhd\\


The top module combines two components:
\textit{spi\_master\_core} and \textit{spi\_master\_regs}.
The first one can be used independently from their top module, saving some
interconnection lines and allowing a direct way of using the module. If access
to the control registers \textit{SPI[X]} through classic Wishbone interface is
desired, then the top module must be used.\\

Due to the target use of this SPI core (block transfers for memory interfaces) all
the three input fields are offered in both the top and the core modules.

Internally, the data in every of the three set of fields is registered by the
control registers, either by directly writing into the \textit{SPI[X]} register
(in the case of \textit{spi\_master\_core}) or through wishbone
(\textit{spi\_master\_top}).

\subsection{Dependencies}

Three components used in this core belong to general use in CTDAH board.
Due to that they are packed inside \textbf{ctdah\_lib}. The required components
to be imported are:\\

-- FIFO\_dispatcher.vhd

-- gc\_counter.vhd

-- gc\_clk\_divider.vhd

\subsection{Operation and invalid configurations}

The core analyses both SPI0 and SPI1 and if a valid operation is detected, it
executes it.

Valid operations must have, at least, an instruction field with instruction length different from zero.

\subsubsection{Invalid configurations}
To guarantee the reliability of the core, the following invalid configurations
are specified:
\begin{itemize}
\item A field (address write, data write or read) configured to be executed
with field lenght equaling zero. That field will be skipped.
\item A field with length bigger than the default length values of SPI1, will
be cropped to the default length value. 
\item If an SPI operation is running, updates of SPI0 and SPI1 will not be
attended.
\end{itemize}

\pagebreak
\section{Registers}
\subsection{SPI0}
The SPI0 is a write-read register.\\

Responsible of mode of SPI operation and the length of all configurable fields
(either write or read fields).\\

\begin{table}[!htb]
\begin{center}
  \begin{tabular}{| l | c | c | c |}
    \hline
    \textbf{Bits} & \textbf{Field} & \textbf{Meaning} & \textbf{Default}\\
    \hline
    \hline
    0     & \textbf{CPOL}  & Clock POLarity when idle & \textbf{"00000"} \\
    \hline  
    1     & \textbf{CPHA}  & Clock PHAse & \textbf{"00000"} \\
    \hline
    4-2   & \textbf{BREAD} & Reserved & \textbf{c\_READ\_LENGTH} \\
    \hline
    13-5  & \textbf{BDATA} & Bytes of DATA to be sent       & \textbf{c\_INST\_LENGTH}\\
    \hline
    22-14 & \textbf{BADDR} & Bytes of ADDRess to be sent    & \textbf{c\_ADDR\_LENGTH}\\
    \hline
    31-23 & \textbf{BINST} & Bytes of INSTruction to be sent& \textbf{c\_DATA\_LENGTH}\\
    \hline
  \end{tabular}\\
  \caption{SPI0 register}
  \end{center}
\end{table}

Values of c\_READ\_LENGTH, c\_INST\_LENGTH,\_ADDR\_LENGTH and c\_DATA\_LENGTH
can be found/set in \textit{spi\_master\_pkg.vhd}.

\subsection{SPI1}
The SPI1 is a write-read register.\\

Responsible of the set-up of the kind of SPI operation to be performed and the
prescaling for configuring the clock of the SPI interface.
Contents of internal FIFOs can be pushed to be sent, or not, to allow bigger
flexibility to the user (and save power in the case in which we are sending the
same contents over the SPI).

\begin{table}[!htb]
\begin{center}
  \begin{tabular}{| l | c | c | c |}
    \hline
    \textbf{Bits} & \textbf{Field} & \textbf{Meaning} & \textbf{Default}\\
    \hline
    \hline
          0  & \textbf{PUSH\_DATA}  &  PUSH DATA bytes into       & \textbf{'0'}   \\
             &                      &   internal SPI core memory  & \\ 
    \hline
          1  & \textbf{PUSH\_ADDR}  &  PUSH ADDRess bytes into    & \textbf{'0'}   \\
             &                      &   internal SPI core memory  & \\ 
    \hline
          2  & \textbf{PUSH\_INST}  &  PUSH INSTruction bytes into& \textbf{'0'}   \\
             &                      &   internal SPI core memory  & \\ 
    \hline
        5-3  & x                    &  Reserved                   & \textbf{"000"} \\
    \hline
          6  & \textbf{SEND\_DATA}  &  DATA bytes will be sent in & \textbf{'0'}   \\
             &                      &   a write operation         & \\ 
    \hline
          7  & \textbf{SEND\_ADDR}  &  ADDR bytes will be sent in & \textbf{'0'}   \\
             &                      &   a write operation         & \\
    \hline
          8  & \textbf{SEND\_INST}  &  INST bytes will be sent in & \textbf{'0'}   \\
             &                      &   a write operation         & \\
    \hline
          9  & \textbf{SEND\_OP}    &  perform a SEND OPeration   & \textbf{'0'}   \\
    \hline
      11-10  & y                    & Reserved                    & \textbf{"00"}  \\
    \hline
      15-12  & \textbf{CLK\_DIV}    &  CLocK DIVider              & \textbf{X"0"}  \\
    \hline
      31-16  & z                    & Reserved                    & \textbf{X"0000"}\\
    \hline
  \end{tabular}
  \caption{SPI1 register}
  \end{center}
\end{table}

\subsection{SPI2}
The SPI2 register is a read-only register.\\

It tells when a transaction has finished and what has been sent. Due to
configuration checking inside the SPI core, some fields would have been not
send.\\

\begin{table}[!htb]
\begin{center}
  \begin{tabular}{| l | c | c | c |}
    \hline
    \textbf{Bits} & \textbf{Field} & \textbf{Meaning} & \textbf{Default}\\
    \hline
    \hline
    0     & \textbf{SENT\_DATA}   &  DATA was SENT         & \textbf{'0'}   \\ 
    \hline
    1     & \textbf{SENT\_ADDR}   &  ADDRess was SENT      & \textbf{'0'}   \\ 
    \hline
    2     & \textbf{SENT\_INST}   &  INSTruction was SENT  & \textbf{'0'}   \\ 
    \hline
    3     & \textbf{SENT\_OP  }   &  OPeration was SENT    & \textbf{'0'}   \\ 
    \hline
    11-4  & x                     &  Reserved              & \textbf{X"00"} \\ 
    \hline
    15-12 & \textbf{CLK\_DIV}     &  CLocK DIVision        & \textbf{X"0"}  \\ 
    \hline
  \end{tabular}
  \caption{SPI2 register}
  \end{center}
\end{table}

\subsection{SPI3}
The SPI3 register is a read-only register.\\

It holds the data received by the MISO pin.

\begin{table}[!htb]
\begin{center}
  \begin{tabular}{| l | c | c | c |}
    \hline
    \textbf{Bits} & \textbf{Field} & \textbf{Meaning} & \textbf{Default}\\
    \hline
    \hline
    31-0    & \textbf{MOSI\_DATA} & Latest 32 bits received &  \textbf{X"00"}\\
    \hline
  \end{tabular}
  \caption{SPI3 register}
  \end{center}
\end{table}

\pagebreak
\section{Internal memory mapping}
The internal registers map over the wishbone interface is as follows:\\

\begin{table}[hbt]
\begin{center}
  \begin{tabular}{| c | c | c |} 
  \hline 
  \textbf{Address} & \textbf{Register} & \textbf{Access} \\ 
  \hline 
  \hline 
  \textbf{0x0} & \textit{SPI0} & Write-read \\
  \hline 
  \textbf{0x1} & \textit{SPI1} & Write-read \\
  \hline 
  \textbf{0x2} & \textit{SPI2} & Read-only  \\ 
  \hline 
  \textbf{0x3} & \textit{SPI3} & Read-only  \\ 
  \hline 
  \end{tabular} 
\caption{Memory mapping}
\end{center}
\end{table}

\pagebreak

\section{How to use it}

\subsection{Perform an operation over SPI}
It consists on writing the SPI0 register first, and then the SPI1 register.
\textbf{Order must be preserved}.\\

Status of the operation can be followed via SPI2 register. SPI3 register offer
the data read from the MISO line.\\

\subsubsection{SPI0 register}
It should be specified:
\begin{itemize}
   \item Mode of operation (via \textit{CPOL} and \textit{CPHA}).
   \item Number of bytes to write (instruction \textit{BINST},
   address \textit{BADDR} and data \textit{BDATA}) into MOSI line.
   \item Number of bytes to read (\textit{BREAD}) from the MISO line.
\end{itemize}
Those values must be written into the SPI0 register and, then, the same for
SPI1 register.

\subsubsection{SPI1 register}
The following fields must be set up:
\begin{itemize}
\item Which contents of the internal FIFOs (instruction, address and data)
should be loaded into the SPI core to be sent over MOSI line: \textit{PUSH\_INST},
\textit{PUSH\_ADDR} and \textit{PUSH\_DATA}. If not pushed, last pushed value
will be written.
\item Clock divider, \textit{CLK\_DIV}, to be generated the SPI clock frequency from the system clock frequency. 
\item Which fields should be written: \textit{SEND\_INST}, \textit{SEND\_ADDR}
\textit{SEND\_DATA}.
\item Select if a read operation will be carried out: \textit{READ\_MOSI}.
\item Determine that an operation should be consider by the core:
\textit{SEND\_OP}
\end{itemize}
Note that invalid operations will be detected by the core (either they will be
rejected or modified to comply with the HW constraints).

\subsection{SPI2 register}

When a SPI operation has finished, a one clock signal (SENT\_OP bit) is flagged
for one system clock. During this one clock signal, all the fields that have
run in the operation can be checked in \textit{SPI2}.\\

For optimum perfomance, polling of SENT\_OP should be carried out.

\subsection{SPI3 register}

SPI3 has the contents of the MISO read values.\\

It can be read in any moment but operation-consistent information can be
obtained when the SPI operation has finished.


\pagebreak

\appendix
\section{IP core insights}
\subsection{Design structure}

The core is governt by a simple finite state machine, \textit{clk\_fsm}, and a
expansion of one of it states, \textit{spi\_clk\_fsm}.

\subsubsection{clk\_fsm}

The main functionality of clk\_fsm is:
\begin{itemize}
\item To place all the signals of the core to a known default state by means of
a reset state (\textit{R0\_RESET}, in red).
\item To provide the VHDL predifine set-up and hold times of the chip select
line. This functionality is specially important in the case of the hold time to
let some memories to be programmed correctly when continuos writes are
performed into them (\textit{S1\_SETUP} and \textit{S3\_HOLD}, both in grey).
\item To access to SPI slaves (\textit{S2\_SPI\_ACTIVITY}, in golded-yellow).
\end{itemize}

\begin{figure}[!hbt]
   \begin{center}
      \includegraphics[scale=0.75,
      keepaspectratio]{./Figures/clk_fsm.png}
      \caption{clk\_fsm}
   \end{center}
\end{figure}

\subsubsection{spi\_clk\_fsm}

Namely the expansion of clk\_fsm's state \textit{S2\_SPI\_ACTIVITY}, it is
responsible of controlling the writes (including memory prefetching) and reads
of the MOSI and MISO lines, respectively.\\

When clk\_fsm goes into \textit{R0\_RESET} state, spi\_clk\_fsm resets to
\textit{S0\_IDLE} and it is ready to act over the SPI interface. When a valid
instruction is present and clk\_fsm's \textit{S1\_SETUP} has change to
\textit{S2\_SPI\_ACTIVITY}, the refresh of internal FIFO memories is carried
out (according to valid fields to be sent and PUSH\_[x] values in SPI1
register. Then, in the case of write fields the byte to be sent is pulled from
the FIFO (in blue) and subsequently sent. In the case of reads, SPI data is
read and a one-clock byte reception is issued (in blue). After that two states
for clearing up all the values are run.



\begin{figure}[!hbt]
   \begin{center}
      \includegraphics[scale=0.75,
      keepaspectratio]{./Figures/spi_clk_fsm.png}
      \caption{spi\_clk\_fsm}
   \end{center}
\end{figure}

%%\pagebreak
%%\subsection{Verification}
%%
%%\subsection{Footprint}
\end{document}
