README.md 4.48 KB
Newer Older
Christian Fibich's avatar
Christian Fibich committed
1
2
3
4
# FIJI - Fault InJection Instrumenter

## Synopsis

5
FIJI is a fault injection tool to instrument selected nets of FPGA designs at netlist level and then manipulate them at run-time.
Christian Fibich's avatar
Christian Fibich committed
6

7
## Features
Christian Fibich's avatar
Christian Fibich committed
8

9
There are a number of advantages and features in FIJI that (as of today) are not united together in any other fault injection framework.
Christian Fibich's avatar
Christian Fibich committed
10

11
 - Run-time Control
Christian Fibich's avatar
Christian Fibich committed
12

13
14
    The injected faults can be precisely controlled at runtime via FIJI's UART-based control protocol.
 - HDL Independence
Christian Fibich's avatar
Christian Fibich committed
15

16
17
    FIJI does not interact with the HDL description of the design but processes an easily acquirable (Verilog) netlist representation.
 - Resource Efficiency
Christian Fibich's avatar
Christian Fibich committed
18

19
20
21
    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
Christian Fibich's avatar
Christian Fibich committed
22

23
24
    The user can select individual nets that FIJI shall manipulate instead of simply injecting faults in random places of a design.
 - FPGA Vendor Independence
Christian Fibich's avatar
Christian Fibich committed
25

26
    The FIJI workflow is not tight to any specific features of the synthesis or P&R tools of the FPGA vendor.
Christian Fibich's avatar
Christian Fibich committed
27

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

30
31
32
33
34
35
36
## 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:
37

38
 - [User Guide (PDF)](https://es.technikum-wien.at/pages/vecs/fiji_public/fiji_user_guide.pdf)
39
40

    Explains everything a user of FIJI should have to care about.
41
 - [Technical Reference Manual (PDF)](https://es.technikum-wien.at/pages/vecs/fiji_public/fiji_trm.pdf)
42
43
44
45
46
47

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

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

50
## Installation
51

52
53
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.
54

55
Our toolchain itself does only need Perl and some associated libraries.
56
57
However, for the example work flow in `docs/demos/*` the `make` utility and a number of common Unix programs are required.
Building the various forms of [documentation](#documentation) need Latex and Doxygen facilities to be available as well.
58
Please see the [User Guide (PDF)](https://es.technikum-wien.at/pages/vecs/fiji_public/fiji_user_guide.pdf) for more details.
59
60

> **Attention:**
61
62
63
The upstream version of `Verilog::Perl` (`Verilog::Language`) does support the required features since the 3.442 release.
Using this or a newer upstream version is recommended.
The user guide briefly explains how to build it from source if need be.
64
65
66
67
>

### Linux/Unix
#### Perl Modules
68
To install all necessary Perl modules via CPAN you can simply execute:
Christian Fibich's avatar
Christian Fibich committed
69

70
`$ ./bin/install_prerequesites.sh`
Christian Fibich's avatar
Christian Fibich committed
71

72
### Windows (Cygwin needed)
Christian Fibich's avatar
Christian Fibich committed
73
74
75

`C:> install_prerequesites.cmd`

76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
## 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's avatar
Christian Fibich committed
92

93
94
95
96
97
If you want to contact the people involved in the project at Technikum Wien please use our project-specific email alias: <<mailto:fiji@technikum-wien.at>>

The main contributors are listed below.
Many others were involved by providing feedback to various aspects (e.g., documentation, usability) and working on things not visible in this repository.

98
- [Christian Fibich](https://embsys.technikum-wien.at/staff/fibich/) <<mailto:fibich@technikum-wien.at>>
Christian Fibich's avatar
Christian Fibich committed
99

100
- [Stefan Tauner](https://embsys.technikum-wien.at/staff/tauner/) <<mailto:tauner@technikum-wien.at>>
Christian Fibich's avatar
Christian Fibich committed
101
102
103

## License

104
See [`LICENSE`](/LICENSE) file