README.md

# FIJI - Fault InJection Instrumenter

## Synopsis

FIJI is a fault injection tool to instrument selected nets of FPGA designs at netlist level and then manipulate them at run-time.

## Features

There are a number of advantages and features in FIJI that (as of today) are not united together in any other fault injection framework.

 - Run-time Control

    The injected faults can be precisely controlled at runtime via FIJI's UART-based control protocol.
 - HDL Independence

    FIJI does not interact with the HDL description of the design but processes an easily acquirable (Verilog) netlist representation.
 - Resource Efficiency

    FIJI incorporates only a tiny control logic into the DUT logic that might even be left in the production design.
    There is no need for additional high-speed exercisers to provide stimuli.
 - Fine-grained Fault Localization

    The user can select individual nets that FIJI shall manipulate instead of simply injecting faults in random places of a design.
 - FPGA Vendor Independence

    The FIJI workflow is not tight to any specific features of the synthesis or P&R tools of the FPGA vendor.

This unique combination of features allows it to be used in various circumstances to evaluate, validate or certify safety features in fault-tolerant designs.

## Documentation

> **Note:**
Much of FIJI's documentation gets automatically built with every relevant commit and published at the locations linked below.
>

The following documents are available:

 - [User Guide](https://es.technikum-wien.at/vecs/fiji_public/builds/artifacts/master/file/docs/fiji_user_guide.pdf?job=build-latex) ([PDF](https://es.technikum-wien.at/vecs/fiji_public/builds/artifacts/master/raw/docs/fiji_user_guide.pdf?job=build-latex))

    Explains everything a user of FIJI should have to care about.
 - [Technical Reference Manual](https://es.technikum-wien.at/vecs/fiji_public/builds/artifacts/master/file/docs/fiji_trm.pdf?job=build-latex) ([PDF](https://es.technikum-wien.at/vecs/fiji_public/builds/artifacts/master/raw/docs/fiji_trm.pdf?job=build-latex))

    The target audience of this documents are engineers that want to understand or tinker with the inner workings of the FIJI suite.
    The technical details contained herein are supposed to be irrelevant to ordinary users.
 - API documentation about the source code of FIJI can be built with Doxygen by executing `make -C ./docs/ doxygen`.
    It requires `doxygen-filter-perl` to be available (provided by Perl's `Doxygen::Filter::Perl` package).

 - Know issues and limitations are documented in the [`ISSUES`](/ISSUES.md) file.

## Installation

Since FIJI requires a relatively sane Verilog netlist as input, using Synopsis Synplify is recommended and thus needs to be installed.
A proper P&R tool for the respective FPGA has to be installed as well to produce the final bitstream of the netlist instrumented by FIJI.

Our toolchain itself does only need Perl and some associated libraries.
However, for the example work flow in `docs/demos/*` `make` and a number of common unix utilities are required.
Building the various forms of [documentation](#documentation) you will need Latex and Doxygen installed as well.
Please see the [User Guide](https://es.technikum-wien.at/vecs/fiji_public/builds/artifacts/master/file/docs/fiji_user_guide.pdf?job=build-latex) for more details.

> **Attention:**
The upstream version of `Verilog::Perl` (`Verilog::Language`) does not support the required features yet.
A patch has been submitted upstream but has not been merged yet.
The user guide briefly explains how to build it from source.
>

### Linux/Unix
#### Perl Modules
To install all necessary Perl modules via CPAN you can simply execute:

`$ ./bin/install_prerequesites.sh`

### Windows (Cygwin needed)

`C:> install_prerequesites.cmd`

## Execution

The FIJI framework provides a number of Perl scripts to be executed.
All of them support printing an extensive usage when launched with the `--help` parameter.

Below some typical command lines are listed.

`$ perl ./bin/fiji_setup.pl -s fiji.cfg -n netlist.vm`

`$ perl ./bin/fiji_instrument.pl  -s fiji.cfg -n netlist.vm -p instrumented`

`$ perl ./bin/fiji_ee.pl -m manual -s fiji.cfg -t fiji.tst`

`$ perl ./bin/fiji_ee_gui.pl -s fiji.cfg -t fiji.tst`

## Authors

- [Christian Fibich](https://embsys.technikum-wien.at/staff/fibich/) <<mailto:fibich@technikum-wien.at>>

- [Stefan Tauner](http://embsys.technikum-wien.at/staff/tauner/) <<mailto:tauner@technikum-wien.at>>

## License

See [`LICENSE`](/LICENSE) file