02-installation.tex

\section{Installation}
\label{sec:installation}

\subsection{Prerequisites}

The prerequisites for running the \textit{\ac{FIJI}} fault injection tool flow are
listed in \Cref{tab:prerequisites} alongside the version of the respective software \ac{FIJI} was
initially tested with. This does not include the Perl modules that need to be installed,
which can be found in \Cref{tab:perlmod}.

\begin{table}[ht]
    \caption{Software prerequisites for \ac{FIJI}}
    \label{tab:prerequisites}
    \centering
    \begin{tabular}{llll}
        \toprule
        Category                 & OS                  & Name              & Version       \\
        \midrule
        Perl Interpreter         & Unix/Linux          & Perl              & v5.22.1       \\
                                 & Windows             & ActivePerl        & v5.16.3       \\
        FPGA Synthesis Tool      & Unix/Linux, Windows & Synopsys Synplify & I-2013.09-SP1 \\
        FPGA Implementation Tool & Unix/Linux, Windows & Altera Quartus II & 13.0          \\
                                 & Unix/Linux, Windows & Xilinx Vivado     & 2016.1        \\
        \bottomrule
    \end{tabular}
\end{table}

\begin{table}[ht]
    \caption{Perl Modules required by \ac{FIJI}}
    \label{tab:perlmod}
    \centering
    \begin{tabular}{llll}
        \toprule
        Module                & Description                       &  \ac{FIJI} Tool \\
        \midrule
        Clone                 & Deep object copy                  & All tools \\
        Config::Simple        & Configuration file handling       & All tools \\
        Sort::Naturally       & Natural sorting of alphanumerics  & All tools \\
        enum                  & Enumerated types                  & All tools \\
        Win32::SerialPort     & Serial port interface for Windows & \textit{\acs{FIJIEE}} \\
        Device::SerialPort    & Serial port name mapping          & \textit{\acs{FIJIEE}} \\
        Digest::CRC           & CRC calculation                   & \textit{Instrument}, \textit{\acs{FIJIEE}} \\
        Doxygen::Filter::Perl & Doxygen documentation             & For documentation only \\
        Log::Log4Perl         & Logging framework                 & All tools \\
        Log::Dispatch::FileRotate & Automatic log rotation        & All tools \\
        Log::Dispatch::Output & Base for custom log appenders     & \textit{\acs{FIJIEE} GUI} \\
        Params::Validate      & Validation of parameters          & \textit{\acs{FIJIEE} GUI} \\
        Scalar::Util          & Various numeric helpers           & All tools \\
        Test::Deep            & Deep hash comparison              & \textit{Setup}, \textit{\acs{FIJIEE} GUI} \\
        Time::HiRes           & High-resolution timing            & \textit{Setup}, \textit{\acs{FIJIEE}} \\
        Tk                    & GUI library                       & \textit{Setup}, \textit{\acs{FIJIEE} GUI} \\
        Tk::StatusBar         & StatusBar widget for Tk           & \textit{Setup}, \textit{\acs{FIJIEE} GUI} \\
        Verilog::Language     & Verilog parser/generator          & \textit{Setup}, \textit{Instrument} \\
        \bottomrule
    \end{tabular}
\end{table}

\subsubsection{Linux}
\label{sec:verilog-perl-install}

Linux distributions often have Perl interpreters installed by default and we recommend to use the one shipped with the distribution.
The availability of Perl packages varies greatly among distributions but if they are available in the distribution's repository the probably should work fine.
The only exception is Verilog-Perl that was modified quite significantly during the project and is unlikely to include our changes already in any distribution.
The minimum version required is 3.442.

To build it from source you would need the typical build utilities like \texttt{g++}, \texttt{bison}, \texttt{flex} and \texttt{make}.
The installation can be done via CPAN or manually as documented at \url{https://www.veripool.org/projects/verilog-perl/wiki/Installing}.

The remaining Perl packages should be available from the distributor in a suitable version.
However, \ac{FIJI} also comes with a script to install all required Perl packages (including Verilog-Perl) from CPAN as well.
It is contained in \texttt{bin/install\_prerequisites.sh}.

\subsubsection{Windows}

On Windows there are basically three ways to use \ac{FIJI}:
\begin{enumerate}
    \item via Cygwin
    \item via a native Perl interpreter (e.g., \textit{Strawberry Perl})
    \item via a virtual machine (e.g., \textit{VirtualBox})
\end{enumerate}

Due to the limitations of the Perl environment in Windows we recommend to use FIJI on Windows for evaluation purposes only.
While the other two ways are theoretically possible this guide does only show how to install \ac{FIJI} in Cygwin.

For Cygwin the installation works similar to that of a native Linux distribution.
Additionally to the given tools you will also need a working X server to display any FIJI GUIs.
If you have downloaded the Cygwin setup executable (for 64-bit Windows) to the current directory the following command should install all necessary packages:
% hint: this was found with the help of cygcheck -c

\begin{lstlisting}
setup-x86_64.exe -q -P gcc-g++,make,flex,bison,pkg-config,xorg-server,perl,perl-Carp,perl-Error,perl-Scalar-List-Utils,perl-Log-Log4perl,perl-Tk,perl-Clone,perl-Params-Validate,perl-Scalar-List-Utils,perl-Test-Deep
\end{lstlisting}

After that the following Perl packages remain to be installed from CPAN:
\begin{itemize}
    \item enum
    \item Log::Dispatch::Output
    \item Log::Dispatch::FileRotate
    \item Config::Simple
    \item Digest::CRC
    \item Doxygen::Filter::Perl
    \item Sort::Naturally
    \item Tk::StatusBar
\end{itemize}

That can be handled with the following command within a Cygwin shell.
\begin{lstlisting}
perl -MCPAN -e "CPAN::Shell->notest('install', 'enum', 'Log::Dispatch::Output', 'Log::Dispatch::FileRotate', 'Config::Simple', 'Digest::CRC', 'Doxygen::Filter::Perl', 'Sort::Naturally', 'Tk::StatusBar')"
\end{lstlisting}

Finally, you need also to install Verilog-Perl as shown in \Cref{sec:verilog-perl-install}.

When everything is set up you should be able to launch any FIJI script from a Cygwin shell.
The GUI applications (e.g., \textit{FIJI Setup}) require a running X server before launch.
To that end you can start one in the background with
\begin{lstlisting}
run -p /usr/X11R6/bin XWin -multiwindow -clipboard -silent-dup-error &
\end{lstlisting}

Also, make sure that you have the \texttt{DISPLAY} environment variable set correctly (e.g., \lstinline{DISPLAY=:0.0}).

\paragraph{Strawberry Perl \& ActivePerl}

\begin{wrapfigure}{R}{0.45\textwidth}
% \vspace{-2cm}
\centering
\resizebox{!}{0.85\textwidth}{ % beware, the second parameter is actually the height
\input{img/fiji_dirs}
}
\caption{\ac{FIJI} Directory Structure}
\label{fig:fijidir}
\vspace{-0.12\textwidth} % bottom white space hack
\end{wrapfigure}

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 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}

Since \ac{FIJI} is written in Perl there is no need (and no proposed way) to install it onto a system.
Simply checking out the source code repository and loading the respective scripts in a Perl interpreter should be enough to use it.
To help you navigate within the repository the directory structure is shown in \Cref{fig:fijidir} and explained below.

All source code to be executed by the user on a host PC including customized Perl libraries resides in \texttt{bin}.
This includes also the 4 main scripts already mentioned needed in the \textit{setup}, \textit{instrumentation} and \textit{execution} steps of the workfow.

Documentation including demo projects, 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.\ (in \texttt{rtl}) and the respective test benches (in \texttt{tb}) and simulation scripts (in \texttt{sim}).
Media files like logos and icons are found in \texttt{media}.

The \texttt{test} directory comprises tools and data used for testing \ac{FIJI} including a software emulation of the \ac{FIC} and unit tests for the instrumentation code.
Details about testing are described in the \ac{TRM}'s \Cref{TRM:sec:testing}.

\subsubsection{Logging}

All \ac{FIJI} scripts write important messages to the respective terminal (if available) and tool-specific log files.
The log files are saved to \texttt{bin} and get rotated every day (or when one reaches 100\,MB).
Additionally, \acs{FIJIEE} displays them within its GUI and passes them to a user-defined script for reporting/archiving etc.
In the setup step the path of the log file used during instrumentation can be set individually.

The format, verbosity and many other aspects of the logging can be configured in the file \texttt{logger.conf} in the \texttt{bin} directory (see the documentation of \texttt{Log::Log4perl} for details).