03-software.tex 16.6 KB
 Stefan Tauner committed May 04, 2018 1 \section{Software} Christian Fibich committed May 04, 2018 2 3 \label{sec:flow} Stefan Tauner committed May 04, 2018 4 This chapter sums up some concepts of the Perl classes used in the \ac{FIJI} framework. Stefan Tauner committed May 04, 2018 5 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}. Stefan Tauner committed May 04, 2018 6 You should consult the Doxygen documentation and source files for the details beyong the overview given below. Stefan Tauner committed May 04, 2018 7 8 9 10 \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). Stefan Tauner committed May 04, 2018 11 12 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: Stefan Tauner committed May 04, 2018 13 14 15 16 \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; Stefan Tauner committed May 04, 2018 17 \item the keys on the left side are separated by (the first) equal sign (\texttt{=}) from the values on the right side. Stefan Tauner committed May 04, 2018 18 19 \end{itemize} Stefan Tauner committed May 04, 2018 20 There are two major types of blocks allowed in \ac{FIJI} Settings: Stefan Tauner committed May 04, 2018 21 22 \begin{itemize} Stefan Tauner committed May 04, 2018 23 24 \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{}} where \textit{} Stefan Tauner committed May 04, 2018 25 26 27 28 29 30 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} Stefan Tauner committed May 04, 2018 31 32 33 \Cref{tab:consts} lists all specifiable constants for a design, while \Cref{tab:fiuconsts} explains the settings for each \ac{FIU}. The Name'' Stefan Tauner committed May 04, 2018 34 35 36 37 38 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. Stefan Tauner committed May 04, 2018 39 40 Additionally, the literals used to specify the available fault models at runtime are listed in \Cref{tab:faultmodels}. Stefan Tauner committed May 04, 2018 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 \begin{table} \caption{Design Constants} \input{content/tab_design_consts.tex} \label{tab:consts} \end{table} \begin{table} \caption{FIU Constants} \input{content/tab_fiu_consts.tex} \label{tab:fiuconsts} \end{table} \begin{table} \caption{Fault Model Type Literals} \input{content/tab_faultmodels.tex} \label{tab:faultmodels} \end{table} Christian Fibich committed May 04, 2018 58 Stefan Tauner committed May 04, 2018 59 60 61 62 63 64 \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: Stefan Tauner committed May 04, 2018 65 {\small Stefan Tauner committed May 04, 2018 66 67 68 69 70 71 72 73 74 75 76 77 78 79 \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} Stefan Tauner committed May 04, 2018 80 } Stefan Tauner committed May 04, 2018 81 82 83 84 85 86 87 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). Stefan Tauner committed May 04, 2018 88 89 90 91 92 93 94 95 96 97 98 99 \subsection{FIJI Tests} The data structure describing test patterns is patterned on the \ac{FIJI} Settings. The constants used therein are also described in \texttt{FIJI.pm} but the implementation slightly differs and can be found in \texttt{FIJI::Tests}. The two major differences are: \begin{itemize} \item The rules and data used for validation in the Tests is generated from a \ac{FIJI} Settings instance. This allows for validation against the actual design settings instead of some coarse generic rules. \item The utility functions differ greatly.\\ E.g., instead of calculation FPGA resources like in \texttt{FIJI::Settings::estimate\_resources} the functions in \texttt{Tests.pm} are concerned with generating code related to simluations. \end{itemize} Stefan Tauner committed May 04, 2018 100 101 102 103 104 105 106 107 108 109 110 \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} Stefan Tauner committed May 04, 2018 111 \label{sec:instrumentation} Stefan Tauner committed May 04, 2018 112 113 114 115 116 117 118 119 120 121 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. Stefan Tauner committed May 04, 2018 122 \item Create unique, sane identifieres\footnotemark{} for the various new objects to create (e.g., ports to forward \ac{DUT}-internal signals). Stefan Tauner committed May 04, 2018 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 \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} Stefan Tauner committed May 04, 2018 138 139 140 141 142 \footnotetext{ We denote those identifiers \textit{sane} that have been sanitized by \texttt{FIJI::Netlist::\_sanitize\_identifier}. This function transforms all non-alphanumeric characters into underscores while making sure there are no consecutive underscores. This guarantees that resulting identifiers are compatible with both Verilog and VHDL compilers. } Stefan Tauner committed May 04, 2018 143 144 145 146 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. Stefan Tauner committed May 04, 2018 147 Stefan Tauner committed May 04, 2018 148 149 150 151 152 153 154 155 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 Christian Fibich committed May 04, 2018 156 157 \end{itemize} Stefan Tauner committed May 04, 2018 158 The resulting value is saved as \texttt{ID} into the respective \ac{FIJI} Settings file. Christian Fibich committed May 04, 2018 159 Stefan Tauner committed May 04, 2018 160 \subsection{Communication, Protocol Handling and the FIJI Execution Engine} Christian Fibich committed May 04, 2018 161 Stefan Tauner committed May 04, 2018 162 163 164 165 All run-time communication with the \ac{DUT} works via the \ac{UART} protocol specified in \Cref{sec:comm_prot}. The Perl implementation is split into several files. The part filling a buffer representing the payload as preparation for sending as well as parsing the messages from the \ac{FIC} resides in \texttt{FIJI::Connection} and relies on \texttt{FIJI::AnySerialPort} to be compatible across platforms. Its \texttt{send\_config} method allows \texttt{FIJI::Downloader} to offer various \texttt{download\_*} methods to classes further up the stack in the \ac{FIJIEE}. Christian Fibich committed May 04, 2018 166 Stefan Tauner committed May 04, 2018 167 168 169 170 The two available user interfaces of \texttt{fiji\_ee.pl} and \texttt{fiji\_ee\_gui.pl} merely prepare data structures representing test patterns and pass them to the classes mentioned above. The GUI application is the only truely\footnote{As far as Perl threads are \textit{real} anyway,\\cf.\ \url{http://perldoc.perl.org/perlthrtut.html\#What-kind-of-threads-are-Perl-threads\%3f}} multithreaded application in the framework. Its \texttt{download\_worker} function is executed in parallel and triggers the actual communication. It gets its commands from the \texttt{Tk}/main thread via a \texttt{Thread::Queue} and returns its result and log message via the same mechanism as well. Christian Fibich committed May 04, 2018 171 Stefan Tauner committed May 04, 2018 172 173 \subsection{Testing} \label{sec:testing} Christian Fibich committed May 04, 2018 174 Stefan Tauner committed May 04, 2018 175 In the following section the contents of the \texttt{test} directory are described. Christian Fibich committed May 04, 2018 176 Stefan Tauner committed May 04, 2018 177 178 \subsection{\ac{FIC} Emulator} \label{sec:fic_emulator} Christian Fibich committed May 04, 2018 179 Stefan Tauner committed May 04, 2018 180 181 The \ac{FIC} emulator is intended for testing/debugging the \ac{FIJIEE} scripts. It emulates the \ac{FIJI} \ac{FIC} (Fault Injection Controller) by sending appropriate Christian Fibich committed May 04, 2018 182 183 184 185 \texttt{CONF\_DONE} and \texttt{READY} messages. It can also be instructed to send \texttt{UNDERRUN} messages. Moreover, the UART, ID, and CRC error bits as well as fault detect bits can be set at run-time. The \ac{FIC} emulator is written in C. Stefan Tauner committed May 04, 2018 186 To use the \ac{FIC} emulator, the following prerequisites are necessary: Christian Fibich committed May 04, 2018 187 188 189 190 191 \begin{itemize} \item A program to create a pair of connected terminals, e.g. socat\footnote{\url{http://www.dest-unreach.org/socat/}} \item A terminal supporting the POSIX termios interface (\texttt{tcgetattr()} and \texttt{tcsetattr()}) and ANSI escape sequences \end{itemize} Stefan Tauner committed May 04, 2018 192 193 A matching \ac{FIC} Emulator executable needs to be generated for each \ac{FIJI} configuration. The following parameters in the \ac{FIJI} configuration file (\texttt{*.cfg}) Christian Fibich committed May 04, 2018 194 195 196 influence the configuration message length and thus the behavior of this program: \begin{itemize} Stefan Tauner committed May 04, 2018 197 198 199 \item \texttt{FIU\_CFG\_BITS}: Bits per \ac{FIU} fault pattern \item \texttt{FIU\_NUM}: Number of \acp{FIU} \item \texttt{CFGS\_PER\_MSG}: Number of fault patterns for each \ac{FIU} per message Christian Fibich committed May 04, 2018 200 201 202 203 204 205 206 \item \texttt{TIMER\_WIDTH}: Width of the timer values \end{itemize} The configuration file can be passed to the Makefile via the variable \texttt{FIJI\_CFG\_FILE}. The Makefile then parses the constants described above out of the configuration file. Stefan Tauner committed May 04, 2018 207 For example, build the \ac{FIC} emulator using: Christian Fibich committed May 04, 2018 208 209 210 211 212 213 214 \texttt{\$make FIJI\_CFG\_FILE=\textasciitilde/fiji/test\_1/fiji.cfg} It is also possible to pass the constants directly to the compiler using: \texttt{\$ gcc fic-emulator.c -DFIU\_CFG\_BITS=... -DFIU\_NUM=... -DCFGS\_PER\_MSG=... -DTIMER\_WIDTH=...} Stefan Tauner committed May 04, 2018 215 Once compiled, the \ac{FIC} emulator may be used as follows: Christian Fibich committed May 04, 2018 216 217 218 219 220 221 222 \texttt{\$fic-emulator [-d DEVICE] [-c PERIOD] [-h]} The command-line options have the following meanings: \begin{itemize} \item \texttt{-d DEVICE} The terminal device to be used, e.g., \texttt{/dev/pts/2} Stefan Tauner committed May 04, 2018 223 \item \texttt{-c PERIOD} The \ac{FIC} emulator can be instructed to actually Christian Fibich committed May 04, 2018 224 225 226 227 228 229 230 wait during the T1/T2 durations. It multiplies the durations with the clock period in microsecond passed with this parameter. \item \texttt{-h} Display a short usage information including the compile-time configuration \end{itemize} Stefan Tauner committed May 04, 2018 231 To run the \ac{FIC} emulator, first a pair of pseudo terminals need to be set up. Christian Fibich committed May 04, 2018 232 233 234 235 236 This may be done using \texttt{socat} as follows: \texttt{\$ socat -d -d pty,raw,echo=0 pty,raw,echo=0} Then the \ac{FIC} emulator may be launched on one of the terminals. Christian Fibich committed May 04, 2018 237 Christian Fibich committed May 04, 2018 238 When the \ac{FIC} emulator is running, in the status line at the bottom Stefan Tauner committed May 04, 2018 239 240 the current configuration of the fault detection lines, UNDERRUN, UART, ID, and CRC error flags can be seen. The configuration can be changed by pressing Christian Fibich committed May 04, 2018 241 242 any of the keys shown above the status line. The terminal to which the emulator is connected is shown at the top. Christian Fibich committed May 04, 2018 243 Stefan Tauner committed May 04, 2018 244 245 \subsection{Instrumentation Tests} \label{sec:instrumentation_tests} Christian Fibich committed May 04, 2018 246 Stefan Tauner committed May 04, 2018 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 To test our Verilog-Perl changes as well as the instrumentation code (cf.\ \Cref{sec:instrumentation}) we have set up unit tests in \texttt{test/instrument\_test} consisting of minimal netlists (in \texttt{netlists}) and associated \ac{FIJI} Settings (in \texttt{fiji}). These tests cover many different combinations of instrumentation targets and drivers and have found many bugs in corner cases. The provided Makefile will execute all \textit{mandatory} test cases, by default in 16 parallel threads. There are also some optional test cases for Verilog features that have not been observed yet in simple netlists and hence have not been implemented (yet). The unit tests consist of the following phases. \begin{description}[] \item[Setup] If there exists no \ac{FIJI} Settings file for a respective netlist \texttt{fiji\_setup.pl} will be launched to allow the engineer to choose the instrumented net(s) and possibly set other settings needed for the test. If the Settings exist already but are older than the netlist we force make to skip launching the GUI for usability reasons. \item[Instrumentation] The netlists are instrumented with \texttt{fiji\_instrument.pl}. \item[Synthesis] The instrumented netlists are quickly checked for syntax errors and the like by letting Symplify synthesize and filtering unrelated warnings. \item[Simulation] Additionally to the syntax check a behavioral simulation tries to find discrepancies between an instrumented and untouched entity of the respective netlist. To that end the test instantiates them in a testbench and compares their output when fed some generated input. The tests are not exhaustive but very effective since instrumentation bugs usually affect the signal path in a very direct manner. \end{description}