Commit 2db61f5b authored by Stefan Tauner's avatar Stefan Tauner
Browse files

Refine user manual's demo section

parent 4d221c34
...@@ -6,20 +6,21 @@ The \ac{TMR} \ac{VGA} demo design is intended to demonstrate the effects of faul ...@@ -6,20 +6,21 @@ The \ac{TMR} \ac{VGA} demo design is intended to demonstrate the effects of faul
A sprite engine draws a sprite of a small airplane on the screen in front A sprite engine draws a sprite of a small airplane on the screen in front
of a blue-red gradient background. The sprite of the airplane is moved across the of a blue-red gradient background. The sprite of the airplane is moved across the
screen in successive frames, changing direction when it reaches any of screen in successive frames, changing direction when it reaches any of
the visible screen borders. A screenshot can be seen in \Cref{fig:tmrvga_screenshot}. the visible screen borders. Screenshots can be seen in \Cref{fig:tmrvga_screenshot}.
The left side shows the error-free case, a stuck-open error in the sprite The left side shows the error-free case, a stuck-open error in the sprite
engine can be seen on the right side. engine can be seen on the right side.
\begin{figure}[htb] \begin{figure}[htb]
\centering \centering
\includegraphics[width=0.8\linewidth]{img/tmrvga_screenshot.jpg} \includegraphics[width=0.8\linewidth]{img/tmrvga_screenshot.jpg}
\caption{\ac{TMR} \ac{VGA} Screenshot} \caption{\ac{TMR} \ac{VGA} Screenshots}
\label{fig:tmrvga_screenshot} \label{fig:tmrvga_screenshot}
\end{figure} \end{figure}
The use case is designated for use with the Cyclone III-based DE0 development The use case is designated for use with the Cyclone III-based DE0 development
board from Terasic\footnote{\url{http://de0.terasic.com.tw/}, visited on August 29,2016} board from Terasic\footnote{\url{http://de0.terasic.com.tw}, visited on August~29, 2016},
or the Zynq-based Zybo\footnote{\url{https://www.xilinx.com/products/boards-and-kits/1-4azfte.html}, visited on August 29, 2016} the Artix~7-based Basys~3\footnote{\url{https://reference.digilentinc.com/reference/programmable-logic/basys-3/start}, visited on April~12, 2017},
or the Zynq~7000-based Zybo\footnote{\url{https://reference.digilentinc.com/reference/programmable-logic/zybo/start}, visited on April~12, 2017},
but is portable to other boards providing a \ac{VGA} connector with little effort. but is portable to other boards providing a \ac{VGA} connector with little effort.
\begin{figure}[htb] \begin{figure}[htb]
...@@ -43,89 +44,137 @@ In a real-world design the states of the redundant units would usually be determ ...@@ -43,89 +44,137 @@ In a real-world design the states of the redundant units would usually be determ
\subsection{Hardware Setup} \subsection{Hardware Setup}
Board setup (DE0): \subsubsection{Digilent Basys 3}
\begin{itemize} \begin{itemize}
\item Connect a 3V3 Serial TTL cable to the DE0: \item Connect the host with the micro USB port (PROG).
This will not only allow programming the FPGA but also transport the UART packets for the run-time communication.
\item Connect a VGA-compatible monitor to the VGA port.
The design generates a 640x480 @ 25Mhz VGA signal.
\item The dip-switch SW0 controls if TMR is enabled (towards the board edge is off).
\item BTNC resets the design when pressed.
\item The four rightmost LEDs above the dip switches (LD0-LD3) show the error detection state:
\begin{itemize} \begin{itemize}
\item Connect \textit{Ground} to any GND pin on GPIO1 (e.g., J5.30) \item LD0 shows if any error has been detected.
\item Connect \textit{TXD (Host-to-Device)} to GPIO1\_D31 (J5.40) \item LD1-3 show which voter (Red, Green, Blue) detected the error.
\item Connect \textit{RXD (Device-to-Host)} to GPIO1\_D30 (J5.39) \end{itemize}
\item Leave \textit{\#RTS} unconnected \end{itemize}
\item Connect \textit{\#CTS} to GND (or leave unconnected if your cable
pulls it down) \subsubsection{Digilent Zybo}
\begin{itemize}
\item Connect a 3V3 Serial TTL cable to the Zybo:
\begin{itemize}
\item Connect \textit{Ground} to PMOD JE5.
\item Connect \textit{TXD (Host-to-Device)} to PMOD JE1.
\item Connect \textit{RXD (Device-to-Host)} to PMOD JE2.
\item Leave \textit{\#RTS} unconnected.
\item Connect \textit{\#CTS} to GND (or leave unconnected if your cable pulls it down).
\item If your cable requires an I/O voltage input (e.g., FTDI TTL-232R-VIP), \item If your cable requires an I/O voltage input (e.g., FTDI TTL-232R-VIP),
connect the correspondig wire to any 3V3 pin on GPIO1 (e.g., J5.29) connect the correspondig wire to PMOD JE6.
\end{itemize} \end{itemize}
\item Connect a VGA-compatible monitor to the VGA port. The design \item Connect a VGA-compatible monitor to the VGA port.
generates a 640x480 \@ 25Mhz VGA signal. The design generates a 640x480 @ 25Mhz VGA signal.
\item The dip-switch SW0 controls if TMR is enabled. \item The dip-switch SW0 controls if TMR is enabled.
\item BUTTON0 resets the design \item BTN0 resets the design when pressed.
\item The green LEDs above the three buttons (LEDG0-LEDG3) show the \item The LEDs above the dip switches (LD0-LD3) show the error detection state:
error detection state:
\begin{itemize} \begin{itemize}
\item LEDG0 shows if any error has been detected \item LD0 shows if any error has been detected.
\item LEDG1-3 show which voter (Red,Green,Blue) detected the error \item LD1-3 show which voter (Red, Green, Blue) detected the error.
\end{itemize} \end{itemize}
\end{itemize} \end{itemize}
Board setup (Zybo): \subsubsection{Terasic DE0}
\begin{itemize} \begin{itemize}
\item Connect a 3V3 Serial TTL cable to the Zybo: \item Connect a 3V3 Serial TTL cable to the DE0:
\begin{itemize} \begin{itemize}
\item Connect \textit{Ground} to PMOD JE5 \item Connect \textit{Ground} to any GND pin on GPIO1 (e.g., J5.30).
\item Connect \textit{TXD (Host-to-Device)} to PMOD JE1 \item Connect \textit{TXD (Host-to-Device)} to GPIO1\_D31 (J5.40).
\item Connect \textit{RXD (Device-to-Host)} to PMOD JE2 \item Connect \textit{RXD (Device-to-Host)} to GPIO1\_D30 (J5.39).
\item Leave \textit{\#RTS} unconnected \item Leave \textit{\#RTS} unconnected.
\item Connect \textit{\#CTS} to GND (or leave unconnected if your cable \item Connect \textit{\#CTS} to GND (or leave unconnected if your cable pulls it down).
pulls it down)
\item If your cable requires an I/O voltage input (e.g., FTDI TTL-232R-VIP), \item If your cable requires an I/O voltage input (e.g., FTDI TTL-232R-VIP),
connect the correspondig wire to PMOD JE6 connect the correspondig wire to any 3V3 pin on GPIO1 (e.g., J5.29).
\end{itemize} \end{itemize}
\item Connect a VGA-compatible monitor to the VGA port. \item Connect a VGA-compatible monitor to the VGA port.
\item The dip-switch SW0 controls if TMR is enabled. The design generates a 640x480 @ 25Mhz VGA signal.
\item BTN0 resets the design when pressed \item The dip-switch SW0 controls if TMR is enabled (towards the board edge is off).
\item The LEDs above the dip switches (LD0-LD3) show the \item BUTTON0 resets the design.
error detection state: \item The green LEDs above the three buttons (LEDG0-LEDG3) show the error detection state:
\begin{itemize} \begin{itemize}
\item LD0 shows if any error has been detected \item LEDG0 shows if any error has been detected.
\item LD1-3 show which voter (Red,Green,Blue) detected the error \item LEDG1-3 show which voter (Red, Green, Blue) detected the error.
\end{itemize} \end{itemize}
\end{itemize} \end{itemize}
\subsection{Work Flow} \subsection{Work Flow}
All paths hereinafter are relative to \texttt{<FIJI ROOT>/docs/demos/tmr\_vga}. Due to the various supported boards there are some important points to consider when following the steps:
\begin{itemize}
\item All paths hereinafter are relative to \texttt{<FIJI ROOT>/docs/demos/tmr\_vga}.
\item Parts of them are also \textbf{board-specific} and targeting the DE0.
They have to be changed for any other board accordingly (\texttt{de0} \textrightarrow{} \texttt{basys3}, \texttt{zybo} etc).
\item Depending on the FPGA vendor there are some important differences.
Most of them are written out explicitly in the P\&R description to distinguish between Altera Quartus and Xilinx Vivado.
Another thing that needs to be changed throughout this tutorial if you are using a Xilinx-based board is the file name suffix of netlists:
Instead of \texttt{.vqm} used by Altera you need to use \texttt{.vm} for Xilinx.
\end{itemize}
To reconstruct the execution of the flow to configure, instrument and synthesize the design with injection logic, the following steps have to be executed.
\subsubsection{Input Netlist}
To reconstruct the execution of the flow to configure, instrument and synthesis the design with injection logic, the following steps have to be executed. The steps hereinafter assume that you have already synthesized a netlist of the original design with Synopsis Synplify.
A suitable Synopsis project and constraint file is provided in \texttt{synp/de0/}.
Synthesizing this with Synplify creates a netlist compatible to our tool (or more specifically to Verilog-Perl).
The resulting file should be located in the \texttt{synp} directory (e.g., synp/de0/de0/spriteflyer\_top.vqm).
\subsubsection{Run setup} \subsubsection{Run setup}
A pre-configured settings file for \ac{FIJI} is located in \texttt{fiji/de0\_test\_1/fiji/fiji.cfg}.
To review the configuration you can open it up in the \ac{FIJI} Setup GUI:
\begin{lstlisting}[style=shell,gobble=8] \begin{lstlisting}[style=shell,gobble=8]
$ perl ../../../bin/fiji_setup.pl -s fiji/de0_test_1/fiji/fiji.cfg \ $ perl ../../../bin/fiji_setup.pl -s fiji/de0_test_1/fiji/fiji.cfg \
-n synp/de0/de0/spriteflyer_top.vqm -n synp/de0/de0/spriteflyer_top.vqm
\end{lstlisting} \end{lstlisting}
\subsubsection{Instrumentation} \subsubsection{Instrumentation}
To apply the configuration and instrument the design run:
\begin{lstlisting}[style=shell,gobble=8] \begin{lstlisting}[style=shell,gobble=8]
$ perl ../../../bin/fiji_instrument.pl -s fiji/de0_test_1/fiji/fiji.cfg \ $ perl ../../../bin/fiji_instrument.pl -s fiji/de0_test_1/fiji/fiji.cfg \
-n synp/de0/de0/spriteflyer_top.vqm \ -n synp/de0/de0/spriteflyer_top.vqm \
-o fiji/de0_test_1/fiji \ -o fiji/de0_test_1/fiji \
-p tmr_vga_demo -p tmr_vga_demo
\end{lstlisting} \end{lstlisting}
\subsubsection{Synthesis using Synplify Pro} \subsubsection{Synthesis using Synplify Pro}
\begin{enumerate} \begin{enumerate}
\item Create a new Synplify project file named 'spriteflyer\_top.prj' in \texttt{fiji/de0\_test\_1/synp} \item Create a new Synplify project file named 'spriteflyer\_top.prj' in \texttt{fiji/de0\_test\_1/synp}
\item Open the project \item Open the project
\item Rename the default implementation to 'de0' and enter the following settings: \item Rename the (default) implementation to \texttt{basys3}, \texttt{de0}, \texttt{zybo}, etc. respectively.
Then configure it with the following settings.
\medskip
Depending on the FPGA vendor you have to select the P\&R tool (in the ``Implementation Results'' tab):
\begin{itemize}
\item \textbf{Altera} select Quartus II (Version 13.0) as P\&R Tool
\item \textbf{Xilinx} tick ``Use Vivado~[\ldots]'' then select \texttt{.vm} as ``Result Format''.
\end{itemize}
\medskip
\textbf{Common for all boards}:
\begin{itemize}
\item ``Implementation Results'' tab: Name of the output file containing the Verilog netlist: \texttt{spriteflyer\_top.v(q)m}
\item ``VHDL'' tab: ``Top Level Entity'': \texttt{fiji\_top}
\end{itemize}
\begin{itemize} \medskip
\item Device: Cyclone III EP3C16-F484-C6 Finally, you have also to set the correct device in the first tab:
\item Output Filename: spriteflyer\_top.vqm \begin{itemize}
\item Quartus Version: 13.0 \item \textbf{Basys~3}: Artix7 XC7A35T-CPG236-1
\item Verilog toplevel module: fiji\_top \item \textbf{DE0}: Cyclone III EP3C16-F484-C6
\end{itemize} \item \textbf{Zybo}: Zynq XC7Z010-CLG400-1
\end{itemize}
\item \item Add the following files to the project:
\begin{plainlisting}[gobble=12] \begin{plainlisting}[gobble=12]
fiji/de0_test_1/fiji/tmr_vga_demo_instrumented.vqm fiji/de0_test_1/fiji/tmr_vga_demo_instrumented.vqm
fiji/de0_test_1/fiji/tmr_vga_demo_config_pkg.vhd fiji/de0_test_1/fiji/tmr_vga_demo_config_pkg.vhd
...@@ -134,13 +183,15 @@ To reconstruct the execution of the flow to configure, instrument and synthesis ...@@ -134,13 +183,15 @@ To reconstruct the execution of the flow to configure, instrument and synthesis
fiji/de0_test_1/synp/spriteflyer_top.fdc fiji/de0_test_1/synp/spriteflyer_top.fdc
<FIJI PUBLIC ROOT>/hw/rtl/*.vhd <FIJI PUBLIC ROOT>/hw/rtl/*.vhd
\end{plainlisting} \end{plainlisting}
The constraints have already been entered for this demo. The constraints have already been entered for this demo in the \texttt{.fdc} files above.
In a ``real'' flow, they have to be manually transferred from In a ``real'' flow, they have to be manually transferred from the original Synplify project.
the original Synplify project
\item Run \keystroke{F8} \item Synthesize (\keystroke{F8})
\end{enumerate} \end{enumerate}
\subsubsection{Place-and-Route using Quartus II 13.0}
\subsubsection{Place-and-Route for Altera FPGAs}
To create the final bitstream for Altera FPGAs the instrumented netlist needs to be placed and routed with Quartus~II as follows.
\begin{enumerate} \begin{enumerate}
\item Copy the following files into the \texttt{fiji/de0\_test\_1/quartus} directory: \item Copy the following files into the \texttt{fiji/de0\_test\_1/quartus} directory:
...@@ -149,13 +200,14 @@ To reconstruct the execution of the flow to configure, instrument and synthesis ...@@ -149,13 +200,14 @@ To reconstruct the execution of the flow to configure, instrument and synthesis
synp/de0/de0/spriteflyer_top_p_sprite_rom_s_spritmif1.hex synp/de0/de0/spriteflyer_top_p_sprite_rom_s_spritmif1.hex
synp/de0/de0/spriteflyer_top_p_sprite_rom_s_spritmif2.hex synp/de0/de0/spriteflyer_top_p_sprite_rom_s_spritmif2.hex
\end{plainlisting} \end{plainlisting}
\item Create a new project named 'de0\_test\_1.qpf'
\item Create a new project (e.g., \texttt{fiji\_de0.qpf} in \texttt{fiji/de0\_test\_1/quartus}
Set Cyclone III - EP3C16-F484-C6 as device Set Cyclone III - EP3C16-F484-C6 as device
\item Add the following files to the project \item Add the following files to the project
\begin{plainlisting}[gobble=12] \begin{plainlisting}[gobble=12]
fiji/de0_test_1/fiji/tmr_vga_demo_instrumented.vqm fiji/de0_test_1/fiji/fiji\_top.vqm
fiji/de0_test_1/fiji/tmr_vga_demo_constraints.quartus.qsf fiji/de0_test_1/fiji/tmr_vga_demo_constraints.quartus.qsf
fiji/de0_test_1/quartus/fiji_top.sdc fiji/de0_test_1/quartus/fiji_top.sdc
\end{plainlisting} \end{plainlisting}
...@@ -177,21 +229,62 @@ To reconstruct the execution of the flow to configure, instrument and synthesis ...@@ -177,21 +229,62 @@ To reconstruct the execution of the flow to configure, instrument and synthesis
\end{enumerate} \end{enumerate}
\subsubsection{Place-and-Route for Xilinx FPGAs}
To create the final bitstream for Xilinx FPGAs the instrumented netlist needs to be placed and routed with Vivado as follows.
Replace `basys3` with your board name where applicable.
\begin{enumerate}
\item Start Vivado and create a new project (e.g., \texttt{fiji\_basys3}) in \texttt{fiji/basys3\_test\_1/vivado/}.
\item Select ``Post-synthesis Project''.
\item Add the instrumented netlist as source to the project:
\begin{plainlisting}[gobble=12]
fiji/basys3_test_1/synp/basys3/spriteflyer_top.vm
\end{plainlisting}
\item Add the following pre-defined constraint files:
\begin{plainlisting}[gobble=12]
boards/pins_basys3.xdc
fiji/basys3_test_1/vivado/pins_fiji.xdc
fiji/basys3_test_1/vivado/clock.xdc
\end{plainlisting}
The clock and pin constraints have already been entered for this demo.
In a ``real'' project, you would have to manually enter them in Vivado.
\item Set the respective FPGA device:
\begin{itemize}
\item Basys~3: \texttt{xc7a35tcpg236-1}
\item Zybo: \texttt{xc7z010clg400-1}
\end{itemize}
\item Set \texttt{fiji\_top} as toplevel module.
\item Execute ``Generate Bitstream'' (in the ``Flow Navigator'' on the left on the bottom).
\end{enumerate}
\subsection{Runtime Fault Injection} \subsection{Runtime Fault Injection}
\begin{enumerate} \begin{enumerate}
\item Download the FPGA bitstream via Quartus Downloader \item Download the FPGA bitstream with the FPGA vendor tool
\item Run the \ac{FIJIEE} GUI \item Run the \ac{FIJIEE} GUI
% \begin{lstlisting}[style=shell,gobble=12]
% $ perl ../../../bin/fiji_ee_gui.pl -s fiji/de0_test_1/fiji/tmr_vga_demo_download.cfg \
% -t fiji/de0_test_1/fiji/tmr_vga_demo_test.tst
% \end{lstlisting}
\begin{lstlisting}[style=shell,gobble=12] \begin{lstlisting}[style=shell,gobble=12]
$ perl ../../../bin/fiji_ee_gui.pl -s fiji/de0_test_1/fiji/tmr_vga_demo_download.cfg \ $ perl ../../../bin/fiji_ee_gui.pl -s fiji/de0_test_1/fiji/tmr_vga_demo_download.cfg
-t fiji/de0_test_1/fiji/tmr_vga_demo_test.tst
\end{lstlisting} \end{lstlisting}
\item Execute tests: \item Execute tests at will
\begin {itemize} % \item Execute tests:
\item Pre-defined sequence in \texttt{fiji/de0\_test\_1/fiji/tmr\_vga\_demo\_test.tst} % \begin {itemize}
\item Manual tests % \item Pre-defined sequence in \texttt{fiji/de0\_test\_1/fiji/tmr\_vga\_demo\_test.tst}
\item Random tests % \item Manual tests
\end {itemize} % \item Random tests
% \end {itemize}
\end{enumerate} \end{enumerate}
When the \emph{\ac{TMR} Enable} switch is in ``0'' position, the output from When the \emph{\ac{TMR} Enable} switch is in ``0'' position, the output from
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment