Commit a6dbaee1 authored by Stefan Tauner's avatar Stefan Tauner
Browse files

UM: add forefword and refine Yosys section

parent 30434746
\section{Introduction}
\section*{Foreword}
\addcontentsline{toc}{section}{\protect\numberline{}Foreword}%
The target audience of this documents are hardware and test engineers that want to evaluate or use the \ac{FIJI} suite.
Some technical details that are supposedly irrelevant to ordinary users are omitted on purpose and can be looked up in the accompanying \hyperref[TRM:first_page]{\ac*{TRM}}.
In \cref{sec:intro} an overview of \ac{FIJI}, its features and the applicable tool flow is given.
\Cref{sec:installation} show what's needed to install and run \ac{FIJI}.
More details about the flow and resulting limitations follow in \cref{sec:flow}.
Afterwards, \Cref{sec:setup,sec:instrument,sec:implementation,sec:runtime} explain the related tools and required user inputs of the four main steps of the flow respectively.
The last two chapters deal with the demonstration designs and guide the user through their setup.
\section{Introduction}
\label{sec:intro}
The \ac{FIJI} suite provides a tool flow for
performing fault injection tests on chip designs in an FPGA-based environment.
In contrast to fault injection tests by modification of the \ac{RTL} source,
......
\section{Installation}
\label{sec:installation}
\subsection{Prerequisites}
......@@ -143,7 +144,7 @@ There is currently a bug in the 64-bit version of the Perl libraries used to acc
\subsection{Repository Contents}
Since \ac{FIJI} is written in Perl there is no need (and no proposed way) to install it onto a system.
Simply checking out the source code repository and loading the respective scripts in a Perl interpreter should be enough to us it.
Simply checking out the source code repository and loading the respective scripts in a Perl interpreter should be enough to use it.
To help you navigate within the repository the directory structure is shown in \Cref{fig:fijidir} and explained below.
All source code to be executed by the user on a host PC including customized Perl libraries resides in \texttt{bin}.
......
\section{Instrumentation}
\label{sec:instrument}
The \textit{\ac{FIJI} Instrumentation} tool reads in the original Verilog
netlist and the configuration file edited using the \textit{\ac{FIJI} Setup}
......
\section{Implementation}
\label{sec:implementation}
\subsection{Synthesis}
\label{sec:Synthesis}
......
\section{Demo: TMR VGA}
\section{TMR VGA Demonstration}
\subsection{Use Case}
The \ac{TMR} \ac{VGA} demo design is intended to demonstrate the effects of fault injection in an TMR
......
\section{Yosys Demo}
\section{Yosys Demonstration with \texttt{tinyvga}}
Another demo design was implemented in Verilog in order todemonstrate the
interoperability with the open-source synthesis framework Yosys~\footnote{http://www.clifford.at/yosys/,~visited on September 14, 2017}
and the IceStorm toolchain~\footnote{http://www.clifford.at/icestorm/,~visited on September 14, 2017}.
The target board for this design is the \emph{HX8K Breakout Board}~\footnote{http://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx,~visited on September 14, 2017}
Another demo design was implemented in Verilog in order to demonstrate the
interoperability with the open-source synthesis framework Yosys\footnote{\url{http://www.clifford.at/yosys/},~visited on September 14, 2017}
and the IceStorm toolchain\footnote{\url{http://www.clifford.at/icestorm/},~visited on September 14, 2017}.
The target board for this design is the \emph{HX8K Breakout Board}\footnote{\url{http://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx},~visited on September 14, 2017}
offered by Lattice Semiconductor Corp. Additionally, a VGA DAC extension
board such as the XESS StickIt VGA module~\footnote{http://www.xess.com/shop/product/stickit-vga/,~visited on September 14, 2017} is needed.
board such as the XESS StickIt VGA module\footnote{\url{http://www.xess.com/shop/product/stickit-vga/},~visited on September 14, 2017} is needed.
The design generates SVGA 800x600 output with 36~MHz pixel clock generated
by an iCE40 PLL from the 12~MHz on-board oscillator. It moves the content
The design generates SVGA ($800\times600$ pixels, $3\times4$ bits of color) output with 36\;MHz pixel clock generated
by an iCE40 PLL from the 12\;MHz on-board oscillator. It moves the content
of a BRAM in a circular motion on the screen. On the 8 on-board LEDs the
current state of the 8-bit frame counter is shown.
\subsection{Hardware Setup}
\begin{minipage}[h]{\linewidth}
\begin{wrapfigure}{r}{0.4\textwidth}
\centering
\begin{minipage}{0.45\linewidth}
FIJI uses the FTDI chip on the breakout board to communicate with the
fault injection logic.
The VGA extension board shall be connected to
the 40 pin extension header as shown in Figure~\ref{fig:hx8k_connections}.
The pin connections are also documented in the physical constraint files
for the initial and the instrumented implementations.
\end{minipage}
\hspace{0.05\linewidth}
\begin{minipage}{0.45\linewidth}
\begin{figure}[H]
\centering
\includegraphics[height=20em]{img/hx8k_j2.pdf}
\vspace{-9ex}
\includegraphics[height=15em]{img/hx8k_j2.pdf}
\caption{HX8K Connections}
\label{fig:hx8k_connections}
\end{figure}
\end{minipage}
\end{minipage}
\vspace{-9ex}
\end{wrapfigure}
\subsection{Software Setup}
\ac{FIJI} uses the FTDI chip on the breakout board that tunnels UART frames over USB to communicate with the fault injection logic.
The USB connection also provides power for the device.
The Yosys Demo requires a Linux system with the \texttt{yosys}, \texttt{arachne-pnr},
and the IceStorm binaries (\texttt{icepack}, \ldots) in the system's execution path.
The entire instrumentation process is directed by GNU make.
The VGA extension board shall be connected to
the 40 pin extension header as shown in \Cref{fig:hx8k_connections}.
The pin connections are also documented in the physical constraint files for the initial (\texttt{tinyvga.pcf}) and the instrumented implementations (\texttt{tinyvga\_fiji.pcf}) respectively.
\subsection{Software Setup}
As Yosys does not support VHDL as an input language, Synplify is
required to synthesize the FIJI logic and the wrapper. The original synthesis
As Yosys does not support VHDL as an input language, thus Synplify is
required to synthesize the \ac{FIJI} logic and the wrapper. The original synthesis
step, the entire netlist instrumentation process, as well as the final
synthesis step combining the wrapper and the instrumented netlist, is handled
by Yosys.
The Yosys demonstration requires a Linux system with the \texttt{yosys}, \texttt{arachne-pnr}, and the IceStorm binaries (\texttt{icepack}, \ldots) in the system's execution path.
The entire instrumentation process is directed by GNU make.
Other Unix-like systems such as macOS might work as well but were not tested.
Furthermore, a \texttt{FIJI\_ROOT} environment variable shall point to the
root directory where FIJI was cloned from the git repository.
root directory where \ac{FIJI} was cloned from the git repository.
\subsection{Executing the Demo Flow}
......@@ -57,51 +51,54 @@ The entire instrumentation process is executed by two Makefiles (to be
executed in that order):
\begin{enumerate}
\item The initial synthesis step as well as the FIJI Setup and the
FIJI Instrument tool are executed by the Makfile found in
\item The initial synthesis step as well as the \ac{FIJI} Setup and the
\ac{FIJI} Instrument tool are executed by the Makfile found in
\texttt{docs/demos/tinyvga/impl/original/}. Run
\begin{lstlisting}[style=shell,gobble=12]
$ make fiji-instrument
\end{lstlisting}
to synthesize the \ac{RTL} design to a Verilog netlist, call FIJI Setup,
and finally instrument the netlist as required. A FIJI configuration
for some faults has already been provided. If necessary, select the
correct nets/drivers (other Yosys versions might generate a differing
netlist). The optional target \texttt{prog} generates a bitstream for the original design and
to synthesize the \ac{RTL} design to a Verilog netlist, call \ac{FIJI} Setup,
and finally instrument the netlist as required. A \ac{FIJI} configuration
for some faults has already been provided. Select the
correct nets/drivers, if necessary (e.g., in case the Yosys version used generates an incompatible
netlist). The optional Makefile target \texttt{prog} generates a bitstream for the original design and
downloads it to a connected HX8K breakout board.
\item The second synthesis step, as well as run-time fault injection is
executed by the Makefile found in the directory \texttt{docs/demos/tinyvga/impl/instrumented/}.
To download the instrumented design to a connected board and launch FIJI EE
To download the instrumented design to a connected board and launch \ac{FIJIEE}
subsequently, execute
\begin{lstlisting}[style=shell,gobble=12]
$ make prog && make fiji-launch
\end{lstlisting}
in this directory. This Makefile automatically synthesizes
in this directory. This automatically synthesizes
the VHDL parts to a netlist using Synplify (the command and
options are defined in this file), combines the FIJI logic and
the instrumented netlist using Yosys, and finally generates
options are defined in the Makefile), combines the \ac{FIJI} logic and
the instrumented netlist using Yosys, and generates
a bitstream for the HX8K device using the IceStorm tools.
Eventually it downloads the instrumented design and the second commands launches the \ac{FIJIEE} GUI.
\end{enumerate}
\subsection{Run-Time Fault Injection}
The provided FIJI configuration instruments the MSBs of the three
VGA color signals, as well as the row and column addresses for the
The provided \ac{FIJI} configuration instruments the most significant bits of the three
\ac{VGA} color signals, as well as the row and column addresses for the
image source on-chip RAM.
Once the design is downloaded and the FIJI EE GUI is launched, the following
Once the design is downloaded and the \ac{FIJIEE} GUI is launched, the following
things may be done:
\begin{enumerate}
\item Configure the correct serial device to communicate with the
FIJI hardware. A udev rule that symlinks the HX8K board to
\texttt{/dev/ttyHX8K} may be useful.
\item Configure the correct serial device to communicate with the \ac{FIJI} hardware.
A \href{https://www.freedesktop.org/software/systemd/man/udev.html}{\texttt {udev}} rule or similar that symlinks the HX8K board to \texttt{/dev/ttyHX8K} may be useful, for example:
\begin{lstlisting}[style=plain,gobble=12]
{SUBSYSTEM=="tty",ATTRS{idVendor}=="0403",ATTRS{idProduct}=="6010",ATTRS{product}=="Lattice FTUSB Interface Cable", SYMLINK+="ttyHX8K"}
\end{lstlisting}
\item Check the connectivity by pressing the \emph{Update} button.
If no error message is shown in the logging box, the design
is ready for fault injection.
\item Perform sequence, manual, or random fault injections.
Faults are immediately visible by distorted VGA output. Since
the provided FIJI configuration does not alter the VGA timing,
the provided \ac{FIJI} configuration does not alter the VGA timing,
this should work with all monitors.
\end{enumerate}
Markdown is supported
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