Commit 4dd72845 authored by Stefan Tauner's avatar Stefan Tauner
Browse files

Refine user manual apart from use case chapter

parent 2d07c399
......@@ -127,7 +127,11 @@ Also, make sure that you have the \texttt{DISPLAY} environment variable set corr
The major obstacle to install FIJI for a native Perl interpreter is the building of Verilog-Perl and other packages not included by the respective interpreter package distribution.
Recent versions of ActivePerl do not come with \texttt{dmake} without an extra license at all, breaking many packages.
Strawberry Perl
Strawberry Perl on the other hand comes with \texttt{dmake} and allows to install all dependencies apart from Verilog-Perl easily.
To compile the latter however at least some changes to the build scripts are required.
The 32-bit version of both Perl distributions work fine with \ac{FIJIEE} to control the actual fault injection in realtime.
There is currently a bug in the 64-bit version of the Perl libraries used to access serial ports that renders these version unsuitable to do anything meaningful in the context of \ac{FIJI} at the moment.
\subsection{Repository Contents}
......@@ -139,8 +143,9 @@ All source code to be executed on a host PC including customized Perl libraries
Documentation including a demo project, the technical reference manual and this very document can be found in \texttt{docs}.
\texttt{hw} contains the VHDL code implementing the \ac{FIC}, \acp{FIU}, UART etc.\ and the respective test benches and simulation scripts.
Media files like logos and icons are found in \texttt{media}.
The \texttt{test} directory comprises tools and data used for testing \ac{FIJI}.
\begin{figure}[ht]
\begin{figure}[!ht]
\centering
\input{img/fiji_dirs}
\caption{\ac{FIJI} Directory Structure}
......
......@@ -12,11 +12,11 @@ Although \textit{\ac{FIJI} Setup} is a graphical tool, it accepts the
following \emph{optional} command-line arguments:
\begin{itemize}
\item \texttt{-s, {-}{-}settings-file=<filename>}
\item \texttt{-s, {-}{-}settings=<filename>}
Specifies a \textit{\ac{FIJI} Settings} file to load at startup
\item \texttt{-n, {-}{-}netlist-file=<filename>}
\item \texttt{-n, {-}{-}netlist=<filename>}
Specifies a netlist file to load at startup
......@@ -40,20 +40,19 @@ for selecting different categories of values to be entered, (3) the
\begin{figure}[ht]
\centering
\input{img/fiji_setup_screenshot_marked}
%\includegraphics[width=0.85\linewidth]{img/\ac{FIJI}_setup_screenshot.png}
\caption{\ac{FIJI} Setup Tool}
\label{fig:setup}
\end{figure}
\subsection{Control Area and Menu Bar}
Using the \textit{Control Area}, file operations can be performed:
The user can select to load a \textit{\ac{FIJI} Configuration} file from disk
or save the current configuration to a file. Additionally, a Verilog
netlist file can be loaded.
These actions can be performed both via the buttons in the \textit{Control
Area} and the Menubar 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 retrieved.
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.
Upon startup, when no configuration file is specified via command-line
options, \textit{\ac{FIJI} Setup} starts with the \textit{Default Configuration}.
......@@ -65,45 +64,46 @@ edited manually using a text editor.
A netlist must be loaded to perform netlist-related tasks
(choosing nets, pin names, and drivers). When a netlist is loaded, \ac{FIJI}
analyzes the contained Verilog modules and builds an internal representation
using Perl objects. Thus, larger netlists may take a while to load. During
analyzes the contained Verilog modules and builds an internal representation.
Thus, larger netlists may take a while to load. During
this time, a loading screen barring the user from interaction with the
GUI is displayed.
\subsection{Tabs and Main Area}
For clarity, the GUI separates the different configuration topics into
different \textit{Tabs}. The following topics are available for
configuration:
\begin{itemize}
\item \textbf{General Settings}
\begin{description}
\item[General Settings]
Settings for the instrumentation and synthesis process,
as well as settings for the serial communication between \ac{FIJI} and host
and the fault injection timers are subsumed under this tab.
\item \textbf{Clock Settings}
\item[Clock Settings]
The \textit{\ac{FIJI}} fault injection logic is clocked from the
clock of the clock domain in the \ac{DUT} where faults are injected.
The \textit{\ac{FIJI}} fault injection logic is clocked from a clock domain in the \ac{DUT} where faults are injected.
The name and frequency of this clock net need to be specified.
\item \textbf{\acs{LFSR} Settings}
\item[\acs{LFSR} Settings]
\textit{\ac{FIJI}} emulates floating nets caused by \textit{Stuck-open}
\textit{\ac{FIJI}} emulates floating nets caused by \textit{stuck-open}
faults by forcing pseudo-random binary levels onto the respective
net. These levels are derived from the value of a \textit{Linear
Feedback Shift Register}. In this tab, the width, polynomial,
net. These levels are derived from the value of a \textit{\ac{LFSR}}.
In this tab, the width, polynomial,
and starting value of this register can be configured.
See \ref{sec:lfsrtable} for a list of complete \ac{LFSR} polynomials
for different lengths.
\item \textbf{External Reset}
\item[External Reset]
The \ac{FIJI} logic can be configured to be reset from an external
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.
\item \textbf{Reset from \acs{DUT} to \ac{FIJI}}
\item[Reset from \acs{DUT} to \ac{FIJI}]
In addition to the external reset via pin, also any net of the
\ac{DUT} can be used to reset the \ac{FIJI} logic. This feature can be
......@@ -116,7 +116,7 @@ configuration:
\ac{FIJI} are enabled, the reset sources are ORed together and used
as the \ac{FIJI} logic's asynchronous reset signal.
\item \textbf{Reset from \ac{FIJI} to \acs{DUT}}
\item[Reset from \ac{FIJI} to \acs{DUT}]
In contrast to the feature described above, the \ac{FIJI} logic can
also be used as a source for a reset net in the \ac{DUT}.
......@@ -126,7 +126,7 @@ configuration:
the polarity, target net name, and desired reset pulse duration
must be entered.
\item \textbf{Trigger Settings}
\item[Trigger Settings]
In order to support dynamic test execution depending on
events external to \ac{FIJI}, trigger signals can be used to
......@@ -138,21 +138,20 @@ configuration:
For both the internal and the external trigger facilities,
the respective pin or net name and polarity must be specified.
\item \textbf{Fault Detection Settings}
\item[Fault Detection Settings]
The value of up to two nets in the \ac{DUT} can be communicated back to the
host as a means for fault detection. The names and \textit{error}
host as a means for fault detection. The names and error
levels of these nets need to be specified when they are used.
\item \textbf{\acfp{FIU}}
\item[\acfp{FIU}]
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
be added. Each \ac{FIU} has an associated net, a driver for this net,
and fault injection capabilities to be configured.
\end{itemize}
\end{description}
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
......@@ -189,15 +188,18 @@ the \textit{Select} button next to the net entry field (1).
An example for this dialog is shown in Figure~\ref{fig:netsel}. The entry field across
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 }''}.
A hierarchical path shall be constructed as follows:
\begin{minipage}{\textwidth}
A hierarchical path shall be constructed as follows in Extended Backus-Naur Form:
\begin{verbatim}
<hierarchical-path> ::= <top> "/" <net> | <top> <cell-list> "/" <net>
<cell-list> ::= "/" <cell> | <cell-list> "/" <cell>
<top> ::= Toplevel module name
<net> ::= Net name
<cell> ::= Cell name
hierarchical-path = top, "/", { cell-list }, net;
cell-list = { cell-list }, cell, "/";
top = ? Toplevel module name ?;
net = ? Net name ?;
cell = ? Cell name ?;
\end{verbatim}
\smallskip
\end{minipage}
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.
......@@ -239,7 +241,7 @@ bit mask at most as wide as the \ac{LFSR}. The bits of the
resulting in the ``floating'' value of the
corresponding net.
\subsection{Statusbar: Resources and Navigation}
At the bottom of the user interface (see Figure~\ref{fig:setup}),
the \textit{Resource Panel} (4) displays the combinational resources
......@@ -248,8 +250,7 @@ configuration \emph{in relation to the default configuration}.
Absolute resource numbers for different FPGA families are shown
in Table~\ref{tab:resources}.
Within the \textit{Button Panel} (5), the \text{Next} and \textit{Back}
buttons provide additional navigation through the tabs. The \textit{Open
Documentation} button displays this document in a PDF reader.
buttons provide additional navigation through the tabs.
Alternatively, a \textit{\ac{FIJI} Configuration} can be created manually using
......
......@@ -6,9 +6,10 @@ tool.
Its main task is to actually perform the modifications of the \ac{DUT} netlist
specified in the \ac{FIJI} configuration file. For each \texttt{[\acs{FIU}$n$]} entry
in this file, it breaks up the corresponding net in an \textit{original}
and a \textit{modified} net, routes these nets to the toplevel, and creates
in this file, it breaks up the corresponding net into an \textit{original}
and a \textit{modified} net, routes these nets to the existing toplevel entity, and creates
an output and input for them, respectively.
The resulting modified netlist is saved into a new file as Verilog netlist.
Additionally, both a VHDL configuration package defining constants used
in the fault injection hardware HDL design, and a wrapper entity instantiating
......@@ -23,27 +24,27 @@ The \textit{\ac{FIJI} Instrumentation} tool is a command-line tool. It accepts
the following parameters and switches:
\begin{itemize}
\item \texttt{-s, {-}{-}\ac{FIJI}-settings-file=<filename>}
\item \texttt{-s, {-}{-}settings=<filename>}
Specifies the path to the settings file for which to instrument
the original netlist.
Specifies the path to the settings file generated by \textit{\ac{FIJI} Setup}.
This parameter is \emph{required}.
\item \texttt{-n, {-}{-}netlist-file=<filename>}
\item \texttt{-n, {-}{-}netlist=<filename>}
Specifies the path to the original netlist file to be instrumented.
Only Verilog-based netlists are supported.
This parameter is \emph{required}.
\item \texttt{-p, {-}{-}file-prefix=<prefix>}
Changes the filename prefix for all generated files.
This parameter is \emph{optional}.
If it is not specified, the module name of the toplevel in the \ac{DUT} netlist used.
If it is not specified, the module name of the toplevel in the \ac{DUT} netlist is used.
\item \texttt{-o, {-}{-}output-dir=<path>}
Changes the directory where the generated files are put to
the specified path. This option takes precedence over the
Specifies the directory where the generated files are saved to.
This option takes precedence over the
\texttt{OUTPUT\_DIR} value specified in the \ac{FIJI} configuration file.
If the specified directory does not exist, it will be created.
This parameter is \emph{optional}.
......@@ -58,4 +59,3 @@ the following parameters and switches:
Displays usage information on the terminal and exits
\end{itemize}
......@@ -5,7 +5,7 @@
After instrumentation, the instrumented netlist and the HDL description
of the fault injection logic have to be combined into one netlist for
FPGA implementation. To that end, the following steps have to be observed:
FPGA implementation. To that end, the following steps have to be taken:
\begin{enumerate}
\item Create a project in the synthesis tool
......@@ -13,22 +13,22 @@ FPGA implementation. To that end, the following steps have to be observed:
device for which the original netlist was generated
\item Add as source files:
\begin{itemize}
\item The modified \ac{DUT} netlist
\item The generated VHDL file containing the configuration package
\item The generated VHDL file containing the wrapper entity
\item The VHDL sources of the fault injection logic (located in \texttt{\$FIJI\_ROOT/hw/rtl/})
\item the modified \ac{DUT} netlist (\texttt{*\_instrumented.vqm})
\item the generated VHDL file containing the configuration package (\texttt{*\_config\_pkg.vhd})
\item the generated VHDL file containing the wrapper entity (\texttt{*\_wrapper.vhd})
\item the VHDL sources of the fault injection logic (located in \texttt{\$FIJI\_ROOT/hw/rtl/})
\end{itemize}
\item Set the name of the wrapper entity as top-level entity
\item Set the name of the wrapper entity as top-level entity (\texttt{wrap} of type \texttt{fiji\_top}).
\item Add any \textit{synthesis} constraint files existing from the
original synthesis project and adapt paths to HDL modules in the
original synthesis project and adapt their paths to HDL modules in the
\ac{DUT} as necessary (one layer of hierarchy will be added as the
module is instantiated by the wrapper VHDL entity)
module is instantiated by the wrapper VHDL entity).
\item Optionally, add the \textit{synthesis} constraints file generated
by the \textit{\ac{FIJI} Instrumentation} tool. The constraints in
this file attempt to enforce the cross-hierarchy optimization
level between the fault injection logic and the generated \ac{DUT}
netlist (See \ref{sec:preventing_optimizations})
\item Optionally, add any additional \textit{synthesis} constraints
netlist (See \ref{sec:preventing_optimizations}).
\item Optionally, add any additional \textit{synthesis} constraints.
\end{enumerate}
\subsubsection{Preventing Optimizations}
......@@ -47,14 +47,14 @@ has changed are resynthesized.
Thus, to prevent cross-boundary optimization and resynthesis of the \ac{DUT} netlist,
a compile point has to be defined for the instantiated \ac{DUT}.
To do this via the Synplify GUI, the following steps have to be observed:
To do this via the Synplify GUI, the following steps have to be executed:
\begin{enumerate}
\item Create the project and implementation, and add all source files
including the \ac{DUT} netlist
\item Synplify needs to parse the design's hierarchy. Thus, perform
\textit{Compile only} \keystroke{F7}.
\item Afterwards, open the SCOPE constraints editor (e.g., be double-clicking
on the \texttt{fdc} file where the constraints shall be added)
on the \texttt{*.fdc} file where the constraints shall be added)
\item In the \textit{Compile Points} tab, add a new compile point:
\begin{enumerate}
\item Double-click in the \textit{View} field in an empty row
......@@ -78,15 +78,13 @@ found. It can be omitted if the \ac{DUT} is compiled into the \texttt{work} libr
When the \textit{Optimizations} setting in the \textit{\ac{FIJI} Setup} tool
(see Section~\ref{sec:setup}) is set to \texttt{OPTIMIZATION\_OFF} or \texttt{FIX\_PLACEMENT},
\textit{\ac{FIJI} Instrument} generates an ``.fdc'' template constraints file for Synplify.
\textit{\ac{FIJI} Instrument} generates a \texttt{*\_constraints.synplify.fdc} file for Synplify.
This file contains the necessary constraints to prevent cross-boundary optimization
between the fault injection logic and the logic in the \ac{DUT} netlist. In order to
use the constraints contained in this file, it needs to be added as a source
file to the Synplify project and activated in the ``Implementation Options``.
The file is written to the output directory, where also the instrumented netlist file is placed.
\subsection{Place and Route}
\label{sec:place_and_route}
......@@ -141,7 +139,7 @@ This can be achieved using location constraints in the FPGA vendors'
P\&R tools, although names and exact definition processes vary across
different tools.
\paragraph{Altera Quartus}~\\
\paragraph{Altera Quartus}\hfill\\
To fix the physical placement of a (sub)hierarchy in Altera Quartus,
perform the following steps in the Quartus GUI:
......@@ -167,7 +165,7 @@ perform the following steps in the Quartus GUI:
\textit{LogicLock Regions Window}. The fitter will
issue an error message if the selected region is too
small or does not contain enough special resources (e.g., BRAMs
or \textit{DSP Blocks})
or \textit{DSP Blocks}).
\item After a complete compilation run, Quartus has determined
the area requirement for the current fit, and set the height,
width, and origin for the \textit{floating} region automatically.
......@@ -177,7 +175,7 @@ perform the following steps in the Quartus GUI:
\end{itemize}
\end{enumerate}
\paragraph{Xilinx Vivado}~\\
\paragraph{Xilinx Vivado}\hfill\\
To fix the physical placement of a (sub)hierarchy in Xilinx Vivado,
perform the following steps in the Vivado GUI:
......@@ -187,10 +185,10 @@ perform the following steps in the Vivado GUI:
synthesis process) as a source file.
\item Open the \textit{Synthesized Design} perspective.
\item In the \textit{Netlist} tab, right-click on the top-level entity
if the \ac{DUT} netlist (\texttt{i\_DUT})
of the \ac{DUT} netlist (\texttt{i\_DUT}).
\item In the context menu, navigate to \textit{Floorplanning} and
select \textit{New Pblock}. A Pblock is Xilinx Vivado's equivalent
to a \textit{LogicLock Region}.
to Altera's \textit{LogicLock Region}.
\item In the menu bar, navigate to \textit{Tools $\rightarrow$ Floorplanning}
and execute \textit{Place Pblocks}. This will use the information
from the netlist to generate appropriately sized FPGA regions
......@@ -209,8 +207,7 @@ perform the following steps in the Vivado GUI:
can be viewed. In the \textit{Rectangles} tab, the position
and size of the Pblock can be changed manually.
\end{enumerate}
\item The location of the Pblock can also be changed in the device's
floorplan.
\item Optionally, the location of the Pblock can also be changed in the device's floorplan.
\end{enumerate}
\subsubsection{Constraints Export}
......@@ -218,11 +215,8 @@ perform the following steps in the Vivado GUI:
When the \textit{Optimizations} setting in the \textit{\ac{FIJI} Setup} tool
(see Section~\ref{sec:setup}) is set to \texttt{FIX\_PLACEMENT},
\textit{\ac{FIJI} Instrument} generates template constraints files for
the selected P\&R tool (``.qsf'' for Altera Quartus, ``.xdc'' for Xilinx Vivado).
the selected P\&R tool (\texttt{*.qsf} for Altera Quartus, \texttt{*.xdc} for Xilinx Vivado).
These files contain the necessary directives to set up a physical partition for the
\ac{DUT} entity. They can either be imported into the P\&R tool directly or copied
manually to a central constraints file.
The files are written to the output directory, where also the instrumented netlist file is placed.
This diff is collapsed.
......@@ -55,13 +55,13 @@ switch position of SW1 -- FPGA0, an interrupt to the microcontroller is generate
\end{itemize}
\subsubsection{Run setup}
\begin{verbatim}
$ perl fiji_setup.pl --settings-file mc8051_demo/fiji_test_1/fiji.cfg \
--netlist-file=mc8051_demo/synp/fpga_top.vqm
$ perl fiji_setup.pl --settings mc8051_demo/fiji_test_1/fiji.cfg \
--netlist=mc8051_demo/synp/fpga_top.vqm
\end{verbatim}
\subsection{Instrumentation}
\begin{verbatim}
$ perl fiji_instrument.pl --fiji-settings-file=mc8051_demo/fiji_test_1/fiji.cfg \
--netlist-file=mc8051_demo/synp/fpga_top.vqm \
$ perl fiji_instrument.pl --settings=mc8051_demo/fiji_test_1/fiji.cfg \
--netlist=mc8051_demo/synp/fpga_top.vqm \
--file-prefix=fiji_demo
\end{verbatim}
\subsection{Implementation}
......
......@@ -18,6 +18,8 @@
\usepackage[T1]{fontenc}
\usepackage[ngerman,english]{babel}
\usepackage{enumerate}
\usepackage[shortlabels]{enumitem}
\setlist[description]{style=nextline}
\usepackage{keystroke}
\usepackage{textcomp}
......
......@@ -44,5 +44,11 @@
child [missing] {}
child [missing] {}
child [missing] {}
child { node {media}};
child { node {media}}
child [missing] {}
child { node {test}
child { node {fic\_emulator}}
child { node {instrument\_test}}
}
;
\end{tikzpicture}
Supports Markdown
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