02-installation.tex 9.53 KB
 Stefan Tauner committed May 04, 2018 1 2 3 \section{Installation} \subsection{Prerequisites}  Christian Fibich committed May 04, 2018 4   Stefan Tauner committed May 04, 2018 5 The prerequisites for running the \textit{\ac{FIJI}} fault injection tool flow are  Stefan Tauner committed May 04, 2018 6 listed in \Cref{tab:prerequisites} alongside the version of the respective software \ac{FIJI} was  Stefan Tauner committed May 04, 2018 7 initially tested with. This does not include the Perl modules that need to be installed,  Stefan Tauner committed May 04, 2018 8 which can be found in \Cref{tab:perlmod}.  Christian Fibich committed May 04, 2018 9   Stefan Tauner committed May 04, 2018 10 \begin{table}[ht]  Christian Fibich committed May 04, 2018 11  \caption{Software prerequisites for \ac{FIJI}}  Christian Fibich committed May 04, 2018 12  \label{tab:prerequisites}  Stefan Tauner committed May 04, 2018 13 14 15 16 17 18  \centering \begin{tabular}{llll} \toprule Category & OS & Name & Version \\ \midrule Perl Interpreter & Unix/Linux & Perl & v5.22.1 \\  Stefan Tauner committed May 04, 2018 19  & Windows & ActivePerl & v5.16.3 \\  Stefan Tauner committed May 04, 2018 20 21  FPGA Synthesis Tool & Unix/Linux, Windows & Synopsys Synplify & I-2013.09-SP1 \\ FPGA Implementation Tool & Unix/Linux, Windows & Altera Quartus II & 13.0 \\  Stefan Tauner committed May 04, 2018 22  & Unix/Linux, Windows & Xilinx Vivado & 2016.1 \\  Stefan Tauner committed May 04, 2018 23 24  \bottomrule \end{tabular}  Christian Fibich committed May 04, 2018 25 26 \end{table}  Stefan Tauner committed May 04, 2018 27 \begin{table}[ht]  Christian Fibich committed May 04, 2018 28  \caption{Perl Modules required by \ac{FIJI}}  Christian Fibich committed May 04, 2018 29  \label{tab:perlmod}  Stefan Tauner committed May 04, 2018 30 31 32  \centering \begin{tabular}{llll} \toprule  Stefan Tauner committed May 04, 2018 33  Module & Description & \ac{FIJI} Tool \\  Stefan Tauner committed May 04, 2018 34  \midrule  Stefan Tauner committed May 04, 2018 35 36  Clone & Deep object copy & All tools \\ Config::Simple & Configuration file handling & All tools \\  Stefan Tauner committed May 04, 2018 37  Sort::Naturally & Natural sorting of alphanumerics & All tools \\  Stefan Tauner committed May 04, 2018 38 39 40 41 42 43  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 \\  Stefan Tauner committed May 04, 2018 44  Log::Dispatch::FileRotate & Automatic log rotation & All tools \\  Stefan Tauner committed May 04, 2018 45 46 47 48 49 50 51 52  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} \\  Stefan Tauner committed May 04, 2018 53 54  \bottomrule \end{tabular}  Christian Fibich committed May 04, 2018 55 56 \end{table}  Stefan Tauner committed May 04, 2018 57 58 59 60 61 \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.  Stefan Tauner committed May 04, 2018 62 63 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.  Stefan Tauner committed May 04, 2018 64   Stefan Tauner committed May 04, 2018 65 66 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}.  Stefan Tauner committed May 04, 2018 67 68  The remaining Perl packages should be available from the distributor in a suitable version.  Stefan Tauner committed May 04, 2018 69 However, \ac{FIJI} also comes with a script to install all required Perl packages (including Verilog-Perl) from CPAN as well.  Stefan Tauner committed May 04, 2018 70 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 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  Stefan Tauner committed May 04, 2018 97  \item Log::Dispatch::FileRotate  Stefan Tauner committed May 04, 2018 98 99 100  \item Config::Simple \item Digest::CRC \item Doxygen::Filter::Perl  Stefan Tauner committed May 04, 2018 101  \item Sort::Naturally  Stefan Tauner committed May 04, 2018 102 103 104 105 106  \item Tk::StatusBar \end{itemize} That can be handled with the following command within a Cygwin shell. \begin{lstlisting}  Stefan Tauner committed May 04, 2018 107 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')"  Stefan Tauner committed May 04, 2018 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 \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}  Stefan Tauner committed May 04, 2018 123 124 125 126 127 128 129 130 131 132 133 \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}  Stefan Tauner committed May 04, 2018 134 135 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.  Stefan Tauner committed May 04, 2018 136 137 138 139 140 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.  Stefan Tauner committed May 04, 2018 141 142   Stefan Tauner committed May 04, 2018 143 \subsection{Repository Contents}  Stefan Tauner committed May 04, 2018 144   Stefan Tauner committed May 04, 2018 145 146 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 us it.  Stefan Tauner committed May 04, 2018 147 148 149 150 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.  Stefan Tauner committed May 04, 2018 151   Stefan Tauner committed May 04, 2018 152 153 154 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}).  Stefan Tauner committed May 04, 2018 155 156 Media files like logos and icons are found in \texttt{media}.  Stefan Tauner committed May 04, 2018 157 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.  Stefan Tauner committed May 04, 2018 158 Details about testing are described in the \ac{TRM}'s \Cref{TRM:sec:testing}.  Stefan Tauner committed May 04, 2018 159 160 161 162 163 164 165 166 167  \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).