From 06adc72ad00b288fd509a778db0e1aec65831099 Mon Sep 17 00:00:00 2001
From: Theodor Stana <t.stana@cern.ch>
Date: Fri, 28 Mar 2014 18:06:43 +0100
Subject: [PATCH] doc: Update wb_i2c_bridge and add colored tables to other
modules
Signed-off-by: Theodor Stana <t.stana@cern.ch>
---
doc/gc_fsm_watchdog/gc_fsm_watchdog.tex | 23 ++---
doc/gc_glitch_filt/gc_glitch_filt.tex | 5 +-
doc/gc_i2c_slave/gc_i2c_slave.tex | 8 +-
doc/wb_i2c_bridge/wb_i2c_bridge.tex | 101 +++++++++++++---------
doc/wb_xil_multiboot/multiboot-regs.tex | 2 +-
doc/wb_xil_multiboot/wb_xil_multiboot.tex | 24 ++---
6 files changed, 97 insertions(+), 66 deletions(-)
diff --git a/doc/gc_fsm_watchdog/gc_fsm_watchdog.tex b/doc/gc_fsm_watchdog/gc_fsm_watchdog.tex
index 4c9a8631..72d984d1 100644
--- a/doc/gc_fsm_watchdog/gc_fsm_watchdog.tex
+++ b/doc/gc_fsm_watchdog/gc_fsm_watchdog.tex
@@ -6,7 +6,8 @@
\usepackage{graphicx}
\usepackage{multirow}
-\usepackage{color}
+% Color package
+\usepackage[usenames,dvipsnames,table]{xcolor}
\usepackage[toc,page]{appendix}
@@ -36,6 +37,7 @@
\centerline
{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l c p{.6\textwidth}}
\hline
\multicolumn{1}{c}{\textbf{Date}} & \multicolumn{1}{c}{\textbf{Version}} & \multicolumn{1}{c}{\textbf{Change}} \\
@@ -87,20 +89,21 @@ in the HDL code to reset the FSM.
The ports of the \textit{gc\_fsm\_watchdog} module are shown in Table~\ref{tbl:ports}.
\begin{table}[h]
- \caption{Ports of \textit{vbcp\_wb} module}
+ \caption{Ports of \textit{gc\_fsm\_watchdog} module}
\label{tbl:ports}
\centerline
{
- \begin{tabular}{l c p{.6\textwidth}}
+ \rowcolors{2}{white}{gray!25}
+ \begin{tabular}{l p{.8\textwidth}}
\hline
- \multicolumn{1}{c}{\textbf{Port}} & \textbf{Size} & \multicolumn{1}{c}{\textbf{Description}} \\
+ \multicolumn{1}{c}{\textbf{Name}} & \multicolumn{1}{c}{\textbf{Description}} \\
\hline
- clk\_i & 1 & Clock input \\
- rst\_n\_i & 1 & Active-low reset input \\
- wdt\_rst\_i & 1 & Active-high reset input from the FSM to the watchdog timer \newline
- Synchronous to \textit{clk\_i}\\
- fsm\_rst\_o & 1 & Active-high reset output from the watchdog timer to the FSM \newline
- Synchronous to \textit{clk\_i}\\ \\
+ clk\_i & Clock input \\
+ rst\_n\_i & Active-low reset input \\
+ wdt\_rst\_i & Active-high reset input from the FSM to the watchdog timer \newline
+ Synchronous to \textit{clk\_i}\\
+ fsm\_rst\_o & Active-high reset output from the watchdog timer to the FSM \newline
+ Synchronous to \textit{clk\_i}\\
\hline
\end{tabular}
}
diff --git a/doc/gc_glitch_filt/gc_glitch_filt.tex b/doc/gc_glitch_filt/gc_glitch_filt.tex
index 2e372d4f..217125ff 100644
--- a/doc/gc_glitch_filt/gc_glitch_filt.tex
+++ b/doc/gc_glitch_filt/gc_glitch_filt.tex
@@ -4,7 +4,7 @@
\documentclass[a4paper,11pt]{article}
% Color package
-\usepackage[usenames,dvipsnames]{color}
+\usepackage[usenames,dvipsnames,table]{xcolor}
% Hyperrefs
\usepackage[
@@ -45,6 +45,7 @@
\centerline
{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l c p{.6\textwidth}}
\hline
\multicolumn{1}{c}{\textbf{Date}} & \multicolumn{1}{c}{\textbf{Version}} & \multicolumn{1}{c}{\textbf{Change}} \\
@@ -116,6 +117,7 @@ clock cycles later.
\label{tbl:ports}
\centerline
{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l p{.7\textwidth}}
\hline
\multicolumn{1}{c}{\textbf{Name}} & \multicolumn{1}{c}{\textbf{Description}} \\
@@ -124,6 +126,7 @@ clock cycles later.
1 -- glitches narrower than 1 \textit{clk\_i} cycle are filtered \newline
2 -- glitches narrower than 2 \textit{clk\_i} cycles are filtered \newline
etc.\\
+ \hline
clk\_i & Clock input \\
rst\_n\_i & Active-low reset input \\
dat\_i & Data input (should be synchronous to \textit{clk\_i})\\
diff --git a/doc/gc_i2c_slave/gc_i2c_slave.tex b/doc/gc_i2c_slave/gc_i2c_slave.tex
index c38c0603..e21ac409 100644
--- a/doc/gc_i2c_slave/gc_i2c_slave.tex
+++ b/doc/gc_i2c_slave/gc_i2c_slave.tex
@@ -4,7 +4,7 @@
\documentclass[a4paper,11pt]{article}
% Color package
-\usepackage[usenames,dvipsnames]{color}
+\usepackage[usenames,dvipsnames,table]{xcolor}
% Hyperrefs
\usepackage[
@@ -45,6 +45,7 @@
\centerline
{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l c p{.6\textwidth}}
\hline
\multicolumn{1}{c}{\textbf{Date}} & \multicolumn{1}{c}{\textbf{Version}} & \multicolumn{1}{c}{\textbf{Change}} \\
@@ -163,6 +164,7 @@ To instantiate a tri-state buffer in VHDL:
\label{tbl:ports}
\centerline
{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l p{.8\textwidth}}
\hline
\multicolumn{1}{c}{\textbf{Name}} & \multicolumn{1}{c}{\textbf{Description}} \\
@@ -171,6 +173,7 @@ To instantiate a tri-state buffer in VHDL:
1 -- glitches narrower than 1 \textit{clk\_i} cycle are filtered \newline
2 -- glitches narrower than 2 \textit{clk\_i} cycles are filtered \newline
etc.\\
+ \hline
clk\_i & Clock input \\
rst\_n\_i & Active-low reset input \\
scl\_i & SCL line input \\
@@ -391,6 +394,8 @@ Figure~\ref{fig:fsm-and-scl}.
\label{fig:fsm-and-scl}
\end{figure}
+{
+\rowcolors{2}{white}{gray!25}
\begin{longtable}{l p{.7\textwidth}}
\caption{The states of the \textit{gc\_i2c\_slave} FSM}
\label{tbl:fsm} \\
@@ -425,6 +430,7 @@ Figure~\ref{fig:fsm-and-scl}.
\textit{WR\_ACK} & Read ACK bit sent by master. If '0', go back to \textit{WR} state, otherwise
go to \textit{IDLE} state. \\
\end{longtable}
+}
%------------------------------------------------------------------------------
\subsection{Output control}
diff --git a/doc/wb_i2c_bridge/wb_i2c_bridge.tex b/doc/wb_i2c_bridge/wb_i2c_bridge.tex
index 9dc62e15..6d9c81b6 100644
--- a/doc/wb_i2c_bridge/wb_i2c_bridge.tex
+++ b/doc/wb_i2c_bridge/wb_i2c_bridge.tex
@@ -4,7 +4,7 @@
\documentclass[a4paper,11pt]{article}
% Color package
-\usepackage[usenames,dvipsnames]{color}
+\usepackage[usenames,dvipsnames,table]{xcolor}
% Appendix package
\usepackage[toc,page]{appendix}
@@ -49,6 +49,7 @@
\centerline
{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l c p{.6\textwidth}}
\hline
\multicolumn{1}{c}{\textbf{Date}} & \multicolumn{1}{c}{\textbf{Version}} & \multicolumn{1}{c}{\textbf{Change}} \\
@@ -59,7 +60,8 @@
changes in protocol \\
29-10-2013 & 0.04 & Changed PDF link colors \\
18-12-2013 & 1.00 & Finite version with watchdog timer and robust communication \\
- 12-02-2014 & 1.01 & Removed SIM_WB_TRANSFER state in FSM \\
+ 12-02-2014 & 1.01 & Removed SIM\_WB\_TRANSFER state from FSM \\
+ 28-03-2014 & 1.02 & Added generic for FSM watchdog timeout value \\
\hline
\end{tabular}
}
@@ -126,40 +128,43 @@ Figure~\ref{fig:i2c-ports}; Wishbone slaves should be connected to the
Wishbone master interface ports, prefixed with \textit{wbm}.
\begin{table}[hbtp]
- \caption{Ports of \textit{wb\_i2c\_bridge} module}
+ \caption{Ports and generics of \textit{wb\_i2c\_bridge} module}
\label{tbl:ports}
\centerline
{
- \begin{tabular}{l c p{.6\textwidth}}
+ \rowcolors{2}{white}{gray!25}
+ \begin{tabular}{l p{.8\textwidth}}
\hline
- \multicolumn{1}{c}{\textbf{Port}} & \textbf{Size} & \multicolumn{1}{c}{\textbf{Description}} \\
+ \multicolumn{1}{c}{\textbf{Name}} & \multicolumn{1}{c}{\textbf{Description}} \\
\hline
- clk\_i & 1 & Clock input \\
- rst\_n\_i & 1 & Active-low reset input \\
- sda\_en\_o & 1 & SDA line output tri-state enable \\
- sda\_i & 1 & SDA line input \\
- sda\_o & 1 & SDA line output \\
- scl\_en\_o & 1 & SCL line tri-state enable \\
- scl\_i & 1 & SCL line input \\
- scl\_o & 1 & SCL line output \\
- i2c\_addr\_i & 7 & I$^2$C slave address on ELMA I$^2$C bus \\
- tip\_o & 1 & Transfer In Progress \newline
- '1' -- I$^2$C address sent by SysMon matches that of the I$^2$C slave \newline
- '0' -- after transfer has completed and I$^2$C slave is idle \\
- err\_p\_o & 1 & Error bit, high for one \textit{clk\_i} cycle when the Wishbone address
- the SysMon tries to access is invalid \\
- wdto\_p\_o & 1 & FSM watchdog timer time-out, high for one \textit{clk\_i} cycle when
- the FSM watchdog has timed-out \\
- wbm\_stb\_o & 1 & Wishbone data strobe output \\
- wbm\_cyc\_o & 1 & Wishbone valid cycle output \\
- wbm\_sel\_o & 4 & Wishbone byte select output \\
- wbm\_we\_o & 1 & Wishbone write enable output \\
- wbm\_dat\_i & 32 & Wishbone data input (to master) \\
- wbm\_dat\_o & 32 & Wishbone data output (from master) \\
- wbm\_adr\_o & 32 & Wishbone address output \\
- wbm\_ack\_i & 1 & Wishbone acknowledge signal input \\
- wbm\_rty\_i & 1 & Wishbone retry signal input \\
- wbm\_err\_i & 1 & Wishbone error signal input \\
+ g\_fsm\_wdt & Timeout value (in \textit{clk\_i} cycles) for the FSM watchdog timer \\
+ \hline
+ clk\_i & Clock input \\
+ rst\_n\_i & Active-low reset input \\
+ sda\_en\_o & SDA line output tri-state enable \\
+ sda\_i & SDA line input \\
+ sda\_o & SDA line output \\
+ scl\_en\_o & SCL line tri-state enable \\
+ scl\_i & SCL line input \\
+ scl\_o & SCL line output \\
+ i2c\_addr\_i & I$^2$C slave address on ELMA I$^2$C bus \\
+ tip\_o & Transfer In Progress \newline
+ '1' -- I$^2$C address sent by SysMon matches that of the I$^2$C slave \newline
+ '0' -- after transfer has completed and I$^2$C slave is idle \\
+ err\_p\_o & Error bit, high for one \textit{clk\_i} cycle when the Wishbone address
+ the SysMon tries to access is invalid \\
+ wdto\_p\_o & FSM watchdog timer time-out, high for one \textit{clk\_i} cycle when
+ the FSM watchdog has timed-out \\
+ wbm\_stb\_o & Wishbone data strobe output \\
+ wbm\_cyc\_o & Wishbone valid cycle output \\
+ wbm\_sel\_o & Wishbone byte select output \\
+ wbm\_we\_o & Wishbone write enable output \\
+ wbm\_dat\_i & Wishbone data input (to master) \\
+ wbm\_dat\_o & Wishbone data output (from master) \\
+ wbm\_adr\_o & Wishbone address output \\
+ wbm\_ack\_i & Wishbone acknowledge signal input \\
+ wbm\_rty\_i & Wishbone retry signal input \\
+ wbm\_err\_i & Wishbone error signal input \\
\hline
\end{tabular}
}
@@ -296,6 +301,7 @@ shown in Table~\ref{tbl:cmds}.
\label{tbl:cmds}
\centerline
{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l p{.6\textwidth}}
\hline
\multicolumn{1}{c}{\textbf{Command}} & \multicolumn{1}{c}{\textbf{Description}} \\
@@ -359,6 +365,7 @@ is writing and the \textit{wb\_i2c\_bridge} is reading.
\label{tbl:fsm}
\centerline
{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l p{.7\textwidth}}
\hline
\multicolumn{1}{c}{\textbf{State}} & \multicolumn{1}{c}{\textbf{Description}} \\
@@ -429,7 +436,7 @@ state, setting the \textit{err\_p\_o} output for one \textit{clk\_i} cycle.
The design also contains an FSM watchdog component, which resets the main FSM
in case of errors in communication. The watchdog timeout value is configured
-via the \textit{g\_wdt\_max} generic and can be calculated as outlined in
+via the \textit{g\_fsm\_wdt} generic and can be calculated as outlined in
Appendix~\ref{app:wdto-calc}.
%==============================================================================
@@ -445,6 +452,7 @@ on the Spartan-6 XC6SLX45T are shown in Table~\ref{tbl:synth-res}.
\caption{Synthesis results}
\label{tbl:synth-res}
\centerline{
+ \rowcolors{2}{white}{gray!25}
\begin{tabular}{l c c c}
\hline
\multicolumn{1}{c}{\textbf{Resource}} & \textbf{Used} & \textbf{Available} & \textbf{\%} \\
@@ -469,20 +477,18 @@ on the Spartan-6 XC6SLX45T are shown in Table~\ref{tbl:synth-res}.
In order to calculate the maximum watchdog timeout value, the following procedure
should be utilized.
-First, the frequency on the I$^2$C communication in ELMA crates is 100~kHz. One
-I$^2$C byte transfer always consists in 9 bits (eight bits for data plus one for
-acknowledgement). Therefore, one I$^2$C byte is transferred within 90~$\mu$s.
-
-To account for start and stop conditions and to allow for frequency changes on
-the bus, one can consider one I$^2$C byte as 10 bits, therefore one I$^2$C
-transfer can be considered to take 10~$\mu$s to complete.
+First, one should consider the bit period on the I$^2$C transfer, $T_{bit}$. One I$^2$C
+byte transfer consists of 9 bits (eight data bits plus one ACK). To account for start
+and stop conditions and to allow for frequency changes on the bus, one can consider
+one I$^2$C byte as 10 bits. Therefore, one I$^2$C transfer can be considered to take
+10*$T_{bit}$ to complete.
Now, taking this into account and the period of the \textit{clk\_i} input,
$T_{clk\_i}$, the number of clock cycles needed to complete one I$^2$C byte transfer
can be calculated as:
\begin{equation}
-N_{byte} = \frac{10 {\mu}s}{T_{clk\_i}}
+N_{clocks} = \frac{10*T_{bit}}{T_{clk\_i}}
\end{equation}
Within the ELMA crates, a maximum of 35 bytes can be sent through I$^2$C. This
@@ -493,9 +499,22 @@ maximum watchdog timeout value to be the time needed to send 40 bytes via I$^2$C
on the bus:
\begin{equation}
-g\_wdt\_max = 40 * N_{byte} = 40 * \frac{10 {\mu}s}{T_{clk\_i}}
+g\_fsm\_wdt = 40 * N_{clocks} = 40 * \frac{10*T_{bit}}{T_{clk\_i}}
+\end{equation}
+
+It is good practice to increase this value even further, to account for changes
+in bit widths, etc.
+
+For example, in converter board designs, where $T_{clk} = 50ns$, the
+\textit{g\_fsm\_wdt} value was calculated based on $T_{bit} = 30{\mu}s$.
+The final value was doubled to account for potential changes in the bit period:
+
+\begin{equation}
+g\_fsm\_wdt = 2 * \left( 40 * \frac{10*30{\mu}s}{50ns} \right) = 2 * 240000 = 480000
\end{equation}
+This results in that the FSM watchdog would time out in 24~ms.
+
\end{appendices}
%==============================================================================
diff --git a/doc/wb_xil_multiboot/multiboot-regs.tex b/doc/wb_xil_multiboot/multiboot-regs.tex
index 289e15e0..c2a7762a 100644
--- a/doc/wb_xil_multiboot/multiboot-regs.tex
+++ b/doc/wb_xil_multiboot/multiboot-regs.tex
@@ -5,7 +5,7 @@
\rowcolors{2}{white}{gray!25}
\begin{longtable}{l l l p{.5\textwidth}}
\hline
-\textbf{Offset} & \textbf{Default} & \textbf{Name}
+\textbf{Offset} & \textbf{Reset} & \textbf{Name}
& \textbf{Description} \\
\hline
\endfirsthead
diff --git a/doc/wb_xil_multiboot/wb_xil_multiboot.tex b/doc/wb_xil_multiboot/wb_xil_multiboot.tex
index 1672bcb1..40f03b3b 100644
--- a/doc/wb_xil_multiboot/wb_xil_multiboot.tex
+++ b/doc/wb_xil_multiboot/wb_xil_multiboot.tex
@@ -175,18 +175,18 @@ connected directly to the FPGA output ports connected to the flash chip.
\centerline
{
\rowcolors{2}{white}{gray!25}
- \begin{tabular}{l c p{.6\textwidth}}
- \hline
- \multicolumn{1}{c}{\textbf{Port}} & \textbf{Size} & \multicolumn{1}{c}{\textbf{Description}} \\
- \hline
- clk\_i & 1 & Clock input (max. 20~MHz) \\
- rst\_n\_i & 1 & Active-low reset input \\
- wbs\_i & & Wishbone slave interface inputs \\
- wbs\_o & & Wishbone slave interface outputs \\
- spi\_cs\_n\_o & 1 & Active-low chip select output \\
- spi\_sclk\_o & 1 & SPI clock output \\
- spi\_mosi\_o & 1 & SPI data output line (Master Out, Serial In) \\
- spi\_miso\_i & 1 & SPI data input line (Master In, Serial Out) \\
+ \begin{tabular}{l p{.6\textwidth}}
+ \hline
+ \multicolumn{1}{c}{\textbf{Port}} & \multicolumn{1}{c}{\textbf{Description}} \\
+ \hline
+ clk\_i & Clock input (max. 20~MHz) \\
+ rst\_n\_i & Active-low reset input \\
+ wbs\_i & Wishbone slave interface inputs \\
+ wbs\_o & Wishbone slave interface outputs \\
+ spi\_cs\_n\_o & Active-low chip select output \\
+ spi\_sclk\_o & SPI clock output \\
+ spi\_mosi\_o & SPI data output line (Master Out, Serial In) \\
+ spi\_miso\_i & SPI data input line (Master In, Serial Out) \\
\hline
\end{tabular}
}
--
GitLab