02-installation.tex 9.56 KB
Newer Older
Stefan Tauner's avatar
Stefan Tauner committed
1
\section{Installation}
2
\label{sec:installation}
Stefan Tauner's avatar
Stefan Tauner committed
3
4

\subsection{Prerequisites}
Christian Fibich's avatar
Christian Fibich committed
5

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

11
\begin{table}[ht]
Christian Fibich's avatar
Christian Fibich committed
12
    \caption{Software prerequisites for \ac{FIJI}}
Christian Fibich's avatar
Christian Fibich committed
13
    \label{tab:prerequisites}
14
15
16
17
18
19
    \centering
    \begin{tabular}{llll}
        \toprule
        Category                 & OS                  & Name              & Version       \\
        \midrule
        Perl Interpreter         & Unix/Linux          & Perl              & v5.22.1       \\
20
                                 & Windows             & ActivePerl        & v5.16.3       \\
21
22
        FPGA Synthesis Tool      & Unix/Linux, Windows & Synopsys Synplify & I-2013.09-SP1 \\
        FPGA Implementation Tool & Unix/Linux, Windows & Altera Quartus II & 13.0          \\
23
                                 & Unix/Linux, Windows & Xilinx Vivado     & 2016.1        \\
24
25
        \bottomrule
    \end{tabular}
Christian Fibich's avatar
Christian Fibich committed
26
27
\end{table}

28
\begin{table}[ht]
Christian Fibich's avatar
Christian Fibich committed
29
    \caption{Perl Modules required by \ac{FIJI}}
Christian Fibich's avatar
Christian Fibich committed
30
    \label{tab:perlmod}
31
32
33
    \centering
    \begin{tabular}{llll}
        \toprule
34
        Module                & Description                       &  \ac{FIJI} Tool \\
35
        \midrule
36
37
        Clone                 & Deep object copy                  & All tools \\
        Config::Simple        & Configuration file handling       & All tools \\
38
        Sort::Naturally       & Natural sorting of alphanumerics  & All tools \\
39
40
41
42
43
44
        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 \\
45
        Log::Dispatch::FileRotate & Automatic log rotation        & All tools \\
46
47
48
49
50
51
52
53
        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} \\
54
55
        \bottomrule
    \end{tabular}
Christian Fibich's avatar
Christian Fibich committed
56
57
\end{table}

58
59
60
61
62
\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.
63
64
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.
65

66
67
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}.
68
69

The remaining Perl packages should be available from the distributor in a suitable version.
70
However, \ac{FIJI} also comes with a script to install all required Perl packages (including Verilog-Perl) from CPAN as well.
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
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
98
    \item Log::Dispatch::FileRotate
99
100
101
    \item Config::Simple
    \item Digest::CRC
    \item Doxygen::Filter::Perl
102
    \item Sort::Naturally
103
104
105
106
107
    \item Tk::StatusBar
\end{itemize}

That can be handled with the following command within a Cygwin shell.
\begin{lstlisting}
108
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')"
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
\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}

124
125
126
127
128
129
130
131
132
133
134
\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}

135
136
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.
137
138
139
140
141
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.
142
143


144
\subsection{Repository Contents}
145

146
Since \ac{FIJI} is written in Perl there is no need (and no proposed way) to install it onto a system.
147
Simply checking out the source code repository and loading the respective scripts in a Perl interpreter should be enough to use it.
148
149
150
151
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.
152

153
154
155
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}).
156
157
Media files like logos and icons are found in \texttt{media}.

158
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.
159
Details about testing are described in the \ac{TRM}'s \Cref{TRM:sec:testing}.
160
161
162
163
164
165
166
167
168

\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).