04-setup.tex 13.4 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

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

Christian Fibich's avatar
Christian Fibich committed
25
   Increase verbosity on the terminal. Each occurrence of \texttt{-v} or
26
   \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
172
173
174
175
176
177
178
179
180
In the \ac{FIU} tab as shown in \Cref{fig:FIUtab}, the user has two options
of adding fault injection units:

\begin{itemize}
    \item ``Empty'' \acp{FIU} are added using the \textit{Append empty FIU} button (1).
          These \acp{FIU} have no associated net and driver upon creation.
    \item Multiple \acp{FIU} can be added using the \textit{Append multiple FIUs} button (2).
          Here, a dialog to select multiple nets is opened. This mode is only applicable
          if a netlist file is already loaded.
\end{itemize}
181

Christian Fibich's avatar
Christian Fibich committed
182
183
184
185
186
187
188
189
\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
190
The \ac{FIU}s can be configured in the following way:
191
192
193
194
195
Once a netlist is loaded, the user may edit the 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 (3). An example for this dialog is shown
in \Cref{fig:netsel}. The entry field across the top may be used to
specify a hierarchical path to a net as perl-style regular
196
197
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 }''.},
as a shell-style glob\footnote{The standard wildcards * and ? may be used.}, or simply as a substring of the desired net\footnote{This is equivalent to *\textit{\textless text \textgreater}* in glob mode.}.
198

199
\begin{minipage}{\textwidth}
200
201
Regardless of the search mode, the entered expression must match an entire
hierarchical path. A hierarchical path shall be constructed as follows in Extended Backus-Naur Form:
202
203

\begin{verbatim}
204
205
hierarchical-path = top, "/", { cell-list }, net;
cell-list         = { cell-list }, cell, "/";
206
top               = ? Top-level module name ?;
207
208
net               = ? Net name ?;
cell              = ? Cell name ?;
209
\end{verbatim}
210
211
\smallskip
\end{minipage}
212

213
A hierarchical path starts with the name of the top-level module, then
214
215
contains a path of instantiation names, and finally, the name of a net.
The forward slash character \texttt{`/'} is used as a separator between
216
217
218
module, instantiation, and net names. As extended identifiers may be
generated, make sure to add a space after the extended identifier as
required by the Verilog standard.
219
220

Once the user presses the \textit{Search} button, all matching
Christian Fibich's avatar
Christian Fibich committed
221
222
223
224
225
226
227
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
228
229
230
231
232
nets are selected using this method. A slightly different version is used
where multiple nets may be selected (\textit{Append multiple FIUs} in the
\ac{FIU} tab). Here, there also exist buttons to add all nets in the
left list box (``\textgreater\textgreater'') or to remove all nets from the
right list box (``\textless\textless'').
Christian Fibich's avatar
Christian Fibich committed
233
234
235
236

\begin{figure}[ht]
\centering
\includegraphics[width=0.6\linewidth]{img/fiji_net_selection.png}
237
\caption{\ac{FIJI} Setup Tool: Net selection dialog (Single Net)}
Christian Fibich's avatar
Christian Fibich committed
238
239
240
241
\label{fig:netsel}
\end{figure}

Once a net is selected, \textit{\ac{FIJI} Setup} checks if this net is actually
242
present in the \ac{DUT} netlist. The user must then select the driver for
243
this net using the \textit{Driver} button (7). This opens up a dialog
244
245
with all possible driver objects for this net prompting the user to select
one of these options.
246
Additionally, the supported fault model can be selected (4). If the fault
247
model \textit{RUNTIME} is selected, all fault models are supported by
Christian Fibich's avatar
Christian Fibich committed
248
249
250
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
251
selected fault model and fault-free operation.
252
For the emulation of a floating net, the output of an \ac{LFSR} is used (see above).
253
Using the \textit{\acs{LFSR} mask} element (8), the user needs to select a
254
255
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,
256
257
258
resulting in the ``floating'' value of the
corresponding net.

259
260
261
262
263
264
265
A name may be assigned to each \ac{FIU} by pressing the name tag button (5).
This name is for documentation purposes only and is displayed next to the
index for each \ac{FIU} in the Settings Editor and the Execution Engine.
Single \acp{FIU} can be deleted by pressing the delete button (6).
Using the up and down arrows next to the delete button, \acp{FIU} can
be reordered.

266
\subsection{Statusbar: Resources and Navigation}
267

268
At the bottom of the user interface (see \Cref{fig:setup}),
269
the \textit{Resource Panel} (4) displays the combinational resources
270
271
(i.e., \acp{LUT}) and the registers needed to implement the current
configuration \emph{in relation to the default configuration}.
272
Absolute resource numbers for different FPGA families are shown
273
in \Cref{tab:resources}.
274
Within the \textit{Button Panel} (5), the \text{Next} and \textit{Back}
275
buttons provide additional navigation through the tabs.
276
277


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