Skip to content

Latest commit

 

History

History
76 lines (47 loc) · 4.39 KB

sample_bit_scripts.md

File metadata and controls

76 lines (47 loc) · 4.39 KB

Generating Sample Fault Bit lists

In BYU's Comfigurable Computing Lab (CCL), BFAT is used to analyze fault bits that are discovered in radiation beam testing and in fault injection. For users that do not have access to these resource-intensive methods, three scripts are provided which can generate sample fault bit lists for users to input into BFAT with their designs.

These scripts are as follows:

  • find_fault_bits.py: python tool that a user can use on their own design to generate a sample fault bit list
  • ll_sample_bits.py: python tool that a user can run on a generated logic location (.ll) file to generate a sample fault bit list
  • essential_bits.py: python tool that a user can run on a generated essential bits (.ebd) file to generate a sample fault bit list

Each of these scripts will output a list of bits in a .json format. The bits in these files can then be analyzed in the main bfat.py script when input with the user's design bitstream file and implemented design checkpoint file.

find_fault_bits.py

find_fault_bits.py will generate a set of exactly 7 fault bits. The script is designed such that each bit in the fault bit list, if it were to flip, will cause one of the common types of faults that BFAT can detect and analyze. A new user running this script should be able to get a pretty good grasp of BFAT's fault report format and the different types of faults that BFAT can detect.

python3 find_fault_bits.py <design_bitstream> <design_checkpoint>

The command-line interface with this script also has two optional flags which can be set:

  • -r, --run : Immediately run the given bitstream and dcp through BFAT, along with the generated fault bit list
  • -d, --debug : Print the program runtime after major function returns

docs/fault_report.md contains more information about each of the types of faults that will be caused by the bits generated by this script.

ll_sample_bits.py

ll_sample_bits.py will generate a list of fault bits from a provided logic location file. Logic location (.ll) files contain information about the bits in the bitstream which relate to flip-flops, LUTs configured as distributed RAMs, and BRAM blocks.

To generate a .ll file for your design use the -logic_location_file option when writing your bitstream in Vivado's Tcl Console.

write_bitstream -logic_location_file <bitstream_name>

Vivado will create an additional logic location file with the same name as your bitstream, but with the .ll extension. Then, run the file through ll_sample_bits.py, specifying the number of bits from the file that you wish to include in your sample fault bit list.

python3 ll_sample_bits.py <ll_file> <num_bits>

The script will parse the provided logic location file, then randomly select the number of bits specified to include in the output fault bit list.

  • Note that because BFAT does not currently fully support fault analysis of BRAM related bits, this script will skip those bits when parsing the .ll file.

essential_bits.py

essential_bits.py will generate a list of fault bits from a provided essential bits file. Essential bits data (.ebd) files identify all bits in the bitstream that Vivado has determined are "essential" for the design to run properly. Naturally, these bits are perfect candidates for fault analysis, so this script will generate a fault bit list containing bits from this file so BFAT can determine what exactly will happen if upsets were to happen in these locations.

To generate a .ebd file for your design, set this property before generating a bitstream in Vivado's Tcl Console:

set_property bitstream.seu.essentialbits yes [current_design]

When writing a bitstream, two additional files will be generated in the directory where your bitstream is generated:

  • .ebc file -- this is just an ASCII representation of the configuration bitstream
  • .ebd file -- this is a mask of the .ebc file which marks the essential bits, and is the file that essential_bits.py expects

To run the script, simple provide the .ebd file and the number of bits to select from the file as an argument.

python3 essential_bits.py <ebd_file> <num_bits>

The script will generate a fault bit list containing a random selection of the number of bits specified in the command-line interface.

Note: All of these scripts can be run from any directory as long as the correct path to the script is given in the command