04-setup.tex 12.1 KB
Newer Older
Stefan Tauner's avatar
Stefan Tauner committed
1
\section{Configuration}
2
\label{sec:setup}
Christian Fibich's avatar
Christian Fibich committed
3

Christian Fibich's avatar
Christian Fibich committed
4
5
The \textit{\ac{FIJI} Setup} Tool provides a graphical user interface to
create and edit a \textit{\ac{FIJI} Configuration} that can be used to
6
7
8
9
10
instrument a netlist and run fault injection tests. It helps the user
by checking the sanity of entered values, and eases
net and driver selection by displaying suggestions parsed from the
netlist.

Christian Fibich's avatar
Christian Fibich committed
11
Although \textit{\ac{FIJI} Setup} is a graphical tool, it accepts the
12
following \emph{optional} command-line arguments:
13
14

\begin{itemize}
15
    \item \texttt{-s, {-}{-}settings=<filename>}
16

Christian Fibich's avatar
Christian Fibich committed
17
    Specifies a \textit{\ac{FIJI} Settings} file to load at startup
18

19
    \item \texttt{-n, {-}{-}netlist=<filename>}
20
21

    Specifies a netlist file to load at startup
22
23
24
25
26

    \item \texttt{-v, {-}{-}verbose}

   Increase verbosity on the terminal. Each occurence of \texttt{-v} or
   \texttt{{-}{-}verbose} further increases verbosity.
27
28
29
30
31
32
33
    
    \item \texttt{-h, {-}{-}help}

   Displays usage information on the terminal and exits
\end{itemize}


34
The main GUI elements can be seen in \Cref{fig:setup}. The user
35
36
37
38
39
40
interface consists of (1) the \textit{Control Area}, (2) \textit{Tabs}
for selecting different categories of values to be entered, (3) the
\textit{Main Panel}, (4) the \textit{Resource Panel} and (5) the \textit{Navigation Panel}.


\begin{figure}[ht]
Christian Fibich's avatar
Christian Fibich committed
41
\centering
42
\input{img/fiji_setup_screenshot_marked}
Christian Fibich's avatar
Christian Fibich committed
43
\caption{\ac{FIJI} Setup Tool}
44
45
46
\label{fig:setup}
\end{figure}

47
48
\subsection{Control Area and Menu Bar}

49
Using the \textit{Control Area}, file operations can be performed:
Christian Fibich's avatar
Christian Fibich committed
50
The user can select to load a \textit{\ac{FIJI} Configuration} file from disk
51
52
or save the current configuration to a file. Additionally, a Verilog
netlist file can be loaded.
53
54
55
These actions can be performed both via the buttons in the \textit{Control Area} and the menu bar above.
The settings file currently edited is displayed along with the currently loaded netlist.
Using the \textit{Help} menu entry, license information as well as this help document can be accessed.
56
57

Upon startup, when no configuration file is specified via command-line
58
59
60
61
options, \textit{\ac{FIJI} Setup} starts with the \textit{Default Configuration}.
This includes default values for most signals and a single \ac{FIU} (cf.\ \Cref{sec:resource_usage}).

The initial configuration can either be used to
62
63
64
65
create a customized configuration using the GUI, or saved to a file and
edited manually using a text editor.

A netlist must be loaded to perform netlist-related tasks 
Christian Fibich's avatar
Christian Fibich committed
66
(choosing nets, pin names, and drivers). When a netlist is loaded, \ac{FIJI}
67
68
analyzes the contained Verilog modules and builds an internal representation.
Thus, larger netlists may take a while to load. During
69
70
71
this time, a loading screen barring the user from interaction with the
GUI is displayed.

72
73
\subsection{Tabs and Main Area}

74
75
76
77
For clarity, the GUI separates the different configuration topics into
different \textit{Tabs}. The following topics are available for
configuration:

78
79
\begin{description}
    \item[General Settings]
80
81

          Settings for the instrumentation and synthesis process,
Christian Fibich's avatar
Christian Fibich committed
82
          as well as settings for the serial communication between \ac{FIJI} and host
83
84
          and the fault injection timers are subsumed under this tab.

85
    \item[Clock Settings]
86
    
87
          The \textit{\ac{FIJI}} fault injection logic is clocked from a clock domain in the \ac{DUT} where faults are injected.
88
89
          The name and frequency of this clock net need to be specified.

90
    \item[\acs{LFSR} Settings]
91

92
          \textit{\ac{FIJI}} emulates floating nets caused by \textit{stuck-open}
93
          faults by forcing pseudo-random binary levels onto the respective
94
95
          net. These levels are derived from the value of a \textit{\ac{LFSR}}.
          In this tab, the width, polynomial,
96
          and starting value of this register can be configured.
97
          See \Cref{sec:lfsrtable} for a list of complete \ac{LFSR} polynomials
98
99
          for different lengths.

100
    \item[External Reset]
101

Christian Fibich's avatar
Christian Fibich committed
102
          The \ac{FIJI} logic can be configured to be reset from an external
103
104
105
          pin. This feature can be turned on and off in this tab.
          If an external reset pin is desired, the polarity and name must be entered.

106
    \item[Reset from \acs{DUT} to \ac{FIJI}]
107
108
        
          In addition to the external reset via pin, also any net of the
109
          \ac{DUT} can be used to reset the \ac{FIJI} logic. This feature can be
110
          turned on and off in this tab. If an internal reset from the
111
112
113
          \ac{DUT} is desired, the polarity and source net name must be entered.
          When the \textit{Reset from \ac{DUT} to \ac{FIJI}} feature is used, the
          \textit{Reset from \ac{FIJI} to \ac{DUT}} feature cannot be used at the
114
          same time.
115
          If both the external reset feature and the reset from \ac{DUT} to
Christian Fibich's avatar
Christian Fibich committed
116
117
          \ac{FIJI} are enabled, the reset sources are ORed together and used
          as the \ac{FIJI} logic's asynchronous reset signal.
118

119
    \item[Reset from \ac{FIJI} to \acs{DUT}]
120

Christian Fibich's avatar
Christian Fibich committed
121
          In contrast to the feature described above, the \ac{FIJI} logic can
122
123
124
125
          also be used as a source for a reset net in the \ac{DUT}.
          When the \textit{Reset from \ac{FIJI} to \acs{DUT}} feature is used, the
          \textit{Reset from \acs{DUT} to \ac{FIJI}} feature cannot be used at the
          same time. If an internal reset from \ac{FIJI} to the \ac{DUT} is desired,
126
127
128
          the polarity, target net name, and desired reset pulse duration
          must be entered.

129
    \item[Trigger Settings]
130
131

          In order to support dynamic test execution depending on 
Christian Fibich's avatar
Christian Fibich committed
132
          events external to \ac{FIJI}, trigger signals can be used to 
133
134
          continue a suspended test execution.
          Both an external trigger via an FPGA pin as well as an internal
135
          trigger using a net in the \ac{DUT} as a source can be used. The
Christian Fibich's avatar
Christian Fibich committed
136
          \ac{FIJI} logic can be instructed at runtime if it shall wait for
137
138
139
140
          the internal or external trigger signal.
          For both the internal and the external trigger facilities,
          the respective pin or net name and polarity must be specified.

141
    \item[Fault Detection Settings]
142

143
          The value of up to two nets in the \ac{DUT} can be communicated back to the
144
          host as a means for fault detection. The names and error
145
146
          levels of these nets need to be specified when they are used.

147
    \item[\acfp{FIU}]
148
149
150
151
          
          Here, the actual fault injection capabilities of the instrumented
          design are configured. For each net into which faults shall be 
          injected at runtime, a \textit{Fault Injection Unit} needs to 
Christian Fibich's avatar
Christian Fibich committed
152
          be added. Each \ac{FIU} has an associated net, a driver for this net,
153
          and fault injection capabilities to be configured.
154
\end{description}
155
156
157

The left hand side of the \textit{Main Area} displays a graphical representation
of the current hardware configuration in all tabs. Changes in the configuration
Christian Fibich's avatar
Christian Fibich committed
158
such as added \ac{FIU}s and changed signal polarities are reflected in this
159
160
161
162
block diagram immediately. Some blocks and signals provide additional
information when the cursor hovers above them. On the right hand side 
of the \textit{Main Area} the configuration items for the current tab
are displayed. Each time a value is updated in one of the configuration
Christian Fibich's avatar
Christian Fibich committed
163
items, \textit{\ac{FIJI} Setup} checks for sanity and validity of the entered
164
165
166
167
value. If a check fails, the corresponding field is marked in red until
a valid value is entered. Also fields which cannot yet be verified
(e.g., net names, when no netlist is loaded) are marked in this way. 
Nevertheless, it is possible to save a configuration with values deemed
Christian Fibich's avatar
Christian Fibich committed
168
invalid by \textit{\ac{FIJI} Setup}. A warning is issued before such configuration
169
170
is saved.

171
In the \ac{FIU} tab as shown in \Cref{fig:FIUtab}, the user may add fault
Christian Fibich's avatar
Christian Fibich committed
172
173
174
injection units using the \textit{Append Empty \ac{FIU}} button and remove 
them selectively using the trash can icon next to each \ac{FIU}.
Added \ac{FIU}s are ``empty'', i.e., they have no associated net and driver.
175

Christian Fibich's avatar
Christian Fibich committed
176
177
178
179
180
181
182
183
\begin{figure}[ht]
\centering
\input{img/fiji_setup_fius_marked}
%\includegraphics[width=0.85\linewidth]{img/\ac{FIJI}_setup_screenshot.png}
\caption{\ac{FIJI} Setup Tool: \ac{FIU} Tab}
\label{fig:FIUtab}
\end{figure}

Christian Fibich's avatar
Christian Fibich committed
184
The \ac{FIU}s can be configured in the following way:
Christian Fibich's avatar
Christian Fibich committed
185
186
187
Once a netlist is loaded, the user may start with selecting a net to be
instrumented. This is done using a filter dialog which is opened by pressing
the \textit{Select} button next to the net entry field (1).
188
An example for this dialog is shown in \Cref{fig:netsel}. The entry field across
189
190
the top may be used to specify a hierarchical path to a net as perl-style regular expression\footnote{This means that the backslashes and other regex meta characters in escaped identifiers need to be escaped themselves, e.g. for net ``\texttt{{\textbackslash}escaped.identifier }'' write ``\texttt{{\textbackslash}{\textbackslash}escaped{\textbackslash}.identifier }''}.

191
192
\begin{minipage}{\textwidth}
A hierarchical path shall be constructed as follows in Extended Backus-Naur Form:
193
194

\begin{verbatim}
195
196
197
198
199
hierarchical-path = top, "/", { cell-list }, net;
cell-list         = { cell-list }, cell, "/";
top               = ? Toplevel module name ?;
net               = ? Net name ?;
cell              = ? Cell name ?;
200
\end{verbatim}
201
202
\smallskip
\end{minipage}
203
204
205
206
207
208
209

A hierarchical path starts with the name of the toplevel module, then
contains a path of instantiation names, and finally, the name of a net.
The forward slash character \texttt{`/'} is used as a separator between
module, instantiation, and net names.

Once the user presses the \textit{Search} button, all matching
Christian Fibich's avatar
Christian Fibich committed
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
nets are displayed in the left list box (``Matching nets''). The desired net
can now be selected for fault injection by first selecting it in the
left list box and then pressing the ``\textgreater'' button. Once a net is selected,
it is shown in the list box on the right. Now, clicking ``OK'' selects this
net for the current \ac{FIU}. An already selected net may be de-selected
by pressing the ``\textless'' button. The net selection dialog is used
wherever a net has to be selected: Also the clock net and the fault detection
nets are selected using this method.

\begin{figure}[ht]
\centering
\includegraphics[width=0.6\linewidth]{img/fiji_net_selection.png}
\caption{\ac{FIJI} Setup Tool: Net selection dialog}
\label{fig:netsel}
\end{figure}

Once a net is selected, \textit{\ac{FIJI} Setup} checks if this net is actually
227
present in the \ac{DUT} netlist. The user must then select the driver for
228
229
230
231
232
this net using the \textit{Driver} button (3). This opens up a dialog
with all possible driver objects for this net prompting the user to select
one of these options.
Additionally, the supported fault model can be selected (2). If the fault
model \textit{RUNTIME} is selected, all fault models are supported by
Christian Fibich's avatar
Christian Fibich committed
233
234
235
this \ac{FIU} and can be activated at runtime. In order to save resources and
timing budget, each \ac{FIU} can also be configured to support only a single
fault model. At runtime, this \ac{FIU} can then only be switched between the
236
selected fault model and fault-free operation.
237
238
239
240
For the emulation of a floating net, the output of an \ac{LFSR} is used (see above).
Using the \textit{\acs{LFSR} mask} element (4), the user needs to select a
bit mask at most as wide as the \ac{LFSR}. The bits of the
\ac{LFSR} corresponding to `1`s in the \textit{mask} are ANDed together,
241
242
243
resulting in the ``floating'' value of the
corresponding net.

244
\subsection{Statusbar: Resources and Navigation}
245

246
At the bottom of the user interface (see \Cref{fig:setup}),
247
the \textit{Resource Panel} (4) displays the combinational resources
248
249
(i.e., \acp{LUT}) and the registers needed to implement the current
configuration \emph{in relation to the default configuration}.
250
Absolute resource numbers for different FPGA families are shown
251
in \Cref{tab:resources}.
252
Within the \textit{Button Panel} (5), the \text{Next} and \textit{Back}
253
buttons provide additional navigation through the tabs.
254
255


Christian Fibich's avatar
Christian Fibich committed
256
Alternatively, a \textit{\ac{FIJI} Configuration} can be created manually using
257
a text editor. A template file can be generated by saving the default
258
configuration out of the \textit{\ac{FIJI} Setup Tool}.