09-demo_yosys.tex 5.68 KB
Newer Older
1
\section{Yosys Demonstration with \texttt{tinyvga}}
2

3
Another demo design was implemented in Verilog in order to demonstrate the
Christian Fibich's avatar
Christian Fibich committed
4
5
6
interoperability with the open-source synthesis framework Yosys\footnote{\url{http://www.clifford.at/yosys/},~visited on May~7, 2018}
and the IceStorm toolchain\footnote{\url{http://www.clifford.at/icestorm/},~visited on May~7, 2018}.
The target board for this design is the \emph{HX8K Breakout Board}\footnote{\url{http://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx},~visited on May~7, 2018}
7
offered by Lattice Semiconductor Corp. Additionally, a VGA DAC extension
Christian Fibich's avatar
Christian Fibich committed
8
board such as the XESS StickIt VGA module\footnote{\url{http://www.xess.com/shop/product/stickit-vga/},~visited on May~7, 2018} is needed.
9

10
11
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
12
13
14
15
16
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}

17
\begin{wrapfigure}{r}{0.4\textwidth}
18
\centering
19
20
\vspace{-9ex}
\includegraphics[height=15em]{img/hx8k_j2.pdf}
21
22
\caption{HX8K Connections}
\label{fig:hx8k_connections}
23
24
\vspace{-9ex}
\end{wrapfigure}
25

26
27
\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.
28

29
30
31
32
33
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}
34

35
36
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
37
38
39
40
step, the entire netlist instrumentation process, as well as the final
synthesis step combining the wrapper and the instrumented netlist, is handled
by Yosys.

41
42
43
44
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.

45
Furthermore, a \texttt{FIJI\_ROOT} environment variable shall point to the
46
root directory where \ac{FIJI} was cloned from the git repository.
47
48
49
50
51
52
53

\subsection{Executing the Demo Flow}

The entire instrumentation process is executed by two Makefiles (to be
executed in that order):

\begin{enumerate}
54
55
    \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
Stefan Tauner's avatar
Stefan Tauner committed
56
          \texttt{docs/demos/hx8k\_demo/impl/original/}. Run
57
58
59
        \begin{lstlisting}[style=shell,gobble=12]
            $ make fiji-instrument
        \end{lstlisting}
60
61
62
63
64
          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
65
66
          downloads it to a connected HX8K breakout board.
    \item The second synthesis step, as well as run-time fault injection is
Stefan Tauner's avatar
Stefan Tauner committed
67
          executed by the Makefile found in the directory \texttt{docs/demos/hx8k\_demo/impl/instrumented/}.
68
          To download the instrumented design to a connected board and launch \ac{FIJIEE}
69
70
71
72
          subsequently, execute
        \begin{lstlisting}[style=shell,gobble=12]
            $ make prog && make fiji-launch
        \end{lstlisting}
73
          in this directory. This automatically synthesizes
74
          the VHDL parts to a netlist using Synplify (the command and
75
76
          options are defined in the Makefile), combines the \ac{FIJI} logic and
          the instrumented netlist using Yosys, and generates
77
          a bitstream for the HX8K device using the IceStorm tools.
78
          Eventually it downloads the instrumented design and the second commands launches the \ac{FIJIEE} GUI.
79
80
81
82
\end{enumerate}

\subsection{Run-Time Fault Injection}

83
84
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
85
86
image source on-chip RAM.

87
Once the design is downloaded and the \ac{FIJIEE} GUI is launched, the following
88
89
90
things may be done:

\begin{enumerate}
91
92
93
94
95
    \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}
96
97
98
99
100
    \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
101
          the provided \ac{FIJI} configuration does not alter the VGA timing,
102
103
104
          this should work with all monitors.
\end{enumerate}