03-software.tex 17.5 KB
Newer Older
1
\section{Software}
2
3
\label{sec:flow}

Stefan Tauner's avatar
Stefan Tauner committed
4
This chapter sums up some concepts of the Perl classes used in the \ac{FIJI} framework.
5
Their use in the complete tool flow and the respective interfaces to the vendor tools are described in detail in \hyperref[UG:sec:flow]{the \ac*{UG}}.
Stefan Tauner's avatar
Stefan Tauner committed
6
You should consult the Doxygen documentation and source files for the details beyong the overview given below.
7
8
9
10

\subsection{FIJI Settings}

The \ac{FIJI} framework is highly configurable and consists of various parts that require access to configuration parameters (see the tables in \Cref{sec:settings_consts} for a complete list).
Stefan Tauner's avatar
Stefan Tauner committed
11
12
The \ac{FIJI} Settings file (usually named \texttt{fiji.cfg}) serves as intermediate storage for the parameters and is read and written by the various tools of the framework.
This file is organized in blocks of key-value pairs represented in the same format as common \texttt{.ini} files:
13
14
15
16

\begin{itemize}
    \item Each block starts with the name of the block in square brackets;
    \item the key-value pairs that belong to a block follow one per line;
Stefan Tauner's avatar
Stefan Tauner committed
17
    \item the keys on the left side are separated by (the first) equal sign (\texttt{=}) from the values on the right side.
18
19
\end{itemize}

Stefan Tauner's avatar
Stefan Tauner committed
20
There are two major types of blocks allowed in \ac{FIJI} Settings:
21
22

\begin{itemize}
Stefan Tauner's avatar
Stefan Tauner committed
23
24
    \item A single \texttt{consts} block specifies various constants for a specific design.
    \item For every \ac{FIU} in the setup there is a respective block named \texttt{\ac{FIU}\textit{<number>}} where \textit{<number>}
25
26
27
28
29
30
    is a strictly increasing integer starting with 0 for the first \ac{FIU} in a design.
\end{itemize}

\subsection{Constants in \ac{FIJI} Settings}
\label{sec:settings_consts}

Stefan Tauner's avatar
Stefan Tauner committed
31
32
33
\Cref{tab:consts} lists all specifiable constants for a design, while
\Cref{tab:fiuconsts} explains the settings for each \ac{FIU}.
The ``Name''
34
35
36
37
38
columns denote the key names in the \ac{FIJI} Settings file. The possible ranges of values and their defaults
are given in the ``Range'' and ``Default'' columns respectively.
The defaults are offered to the user as preselected values and assumed
by the tools if no value is available when one is needed but not available.

Stefan Tauner's avatar
Stefan Tauner committed
39
40
Additionally, the literals used to specify the available fault models at runtime are listed in \Cref{tab:faultmodels}.

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
\begin{table}
    \caption{Design Constants}
    \input{content/tab_design_consts.tex}
    \label{tab:consts}
\end{table}

\begin{table}
    \caption{FIU Constants}
    \input{content/tab_fiu_consts.tex}
    \label{tab:fiuconsts}
\end{table}

\begin{table}
    \caption{Fault Model Type Literals}
    \input{content/tab_faultmodels.tex}
    \label{tab:faultmodels}
\end{table}
58

Stefan Tauner's avatar
Stefan Tauner committed
59
60
61
62
63
64
\subsection{Implementation and Usage of the Settings}
\label{sec:settings_usage}

Since the settings play such a tremendously important role in \ac{FIJI} their existence is rooted in a single file (\texttt{FIJI.pm}) that also holds a number of other constants.
In \texttt{FIJI.pm} keys of the constants listed in \Cref{tab:consts} and \Cref{tab:fiuconsts} are stored as hash references binding some properties to them, namely:

65
{\small
Stefan Tauner's avatar
Stefan Tauner committed
66
67
68
69
70
71
72
73
74
75
76
77
78
79
\begin{description}[style=sameline]
    \item [\texttt{ini\_name}] maps the Perl-internal names to those used in the settings file.
    \item [\texttt{description}] describes the underlying setting in a few words.
    \item [\texttt{help}] contains a longer, user-oriented description of the setting.
    \item [\texttt{type}] of the value, e.g., \texttt{boolean}, \texttt{natural}, \texttt{net} allowing for validation.
    \item [\texttt{phases\_opt}] contains a list of optional flow phases that controls validation exemptions.
    \item [\texttt{group}, \texttt{order}] tags the settings to be layouted in the GUI together in a certain order, see also \texttt{DISPLAYGROUPS}.
    \item [\texttt{depends\_on}] lists other settings that need to be enabled/valid for this one to work.
    \item [\texttt{forbidden\_by}] lists other settings that are exclusive to this one.
    \item [\texttt{values}] can either be an array of allowed values or a reference to code checking a given value for validity.
    \item [\texttt{noedit}] marks read-only settings.
    \item [\texttt{default}] defines the default value.
    \item [\texttt{unit}] denotes the (physical) unit of the value specified by this setting.
\end{description}
80
}
Stefan Tauner's avatar
Stefan Tauner committed
81
82
83
84
85
86
87

The static hashes mentioned above are complemented by \texttt{FIJI::Settings} that implements loading saving instances of the \ac{FIJI} settings to actual as well as validating new values (e.g., read from a file or given by a user) etc.
The \texttt{FIJI::Settings} instances returned by the constructor \texttt{new} or the static method \texttt{read\_settingsfile} form the major component of the state of the various \ac{FIJI} programs.

One of the most prominent users of this instance is \texttt{Tk::FIJISettingsViewer} that presents the settings to the user as part of \texttt{fiji\_setup.pl}.
The other tools merely read existing settings file or amend them with additional information (e.g., Design ID is added during instrumentation).

88
89
90
91
92
93
94
95
96
97
98
99
\subsection{FIJI Tests}

The data structure describing test patterns is patterned on the \ac{FIJI} Settings.
The constants used therein are also described in \texttt{FIJI.pm} but the implementation slightly differs and can be found in \texttt{FIJI::Tests}.
The two major differences are:
\begin{itemize}
    \item The rules and data used for validation in the Tests is generated from a \ac{FIJI} Settings instance.
          This allows for validation against the actual design settings instead of some coarse generic rules.
    \item The utility functions differ greatly.\\
          E.g., instead of calculation FPGA resources like in \texttt{FIJI::Settings::estimate\_resources} the functions in \texttt{Tests.pm} are concerned with generating code related to simluations.
\end{itemize}

Stefan Tauner's avatar
Stefan Tauner committed
100
101
102
\subsubsection{FIJI Setup Tool}

\texttt{Tk::FIJISettingsViewer} makes up for the majority of the visible UI of \texttt{fiji\_setup.pl}.
103
Apart from the widgets specifying things like the save location of the settings file on the top it shows several tabs containing controls for most of the \ac{FIJI} Settings.
Stefan Tauner's avatar
Stefan Tauner committed
104
105
The tabs are filled automatically according to the constants described in \Cref{sec:settings_usage} (cf., \texttt{Tk::FIJISettingsViewer::\_populate\_widget}).
Additionally there is a graphical representation of the \ac{FIJI} system that is implemented by \texttt{Tk::FIJISettingsCanvas}.
106
107
108
109
110
111
112
113
114
115
116
The dependency graph of \texttt{Tk::FIJISettingsViewer} is depicted in \Cref{fig:FIJISettingsViewer_8pm__incl}.

\begin{figure}[ht]
    \centering
    \resizebox{\textwidth}{!}{
        \input{content/FIJISettingsViewer_8pm__incl.dot.tex}
    }
    \caption{Dependency graph of \texttt{Tk::FIJISettingsViewer}}
    \label{fig:FIJISettingsViewer_8pm__incl}
\end{figure}

Stefan Tauner's avatar
Stefan Tauner committed
117
118
119
120
121

All settings of type \texttt{net} (representing a net in the Verilog netlist) can be set by a distinct dialog that is represented by \texttt{Tk::FIJINetSelection}.
Another dialog that is not exclusive to \texttt{fiji\_setup.pl} is \texttt{Tk::FIJIModalDialog} that is a simple implementation of a modal dialog that conveniencetly handles buttons and supports images and markup text (used in the about dialog) as well.

\subsection{Instrumentation}
122
\label{sec:instrumentation}
Stefan Tauner's avatar
Stefan Tauner committed
123
124

The components of the Verilog parsing/generation library named Verilog-Perl contained in the various \texttt{Verilog::*} packages form the backbone of \texttt{fiji\_instrument.pl} that instruments the given user design according to the information in the \ac{FIJI} Settings.
125
Support for buses and concatenations had to be added to Verilog-Perl by us and its first version has been merged to upstream in version 3.440.
Stefan Tauner's avatar
Stefan Tauner committed
126
127
128
129
130
131

The interface between Verilog-Perl and \ac{FIJI} is \texttt{FIJI::Netlist} that provides functions to read in Verilog netlists, find drivers of a net and instrumenting nets.
The general idea of the instrumentation process (cf.\ \texttt{FIJI::Netlist::instrument\_net}):

\begin{enumerate}
    \item Retrieve all signals connected to the respective net (\texttt{FIJI::Netlist::\_get\_net\_connections}) including its driver.
132
    \item Create unique, sane identifieres\footnotemark{} for the various new objects to create (e.g., ports to forward \ac{DUT}-internal signals).
Stefan Tauner's avatar
Stefan Tauner committed
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
    \item Forward the original and instrumented signals up/down the hierarchy respectively via newly created ports.
    \item Determine the name for an intermediate net to ease splicing of the instrumented signal (e.g., into single bits of busses).
    \item Split up the instrumented net depending on its driver.
    \begin{enumerate}
        \item If the driver is a~\ldots
            \begin{description}[style=sameline]
                \item[output pin] of a (sub)cell then connect this pin to the intermediate net.
                \item[input port] of the respective cell then create a matching wire for it and connect that to the intermediate net.
                \item[assignment] them replace the \ac{LHS} with the intermediate net.
            \end{description}
        \item Actually create the intermediate net depending on information gathered during the previous step.
        \item Add an assignment from the new input port to the original net thus splicing in the injected signal.
        \item Add another assignment from the driver to the new output port.
    \end{enumerate}
\end{enumerate}
148
149
150
151
152
\footnotetext{
    We denote those identifiers \textit{sane} that have been sanitized by \texttt{FIJI::Netlist::\_sanitize\_identifier}.
    This function transforms all non-alphanumeric characters into underscores while making sure there are no consecutive underscores.
    This guarantees that resulting identifiers are compatible with both Verilog and VHDL compilers.
}
Stefan Tauner's avatar
Stefan Tauner committed
153
154
155
156

All of the steps need to take busses into account and \ac{FIJI} even supports instrumentation of multiple bits of a single bus (with one dedicated \ac{FIU} per bit).

\texttt{FIJI::Netlist} relies on \texttt{FIJI::VHDL} to generate a VHDL wrapper module instantiating \ac{FIJI} logic and the \ac{DUT}, and to create an associated VHDL package file.
Stefan Tauner's avatar
Stefan Tauner committed
157
    
Stefan Tauner's avatar
Stefan Tauner committed
158
159
160
161
162
163
Additionally, \texttt{fiji\_instrument.pl} calculates a design ID each time it exports an instrumented netlist.
This ensures that configuration data sent to the hardware matches the actual design (settings).
To this end it calculates a 16-bit hash value based on the CRC-CCITT algorithm concatenating the following data as input for the hash function:
\begin{itemize}
    \item the unmodified net list (i.e., the content of the Verilog netlist file)
    \item the \ac{FIJI} Settings (i.e., the file contents)
164
    \item the (user-settable) name of the top-level module (wrapper)
Stefan Tauner's avatar
Stefan Tauner committed
165
    \item the (user-settable) file prefix
166
167
\end{itemize}

Stefan Tauner's avatar
Stefan Tauner committed
168
The resulting value is saved as \texttt{ID} into the respective \ac{FIJI} Settings file.
169

170
\subsection{Communication, Protocol Handling and the FIJI Execution Engine}
171

172
173
174
175
All run-time communication with the \ac{DUT} works via the \ac{UART} protocol specified in \Cref{sec:comm_prot}.
The Perl implementation is split into several files.
The part filling a buffer representing the payload as preparation for sending as well as parsing the messages from the \ac{FIC} resides in \texttt{FIJI::Connection} and relies on \texttt{FIJI::AnySerialPort} to be compatible across platforms.
Its \texttt{send\_config} method allows \texttt{FIJI::Downloader} to offer various \texttt{download\_*} methods to classes further up the stack in the \ac{FIJIEE}.
176
177
This class would also be the one to instantiate when one would like to write a custom run-time execution script instead of using the provided applications.
The dependency graph of \texttt{FIJI::Downloader} is depicted in \Cref{fig:Downloader_8pm__incl}.
178
179
180
181
182
183
184
185
186
187

\begin{figure}[ht]
    \centering
    \resizebox{\textwidth}{!}{
        \input{content/Downloader_8pm__incl.dot.tex}
    }
    \caption{Dependency graph of \texttt{FIJI::Downloader}}
    \label{fig:Downloader_8pm__incl}
\end{figure}

188

189
190
191
192
The two available user interfaces of \texttt{fiji\_ee.pl} and \texttt{fiji\_ee\_gui.pl} merely prepare data structures representing test patterns and pass them to the classes mentioned above.
The GUI application is the only truely\footnote{As far as Perl threads are \textit{real} anyway,\\cf.\ \url{http://perldoc.perl.org/perlthrtut.html\#What-kind-of-threads-are-Perl-threads\%3f}} multithreaded application in the framework.
Its \texttt{download\_worker} function is executed in parallel and triggers the actual communication.
It gets its commands from the \texttt{Tk}/main thread via a \texttt{Thread::Queue} and returns its result and log message via the same mechanism as well.
193

194
195
\subsection{Testing}
\label{sec:testing}
196

197
In the following section the contents of the \texttt{test} directory are described.
198

199
\subsubsection{\ac{FIC} Emulator}
200
\label{sec:fic_emulator}
201

202
203
The \ac{FIC} emulator is intended for testing/debugging the \ac{FIJIEE} scripts.
It emulates the \ac{FIJI} \ac{FIC} (Fault Injection Controller) by sending appropriate
204
205
206
207
\texttt{CONF\_DONE} and \texttt{READY} messages. It can also be instructed to send
\texttt{UNDERRUN} messages. Moreover, the UART, ID, and CRC error bits as well as 
fault detect bits can be set at run-time. The \ac{FIC} emulator is written in C.

208
To use the \ac{FIC} emulator, the following prerequisites are necessary:
209
210
211
212
213
\begin{itemize}
    \item A program to create a pair of connected terminals, e.g. socat\footnote{\url{http://www.dest-unreach.org/socat/}}
    \item A terminal supporting the POSIX termios interface (\texttt{tcgetattr()} and \texttt{tcsetattr()}) and ANSI escape sequences
\end{itemize}

214
215
A matching \ac{FIC} Emulator executable needs to be generated for each \ac{FIJI}
configuration. The following parameters in the \ac{FIJI} configuration file (\texttt{*.cfg})
216
217
218
influence the configuration message length and thus the behavior of this program:

\begin{itemize}
219
220
221
    \item \texttt{FIU\_CFG\_BITS}: Bits per \ac{FIU} fault pattern
    \item \texttt{FIU\_NUM}: Number of \acp{FIU}
    \item \texttt{CFGS\_PER\_MSG}: Number of fault patterns for each \ac{FIU} per message
222
223
224
225
226
227
228
    \item \texttt{TIMER\_WIDTH}: Width of the timer values
\end{itemize}

The configuration file can be passed to the Makefile via the variable
\texttt{FIJI\_CFG\_FILE}. The Makefile then parses the constants described above
out of the configuration file.

229
For example, build the \ac{FIC} emulator using:
230
231
232
233
234
235
236

    \texttt{\$ make FIJI\_CFG\_FILE=\textasciitilde/fiji/test\_1/fiji.cfg}

It is also possible to pass the constants directly to the compiler using:

    \texttt{\$ gcc fic-emulator.c -DFIU\_CFG\_BITS=... -DFIU\_NUM=... -DCFGS\_PER\_MSG=... -DTIMER\_WIDTH=...}

237
Once compiled, the \ac{FIC} emulator may be used as follows:
238
239
240
241
242
243
244

\texttt{\$ fic-emulator [-d DEVICE] [-c PERIOD] [-h]}

The command-line options have the following meanings:

\begin{itemize}
    \item \texttt{-d DEVICE} The terminal device to be used, e.g., \texttt{/dev/pts/2}
245
    \item \texttt{-c PERIOD} The \ac{FIC} emulator can be instructed to actually
246
247
248
249
250
251
252
                        wait during the T1/T2 durations. It multiplies the
                        durations with the clock period in microsecond
                        passed with this parameter.
    \item \texttt{-h}   Display a short usage information including the
                        compile-time configuration
\end{itemize}

253
To run the \ac{FIC} emulator, first a pair of pseudo terminals need to be set up.
254
255
256
257
258
This may be done using \texttt{socat} as follows:

    \texttt{\$ socat -d -d pty,raw,echo=0 pty,raw,echo=0}

Then the \ac{FIC} emulator may be launched on one of the terminals.
259

260
When the \ac{FIC} emulator is running, in the status line at the bottom
261
262
the current configuration of the fault detection lines, UNDERRUN, UART, ID, and
CRC error flags can be seen. The configuration can be changed by pressing
263
264
any of the keys shown above the status line. The terminal to which the
emulator is connected is shown at the top.
265

266
\subsubsection{Instrumentation Tests}
267
\label{sec:instrumentation_tests}
268

269
To test our Verilog-Perl changes as well as the instrumentation code (cf.\ \Cref{sec:instrumentation}) we have set up unit tests in \texttt{test/instrument\_test} consisting of minimal netlists (in \texttt{netlists}) and associated \ac{FIJI} Settings (in \texttt{fiji}).
270
These tests cover many different combinations of instrumentation targets and drivers, which helped to find many bugs in corner cases.
271
272
273
274
275
276
277
278
The provided Makefile will execute all \textit{mandatory} test cases, by default in 16 parallel threads.
There are also some optional test cases for Verilog features that have not been observed yet in simple netlists and hence have not been implemented (yet).

The unit tests consist of the following phases.
\begin{description}[]
    \item[Setup] If there exists no \ac{FIJI} Settings file for a respective netlist \texttt{fiji\_setup.pl} will be launched to allow the engineer to choose the instrumented net(s) and possibly set other settings needed for the test.
        If the Settings exist already but are older than the netlist we force make to skip launching the GUI for usability reasons.
    \item[Instrumentation] The netlists are instrumented with \texttt{fiji\_instrument.pl}.
279
280
    \item[Synthesis] The instrumented netlists are quickly checked for syntax errors and the like by synthesizing them with Synplify and filtering out unrelated warnings.
    \item[Simulation] In addition to the syntax check a behavioral simulation tries to find discrepancies between an instrumented and untouched entity of the respective netlist.
281
282
283
    To that end the test instantiates them in a testbench and compares their output when fed some generated input.
    The tests are not exhaustive but very effective since instrumentation bugs usually affect the signal path in a very direct manner.
\end{description}