Commit 913b3ad3 authored by Stefan Tauner's avatar Stefan Tauner
Browse files

TRM: refine Software chapter

parent 30a90f39
......@@ -48,7 +48,7 @@ use Getopt::Long qw(:config bundling);
# undef => classic+menu GUI
use constant USE_MENU => undef;
use FIJI qw(:default :fiji_dir :fiji_documentation_path);
use FIJI qw(:default :fiji_dir);
use FIJI::Tests;
use FIJI::Downloader;
use Tk::FIJITestsViewer;
......@@ -322,7 +322,6 @@ sub main {
$mw->toplevel()->bind("<Control-q>" => sub { $self->_onexit(); });
$mw->toplevel()->bind("<F1>" => sub { Tk::FIJIUtils::show_documentation($mw); });
$self->{'documentation_path'} = File::Spec->catfile($ugdir, 'fiji_user_guide.pdf');
$self->{'FIJITestsViewer'} = $mw->FIJITestsViewer(
-changes_callback => sub { my $value = shift; _indicate_changes($self, $value) },
-test_callback => sub { my $value = shift; $self->{'export_menuentry'}->configure(-state => ($value > 0) ? "normal" : "disabled")},
......
......@@ -3,3 +3,6 @@
The target audience of this documents are engineers that want to understand or tinker with the inner workings of the \ac{FIJI} suite.
The technical details contained herein are supposed to be irrelevant to ordinary users.
The reader is expected to be familiar with the goal and application of \ac{FIJI} as explained in the accompanying \hyperref[UG:first_page]{\ac*{UG}}.
Besides the information in the \ac{UG} and within this file some documentation can be generated with Doxygen from comments in the source code of the Perl scripts.
See the \ac{FIJI} \texttt{README.md} how to generate them.
\section{Software}
\label{sec:flow}
This chapter sums up some underlying facts of the scripts used in the \ac{FIJI} framework.
This chapter sums up some concepts of the Perl classes used in the \ac{FIJI} framework.
Their use in the complete tool flow and the respective interfaces to the vendor tools are described in detail in \Cref{UG:sec:flow} of the \ac{UG}.
You should consult the Doxygen documentation and source files for the details beyong the overview given below.
\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).
The \ac{FIJI} Settings are organized in blocks of key-value pairs represented in the same format as common \texttt{.ini} files:
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:
\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;
\item the keys on the left side are separated by (the first) equal sign (=) from the values on the right side.
\item the keys on the left side are separated by (the first) equal sign (\texttt{=}) from the values on the right side.
\end{itemize}
There are two major types of blocks allowed:
There are two major types of blocks allowed in \ac{FIJI} Settings:
\begin{itemize}
\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>}
\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>}
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}
Table~\ref{tab:consts} lists all specifiable constants for a design, while
Table~\ref{tab:fiuconsts} explains the settings for each \ac{FIU}. The ``Name''
\Cref{tab:consts} lists all specifiable constants for a design, while
\Cref{tab:fiuconsts} explains the settings for each \ac{FIU}.
The ``Name''
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.
Additionally, the literals used to specify the available fault models at runtime are listed in \Cref{tab:faultmodels}.
\begin{table}
\caption{Design Constants}
\input{content/tab_design_consts.tex}
......@@ -52,53 +56,94 @@ by the tools if no value is available when one is needed but not available.
\label{tab:faultmodels}
\end{table}
\subsection{FIJI Setup Tool}
The \ac{FIJI} Settings file (usually named \texttt{fiji.cfg}) serves as intermediate
storage for the parameters and is read by the various tools of the framework.
It is normally created by \texttt{fiji\_setup.pl} from the synthesized netlist of
the user design and input from the user. It acquires information about
the DUT and the to be inserted faults by querying the engineer for the
following data:
\begin{itemize}
\item Design settings:
\begin{itemize}
\item Name of the clock net within the DUT to be used as input for the FIC and its frequency,
\item UART baud rate,
\item Name for serial RX and TX signals,
\item Width of the timer (determining the maximum time spans of the t1 and t2 durations),
\item Width, polynomial, seed of the \ac{LFSR} that is used to generate pseudo randomness,
\item Activation, polarity, name of the external reset,
\item Activation, polarity, name of the DUT-to-FIC reset signal,
\item Activation, polarity, name, duration of the FIC-to-DUT reset signal,
\item Activation, polarity, name of the internal trigger input,
\item Activation, polarity, name of the external trigger input,
\item Activation, polarity, names of the two fault detection signals,
\item the used ``FPGA Implementation'' tool.
\end{itemize}
\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:
\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}
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).
\subsubsection{FIJI Setup Tool}
\texttt{Tk::FIJISettingsViewer} makes up for the majority of the visible UI of \texttt{fiji\_setup.pl}.
Apart from the widgets on the top it shows several tabs containing controls for most of the \ac{FIJI} Settings.
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}.
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}
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.
Support for buses and concatenations had to be added to Verilog-Perl by us and is currently in the process of being upstreamed.
Until this is complete you have to use our fork available from \fixme{add link to github or es}.
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.
\item Create unique, sane identifieres for the various new objects to create (e.g., ports to forward \ac{DUT}-internal signals).
\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}
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.
\item For each ``faulty'' net (thereby specifying the number of \acp{FIU})
\begin{itemize}
\item Net name
\item Net driver
\item Available fault models: all 5 fault models or only a single (selectable) one of them (cf.\ \Cref{tab:faultmodels})
\item Bits of the global \ac{LFSR} which should be ANDed to generate the random signal in stuck-open mode
\end{itemize}
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)
\item the (user-settable) name of the toplevel module (wrapper)
\item the (user-settable) file prefix
\end{itemize}
The detailed specification of the values and syntax of the \ac{FIJI} Settings
can be found in Section~TODO. Any module-specific parameters (e.g. generics
for hardware modules) are described within the respective chapters later.
The resulting value is saved as \texttt{ID} into the respective \ac{FIJI} Settings file.
\subsection{FIJI Instrumentation Tool}
\subsection{Communication and Protocol Handling}
The next tool in the flow is \texttt{fiji\_instrument.pl} that instruments the given
user design according to the information in the \ac{FIJI} Settings. \todo{TBC}
Additionally, the script calculates a design ID each time it creates a
new netlist. This ensures that configuration data sent to the hardware
matches the actual design. To this end it calculates a 16-bit hash value
with the \ac{FIJI} Settings and the unmodified net list as input (\todo{how exactly}).
Appropriate constraints are added to prevent unwanted optimizations that would interfere with the introduced faults.
\todo{upon instrumentation, launch Synplify for further processing...}
\todo{Document}
\subsection{FIJI Tests}
\todo{Document}
\subsection{FIJI Execution Engine}
......@@ -134,14 +179,6 @@ support three modes:
\end{enumerate}
\subsection{Documentation}
Besides the information within this file some documentation can be
generated with Doxygen from comments in the source code by executing
``doxygen Doxyfile''. For this to work Doxygen and the filter package
mentioned in Table~\ref{tab:perlmod} need to be installed. By default
only HTML output is created as specified in the configuration file Doxyfile.
\subsection{Testing}
\label{sec:testing}
......
......@@ -17,7 +17,7 @@ and the fault injection units (see Section~\ref{sec:hw_fiu}).
The \texttt{fault\_injection\_top} module is intended to be configured and instantiated
by \texttt{fiji\_instrument.pl} when generating the wrapper module for the modified
netlist. This configuration is done by assigning the desired values to
the constants located in \texttt{public\_config\_pkg} as described in Table~\ref{tab:vhdl_consts}.
the constants located in \texttt{public\_config\_pkg} as described in \Cref{tab:vhdl_consts}.
Both the number of fault injection units and their configuration are
passed in \texttt{c\_fiu\_config} whose type \texttt{t\_fiu\_records} is an array of \texttt{t\_single\_fiu\_record}
defined in the VHDL package \texttt{public\_config\_pkg.vhd}. The described fault
......
......@@ -5,6 +5,7 @@
\acro{FIJI}{Fault InJection Instrumenter}
\acro{FIU}{Fault Injection Unit}
\acro{LFSR}{Linear Feedback Shift Register}\glsunset{LFSR}
\acro{LHS}{Left-Hand Side}\glsunset{LHS}
\acro{LOC}{Lines Of Code}
\acro{LUT}{Look-up Table}
\acro{SEU}{Single Event Upset}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment