The communication between the hardware and the \texttt{fiji\_ee*.pl} tools uses a
The communication between the hardware and the \ac{FIJIEE} uses a
UART protocol with 8N1 configuration (8 data bits, 1 stop bit, no parity).
The baud rate is configurable (in \texttt{fiji\_setup.pl}) with a default of 115200.
It works with any type of serial port (e.g., RS-232-compatible ports or USB-based TTL-level adapters) as long as the operating system represents it as such.
Each communication direction uses its own message format as explained in the next two sections.
@@ -62,6 +62,7 @@ Additionally, the literals used to specify the available fault models at runtime
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:
{\small
\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.
...
...
@@ -76,6 +77,7 @@ In \texttt{FIJI.pm} keys of the constants listed in \Cref{tab:consts} and \Cref{
\item [\texttt{default}] defines the default value.
\item [\texttt{unit}] denotes the (physical) unit of the value specified by this setting.
\end{description}
}
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.
...
...
@@ -83,6 +85,18 @@ The \texttt{FIJI::Settings} instances returned by the constructor \texttt{new} o
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).
\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}
\subsubsection{FIJI Setup Tool}
\texttt{Tk::FIJISettingsViewer} makes up for the majority of the visible UI of \texttt{fiji\_setup.pl}.
...
...
@@ -94,6 +108,7 @@ All settings of type \texttt{net} (representing a net in the Verilog netlist) ca
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}
\label{sec:instrumentation}
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.
...
...
@@ -104,7 +119,7 @@ The general idea of the instrumentation process (cf.\ \texttt{FIJI::Netlist::ins
\begin{enumerate}
\item Retrieve all signals connected to the respective net (\texttt{FIJI::Netlist::\_get\_net\_connections}) including its driver.
\item Create unique, sane identifieres for the various new objects to create (e.g., ports to forward \ac{DUT}-internal signals).
\item Create unique, sane identifieres\footnotemark{} for the various new objects to create (e.g., ports to forward \ac{DUT}-internal signals).
\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.
...
...
@@ -120,6 +135,11 @@ The general idea of the instrumentation process (cf.\ \texttt{FIJI::Netlist::ins
\item Add another assignment from the driver to the new output port.
\end{enumerate}
\end{enumerate}
\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.
}
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).
...
...
@@ -137,77 +157,46 @@ To this end it calculates a 16-bit hash value based on the CRC-CCITT algorithm c
The resulting value is saved as \texttt{ID} into the respective \ac{FIJI} Settings file.
\subsection{Communication and Protocol Handling}
\todo{Document}
\subsection{FIJI Tests}
\todo{Document}
\subsection{FIJI Execution Engine}
The communication with the instrumented DUT is handled by \texttt{fiji\_ee.pl}
and \texttt{fiji\_ee\_gui.pl}. Preferences that are not related to the hardware
are read from its own configuration file named fiji.tst It gathers
the necessary information about the respective hardware design from the
FIJI Settings as described above.
\begin{itemize}
\item input/config files
\item interactive interface
\end{itemize}
\todo{Document}
All runtime configuration is done with \texttt{fiji\_ee.pl} or \texttt{fiji\_ee\_gui.pl}
which communicate with the DUT over a common serial connection. It works with
any type of serial port (e.g., RS-232-compatible ports or USB-based TTL-level
adapters) as long as the operating system represents it as such. The scripts
support three modes:
\begin{enumerate}
\item Interactive: The user is asked interactively for the various items needed
to build a valid configuration message for the current design.
If available (e.g. via the \ac{FIJI} Settings) it offers useful
default values (e.g. for the design ID). After all information
is typed in the configuration is sent to the device. The respective
responses are received and handled before the user is offered to define another round of parameters.
\item Sequence: \todo{command line usage/features and/or batch configuration file etc.}
\item Random: \todo{command line usage/features and/or batch configuration file etc.}
\end{enumerate}
\subsection{Communication, Protocol Handling and the FIJI Execution Engine}
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}.
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.
\subsection{Testing}
\label{sec:testing}
In the following section the contents of the \texttt{test} directory are described.
\subsection{\ac{FIC} Emulator}
\label{sec:fic_emulator}
The \ac{FIC} emulator is intended for testing/debugging the FIJIEE scripts.
It emulates the FIJI \ac{FIC} (Fault Injection Controller) by sending appropriate
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
\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.
To use the \ac{FIC} emulator, the following preqrequisites are necessary:
To use the \ac{FIC} emulator, the following prerequisites are necessary:
\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}
A matching FIC Emulator executable needs to be generated for each FIJI
configuration. The following parameters in the FIJI configuration file (*.cfg)
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})
influence the configuration message length and thus the behavior of this program:
\begin{itemize}
\item\texttt{FIU\_CFG\_BITS}: Bits per FIU fault pattern
\item\texttt{FIU\_NUM}: Number of FIUs
\item\texttt{CFGS\_PER\_MSG}: Number of fault patterns for each FIU per message
\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
\item\texttt{TIMER\_WIDTH}: Width of the timer values
\end{itemize}
...
...
@@ -215,7 +204,7 @@ 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.
For example, build the FIC emulator using:
For example, build the \ac{FIC} emulator using:
\texttt{\$ make FIJI\_CFG\_FILE=\textasciitilde/fiji/test\_1/fiji.cfg}
...
...
@@ -223,7 +212,7 @@ It is also possible to pass the constants directly to the compiler using:
@@ -247,12 +236,26 @@ This may be done using \texttt{socat} as follows:
Then the \ac{FIC} emulator may be launched on one of the terminals.
When the \ac{FIC} emulator is running, in the status line at the bottom
the current configuration of the FD lines, UNDERRUN, UART, ID, and
CRC flags can be seen. The configuration can be changed by pressing
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
any of the keys shown above the status line. The terminal to which the
emulator is connected is shown at the top.
\subsection{Instrumentation Tests}
\label{sec:instrumentation_tests}
\todo{Document}
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.
