BFAT is a tool used for analysis of a design's bitstream to evaluate and report any relevant information about given fault bits as well as any errors that they would cause in the design's implementation. BFAT is being used for research purposes and is currently under development. So far BFAT supports most Xilinx 7-Series FPGAs that are documented in the Project X-Ray database. The full list of parts can be found below in the "Supported Parts" section.
BFAT consists of the following scripts:
bfat.py
: The main script that is run on a design and creates a .txt file to report the information found.bitread.py
: python tool used to convert bitstream to ascii representation of high bits in bitstream and identify the part used to implement the provided design. Can also be run by itself to convert a bitstream to a .bits file containing the ascii representation of the high bits in the bitstream.Scripts included from the local library:
define_bit.py
: Correlates fault bits to their physical functions in the FPGA fabric using the Project X-Ray databasefault_analysis.py
Uses the physical functions found for each fault bit to analyze the effect on the design from an upset.file_processing.py
: Deals with all external file reading and parsing.rpd_query.py
: Deals with querying the design information from its .dcp checkpoint file using the Rapidwright tool.statistics.py
: Reads the report data for the design and adds a footer at the end of the report file to report some statistics of the design and faults found.tile.py
: Creates the classes to store the information on the tiles and routing muxes for the given FPGA design.Utility scripts to generate fault bit lists for user designs (see here for more info):
find_fault_bits.py
: python tool that a user can use on their own design to generate a sample fault bit listll_sample_bits.py
: python tool that a user can run on a generated logic location (.ll) file to generate a sample fault bit listessential_bits.py
: python tool that a user can run on a generated essential bits (.ebd) file to generate a sample fault bit listOther utility scripts:
net_analysis.py
: python tool which performs a sensitivity analysis for any given nets in a user's design (see here for info)BFAT requires the use of Vivado or Rapidwright to read dcp files in order to retrieve information about the design being analyzed. BFAT runs using a sourced version of Vivado by default, but can be run using Rapidwright with the -rpd
flag.
BFAT utilizes the ProjectXray database in its design analysis and clones the database repo from Github during setup.
Clone the BFAT repo from Github along with its submodule
git clone --recurse-submodules https://github.com/byuccl/bfat.git
cd bfat
Install Vivado HDL Tools
Note: We recommend Vivado version 2021.2 or later, as earlier versions are untested and we cannot guarantee that they will work
Install Python 3.8+, its corresponding Virtual Environement (venv) module, and a valid Java JDK
sudo apt install python<dist> python<dist>-venv default-jdk
Create and activate a Python Virtual Environment
python<dist> -m venv env/
source env/bin/activate
Install required packages for Rapidwright (while venv is activated)
pip install -r requirements.txt
Source Python Virtual Environment
source env/bin/activate
Source Vivado tooling
source /opt/Xilinx/Vivado/<vivado_version>/settings64.sh
Note: This is the default path for Vivado installation. Vivado may be installed in a different directory on your machine.
Run the bfat.py script providing it with:
Note: If the bits_file flag (-bf) is used, a .bits file (as generated from bitread.py) will be read in instead of a bitstream
-rpd
flag if running with Rapidwright(Optional) Using the -of
flag you can specify the file the fault report will be output to. If not used, the report will be saved to a file with a generated name in the current directory.
Template command to run BFAT:
python3 bfat.py <bitstream> <dcp> <fault_bits>
python3 bfat.py -h
When using the Rapidwright implementation of the design query, Rapidwright will attempt to read the checkpoint data from the following sources in order:
Loading the dcp into Vivado and writing a usable edf file
If it reaches this point, the read will not be able to happen and an error will be thrown if some version of vivado has not already been sourced.
source /opt/Xilinx/Vivado/<vivado_version>/settings64.sh
Note: This is the default path. Vivado may be installed in a different directory on your machine.