08-demo.tex 20.1 KB
Newer Older
1
2
3
4
5
6
\section{Demo: TMR VGA}

\subsection{Use Case}
The \ac{TMR} \ac{VGA} demo design is intended to demonstrate the effects of fault injection in an TMR

A sprite engine draws a sprite of a small airplane on the screen in front
7
of a blue-red gradient background. The sprite of the airplane is moved across the
8
screen in successive frames, changing direction when it reaches any of
9
the visible screen borders. Screenshots can be seen in \Cref{fig:tmrvga_screenshot}.
10
11
12
13
14
15
The left side shows the error-free case, a stuck-open error in the sprite
engine can be seen on the right side.

\begin{figure}[htb]
\centering
\includegraphics[width=0.8\linewidth]{img/tmrvga_screenshot.jpg}
16
\caption{\ac{TMR} \ac{VGA} Screenshots}
17
18
\label{fig:tmrvga_screenshot}
\end{figure}
19
20

The use case is designated for use with the Cyclone III-based DE0 development
21
22
23
board from Terasic\footnote{\url{http://de0.terasic.com.tw}, 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},
24
but is portable to other boards providing a \ac{VGA} connector with little effort. It is implemented in VHDL.
25
26
27
28
29
30
31
32
33
34
35
36
37

\begin{figure}[htb]
\centering
\input{img/blockdiagram-usecase.tex}
\caption{\ac{TMR} \ac{VGA} Use Case}
\label{fig:tmrvga}
\end{figure}

The design contains a \ac{VGA} timing generator module, which provides
HSync and VSync signals as well as the row and column in the current frame.
The output of the sprite engine is the color of the current pixel, blanked in the non-visible area of the \ac{VGA} timing. 
This sprite engine is triplicated, as an analogy to triplicated avionics in an actual airplane.
Majority voting is performed over the three color channels before outputting the color value to a parallel \ac{DAC}.
38
The voters are also able to determine if a 2:1 mismatch has occurred.
39
40
41
42
43
44
45
46
A coarse block diagram of the design can be seen in \Cref{fig:tmrvga}.

An important thing to note is that the sprite position registers within the sprite engines are not converged using majority voting.
Thus, faults affecting the direction register will cause the domain 0 to permanently diverge from the others until the design is reset.
In a real-world design the states of the redundant units would usually be determined by the voter.

\subsection{Hardware Setup}

47
\subsubsection{Digilent Basys 3}
48
\begin{itemize}
49
50
51
52
53
54
    \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.
55
    \item The external trigger is activated when BTNU is pressed.
56
    \item The four rightmost LEDs above the dip switches (LD0-LD3) show the error detection state:
57
        \begin{itemize}
58
59
60
61
62
63
64
65
66
67
68
69
70
71
            \item LD0 shows if any error has been detected.
            \item LD1-3 show which voter (Red, Green, Blue) detected the error.
        \end{itemize}
\end{itemize}

\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).
72
            \item If your cable requires an I/O voltage input (e.g., FTDI TTL-232R-VIP),
73
                  connect the correspondig wire to PMOD JE6.
74
        \end{itemize}
75
76
77
78
79
80
81
        \begin{figure}[H]
        \centering
        \includegraphics[width=10em]{img/zybo_je.pdf}
        \caption{Zybo Connections}
        \label{fig:zybo_connections}
        \end{figure}

82
83
    \item Connect a VGA-compatible monitor to the VGA port.
          The design generates a 640x480 @ 25Mhz VGA signal.
84
    \item The dip-switch SW0 controls if TMR is enabled.
85
    \item BTN0 resets the design when pressed.
Christian Fibich's avatar
Christian Fibich committed
86
    \item The external trigger is activated when BTN1 is pressed.
87
    \item The LEDs above the dip switches (LD0-LD3) show the error detection state:
88
        \begin{itemize}
89
90
            \item LD0 shows if any error has been detected.
            \item LD1-3 show which voter (Red, Green, Blue) detected the error.
91
        \end{itemize}
92
93
\end{itemize}

94
\subsubsection{Terasic DE0}
Christian Fibich's avatar
Christian Fibich committed
95

96
\begin{itemize}
97
    \item Connect a 3V3 Serial TTL cable to the DE0:
Christian Fibich's avatar
Christian Fibich committed
98
99
100
101

        \begin{minipage}[h]{\linewidth}
        \centering
        \begin{minipage}{0.45\linewidth}
102
        \begin{itemize}
103
104
105
106
107
            \item Connect \textit{Ground} to any GND pin on GPIO1 (e.g., J5.30).
            \item Connect \textit{TXD (Host-to-Device)} to GPIO1\_D31 (J5.40).
            \item Connect \textit{RXD (Device-to-Host)} to GPIO1\_D30 (J5.39).
            \item Leave \textit{\#RTS} unconnected.
            \item Connect \textit{\#CTS} to GND (or leave unconnected if your cable pulls it down).
108
            \item If your cable requires an I/O voltage input (e.g., FTDI TTL-232R-VIP),
109
                  connect the correspondig wire to any 3V3 pin on GPIO1 (e.g., J5.29).
110
        \end{itemize}
Christian Fibich's avatar
Christian Fibich committed
111
112
113
114
115
116
117
118
119
120
121
122
123
124
        \end{minipage}
        \hspace{0.05\linewidth}
        \begin{minipage}{0.45\linewidth}
        \begin{figure}[H]
        \centering
        \includegraphics[height=20em]{img/de0_j5.pdf}
        \caption{DE0 Connections}
        \label{fig:de0_connections}
        \end{figure}
        \end{minipage}

    \end{minipage}
    \vspace{1em}

125
    \item Connect a VGA-compatible monitor to the VGA port.
126
127
128
          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 BUTTON0 resets the design.
Christian Fibich's avatar
Christian Fibich committed
129
    \item The external trigger is activated when BUTTON1 is pressed.
130
    \item The green LEDs above the three buttons (LEDG0-LEDG3) show the error detection state:
131
        \begin{itemize}
132
133
            \item LEDG0 shows if any error has been detected.
            \item LEDG1-3 show which voter (Red, Green, Blue) detected the error.
134
        \end{itemize}
135
136
137
138
\end{itemize}

\subsection{Work Flow}

139
140
141
142
143
144
145
146
147
148
149
150
151
152
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}
153

154
155
156
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).
157
The resulting file should be located in the \texttt{synp} directory (e.g., \texttt{synp/de0/de0/spriteflyer\_top.vqm}).
158
159

\subsubsection{Run setup}
160
161
    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:
162
163
164
165
166
167
    \begin{lstlisting}[style=shell,gobble=8]
        $ perl ../../../bin/fiji_setup.pl -s fiji/de0_test_1/fiji/fiji.cfg \
                                          -n synp/de0/de0/spriteflyer_top.vqm
    \end{lstlisting}

\subsubsection{Instrumentation}
168
    To apply the configuration and instrument the design run:
169
170
171
172
173
174
    \begin{lstlisting}[style=shell,gobble=8]
        $ perl ../../../bin/fiji_instrument.pl -s fiji/de0_test_1/fiji/fiji.cfg \
                                               -n synp/de0/de0/spriteflyer_top.vqm \
                                               -o fiji/de0_test_1/fiji \
                                               -p tmr_vga_demo
    \end{lstlisting}
175

176
177
178
179
180
\subsubsection{Synthesis using Synplify Pro}
\begin{enumerate}
    \item Create a new Synplify project file named 'spriteflyer\_top.prj' in \texttt{fiji/de0\_test\_1/synp}
    \item Open the project
    
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
    \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}
197

198
199
200
201
202
203
204
        \medskip
        Finally, you have also to set the correct device in the first tab:
        \begin{itemize}
            \item \textbf{Basys~3}: Artix7 XC7A35T-CPG236-1
            \item \textbf{DE0}: Cyclone III EP3C16-F484-C6
            \item \textbf{Zybo}: Zynq XC7Z010-CLG400-1
        \end{itemize}
205

206
    \item Add the following files to the project:
207
208
209
210
211
212
213
214
        \begin{plainlisting}[gobble=12]
            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_wrapper.vhd
            fiji/de0_test_1/fiji/tmr_vga_demo_constraints.synplify.fdc
            fiji/de0_test_1/synp/spriteflyer_top.fdc
            <FIJI PUBLIC ROOT>/hw/rtl/*.vhd
        \end{plainlisting}
215
216
        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 the original Synplify project.
217

218
    \item Synthesize (\keystroke{F8})
219
\end{enumerate}
220
221
222
223

\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.
224
225
226
227
228
229
230
231

\begin{enumerate}
    \item Copy the following files into the \texttt{fiji/de0\_test\_1/quartus} directory:
        \begin{plainlisting}[gobble=12]
            synp/de0/de0/spriteflyer_top_p_sprite_rom_s_sprit.hex
            synp/de0/de0/spriteflyer_top_p_sprite_rom_s_spritmif1.hex
            synp/de0/de0/spriteflyer_top_p_sprite_rom_s_spritmif2.hex
        \end{plainlisting}
232
233

    \item Create a new project (e.g., \texttt{fiji\_de0.qpf} in  \texttt{fiji/de0\_test\_1/quartus}
234
235
236
237
238

        Set Cyclone III - EP3C16-F484-C6 as device

    \item Add the following files to the project
        \begin{plainlisting}[gobble=12]
239
            fiji/de0_test_1/fiji/fiji\_top.vqm
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
            fiji/de0_test_1/fiji/tmr_vga_demo_constraints.quartus.qsf
            fiji/de0_test_1/quartus/fiji_top.sdc
        \end{plainlisting}

    \item Import the assignments from
        \begin{plainlisting}[gobble=12]
            boards/pins_de0.qsf
            fiji/de0_test_1/fiji_pins.qsf
        \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 Quartus.

    \item Perform ``Analysis and Synthesis''

    \item Check the imported pin assignments in the Pin Planner

    \item Perform ``Full Compilation'

\end{enumerate}

261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
\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}

298
299
300
\subsection{Runtime Fault Injection}

\begin{enumerate}
301
    \item Download the FPGA bitstream with the FPGA vendor tool
302
    \item Run the \ac{FIJIEE} GUI
303
304
305
306
        % \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}
307
        \begin{lstlisting}[style=shell,gobble=12]
308
            $ perl ../../../bin/fiji_ee_gui.pl -s fiji/de0_test_1/fiji/tmr_vga_demo_download.cfg
309
        \end{lstlisting}
310
311
312
313
314
315
316
    \item Execute tests at will
    % \item Execute tests:
    % \begin {itemize}
        % \item Pre-defined sequence in \texttt{fiji/de0\_test\_1/fiji/tmr\_vga\_demo\_test.tst}
        % \item Manual tests
        % \item Random tests
    % \end {itemize}
317
318
319
320
321
322
323
324
325
326
327
\end{enumerate}

When the \emph{\ac{TMR} Enable} switch is in ``0'' position, the output from
\ac{TMR} domain 0 is directly relayed to the \ac{VGA} output. All faults are directly
visible. The fault detection LEDs remain dark.

When the \emph{\ac{TMR} Enable} switch is in ``1'' position, the \ac{VGA} output is
generated by majority voting over the three \ac{TMR} domains. Faults in \ac{TMR}
domain 0 are masked and thus are not visible. When \ac{TMR} is enabled, the LEDs on
the board show (1) if an error is detected by the voter (one domain disagrees
with the others) and (2) in which voter (Red, Green, Blue) the error is detected.
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436


\section{Yosys Demo}

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}
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.

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
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}
\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}
\caption{HX8K Connections}
\label{fig:hx8k_connections}
\end{figure}
\end{minipage}
\end{minipage}

\subsection{Software Setup}

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.

As Yosys does not support VHDL as an input language, Synplify is
required to synthesize the 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.

Furthermore, a \texttt{FIJI\_ROOT} environment variable shall point to the
root directory where FIJI was cloned from the git repository.

\subsection{Executing the Demo Flow}

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
          \texttt{docs/demos/tinyvga/impl/original/}. Run
        \begin{lstlisting}[style=shell,gobble=12]
            $ make fiji-instrument
        \end{lstlisting}
          to synthesize the 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
          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
          subsequently, execute
        \begin{lstlisting}[style=shell,gobble=12]
            $ make prog && make fiji-launch
        \end{lstlisting}
          in this directory. This Makefile 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
          a bitstream for the HX8K device using the IceStorm tools.
\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
image source on-chip RAM.

Once the design is downloaded and the FIJI EE 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 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,
          this should work with all monitors.
\end{enumerate}