diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..ceb4b18 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,15 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.10" + commands: + - pip3 install -r ./docs/requirements.txt + - cd docs && python3 -m sphinx.cmd.build -M html "source" "_build" + - mv docs/_build _readthedocs diff --git a/Installing.md b/Installing.md deleted file mode 100644 index 72f8c81..0000000 --- a/Installing.md +++ /dev/null @@ -1,58 +0,0 @@ -# Dependencies -* Git -* Clang 12.0+ -* Swift 5.2+ -* Python 3.6+ with PIP, venv -* Yosys 0.9+ - * 0.22+ recommended -* Icarus Verilog 10.2+ -* Pyverilog -* Atalanta (Optional) -* PODEM (Optional) - -# Installing -You need a Swift-compatible operating system (i.e. macOS or Linux). The Swift version of Windows isn't mature enough for this just yet. - -Again, if you're on Windows (or you're too lazy to follow these instructions,) you can use the Docker container. - -## macOS -macOS 11 Big Sur or higher is required. - -Install the latest Xcode from the Mac App Store. - -Use [Homebrew](https://brew.sh). - -`brew install python yosys icarus-verilog` - -## Linux -You need to fulfill the dependencies listed above. - -### Ubuntu -Ubuntu 20.04 or higher is required. - -Using apt: - -`sudo apt-get install git clang python3 python3-dev python3-pip python3-venv yosys iverilog` - -Then install the Swift programming language: instructions are on [swift.org](https://swift.org/download/#using-downloads). - -### Atalanta/PODEM (Optional) -You can optionally install Atalanta and PODEM if you want to use them for test vector generation. Please note they fall under proprietary licenses. - -```bash -EXEC_PREFIX= sudo $(which swift) ./atalanta_podem_build.swift -``` - -# Installation -Then simply invoke `swift install.swift`. This will install it to `~/bin` by default. You can customize this installation directory by executing `INSTALL_DIR= swift ./install.swift`. - -You may need to add `~/bin` to the PATH environment variable depending on your OS. - -To uninstall this, you can simply invoke `fault uninstall`. - -## Without installation -### Building -With everything set up properly, run `swift build -c release` from the root of the repository. That'll be it: You can find the binary under `.build/release/Fault`. - -### Notes -Both `fault uninstall` and `fault -V` will not function. Please note you will need to install all the binary dependencies: IcarusVerilog, Yosys, etc. diff --git a/Readme.md b/Readme.md index 2f80d0b..b669db8 100644 --- a/Readme.md +++ b/Readme.md @@ -1,13 +1,11 @@ # 🧪 Fault -![Swift 5.4+](https://img.shields.io/badge/Swift-5.4-orange?logo=swift) ![Docker Image Available for x86-64](https://img.shields.io/static/v1?logo=docker&label=docker&message=x86_64) +![Swift 5.8+](https://img.shields.io/badge/Swift-5.8-orange?logo=swift) [![ReadTheDocs](https://readthedocs.org/projects/Fault/badge)](https://fault.readthedocs.io) [![Built with Nix](https://img.shields.io/static/v1?logo=nixos&logoColor=white&label=&message=Built%20with%20Nix&color=41439a)](https://nixos.org) Fault is a complete open source design for testing (DFT) Solution that includes automatic test pattern generation for netlists, scan chain stitching, synthesis scripts and a number of other convenience features. -# Quick Setup/Walkthrough -You may refer to the [wiki](https://github.com/Cloud-V/Fault/wiki) for quick setup instructions (and a small walkthrough!) if you're into that. +# Installation and Usage -## Detailed installation instructions -If you don't feel like using (or can't use) Docker, you can try [Installing.md](./Installing.md) for full installation instructions. +See the documentation at https://fault.readthedocs.io. # Running ## Subcommands @@ -75,7 +73,7 @@ For more information on the supported instructions, check the example [testbench For more options, you can invoke `fault tap --help`. # Copyright & Licensing -All rights reserved ©2018-2022 The American University in Cairo and other contributors. Fault is available under the Apache 2.0 License: See `License`. +All rights reserved ©2018-2024 The American University in Cairo and other contributors. Fault is available under the Apache 2.0 License: See `License`. SOFTWARE INCLUDED WITH FAULT DISTRIBUTIONS, I.E. ATALANTA AND PODEM, WHILE FREE TO DISTRIBUTE, ARE PROPRIETARY, AND MAY NOT BE USED FOR COMMERCIAL PURPOSES. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..9217650 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +/venv +/build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..112c6a1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,29 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= venv/bin/sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: venv + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + + +venv: venv/manifest.txt +venv/manifest.txt: ./requirements.txt + rm -rf venv + python3 -m venv ./venv + PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade pip + PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade wheel + PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade -r ./requirements.txt + PYTHONPATH= ./venv/bin/python3 -m pip freeze > $@ + @echo ">> Venv prepared." + +html: Makefile + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/Source/benchmarks.md b/docs/Source/benchmarks.md new file mode 100644 index 0000000..4eb36dd --- /dev/null +++ b/docs/Source/benchmarks.md @@ -0,0 +1,57 @@ +# Benchmark Results + +## Swift RNG + +The following results are obtained using Swift Language's RNG for the test vector generation while setting 97% for the minimum coverage and 5000 as the ceiling for TV count. + +| File | Top Module | Fault Sites | Gate Count | Ports | Run-Time (sec) | Run-Time (Hrs) | TV Count | Coverage (%) | +| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | +| genericfir.v | genericfir | 735286 | 217247 | 23255 | 225524.25 | 62.646 | 100 | 97.0162 | +| fastfir.v | fastfir | 688571 | 204931 | 17159 | 137752.94 | 38.265 | 87 | 97.07924 | +| y_dct.v | y_dct | 682419 | 201129 | 11645 | 208849.56 | 58.014 | 275 | 97.07643 | +| aes192.v | aes192 | 251965 | 71166 | 15940 | 3221.6 | 0.895 | 20 | 98.65378 | +| aes128.v | aes128 | 246423 | 69656 | 11140 | 2027.2 | 0.563 | 20 | 98.54031 | +| tiny_aes.v | aes_128 | 244590 | 69198 | 11140 | 2011.09 | 0.559 | 20| 98.55391 | +| ecg.v | point_add | 183097 | 50226 | 12326 | 8201.54 | 2.278 | 80 | 97.23343 | +| des.v | cbcdes | 81181 | 22238 | 5033 | 323.59 | 0.090 | 30 | 97.014694 | +| picorv32a.v | picorv32a | 69254 | 19955 | 3295 | 21608.25 | 6.002 | 3780 | 97.0009 | +| PPU.v | PPU | 50405 | 12216 | 5792 | 41723.76 | 11.590 | 5000 | 94.37357 | +| axi_fifo.v | axi_fifo | 44429 | 9998 | 5626 | 909.35 | 0.253 | 130 | 97.20341 | +| y_quantizer.v | y_quantizer | 38876 | 9138 | 6028 | 1692.25 |0.470 | 200 | 97.01358 +| cordic.v | cordic | 28462 | 8277 | 1988 | 143.78 | 0.040 | 110 | 97.089096 | +| s35932.v | s35932 | 25245 | 6457 | 3814 | 124.73 | 0.035 | 40 | 97.991684 | +| md5.v | md5 | 23226 | 6049 | 1831 | 1026.07 | 0.285 | 100 | 97.13468 | +| dct.v | dct | 20251 | 6027 | 135 | 1089.01 | 0.303 | 1140 | 97.00262 | +| tv80.v | tv80 | 18218 | 5017 | 715 | 2969.56 | 0.825 | 5000 | 93.32528 | +| aes_encipher_block.v | aes_encipher_block | 12559 | 3418 | 289 | 39.42 | 0.011 | 90 | 97.16538 | +| s15850a.v | s15850 | 8861 | 2323 | 1260 | 1782.93 | 0.495 | 5000 | 95.36734 | +| s15850.v | s15850 | 8861 | 2323 | 1260 | 1757 | 0.488 | 5000 | 96.10654 | +| s13207a.v | s13207 | 7168 | 1803 | 1185 | 1427.64 | 0.397 | 5000 | 93.784874 | +| s13207.v | s13207 | 7168 | 1803 | 1185 | 1419.2 | 0.394 | 5000 | 92.2433 | +| cpu6502.v | cpu6502 | 6342 | 1760 | 297 | 640.01 | 0.178 | 3330 | 97.03564 | +| s5378.v | s5378 | 2913 | 787 | 407 | 122.94 | 0.034 | 1190 | 97.59698 | +| s9234.v | s9234 | 2518 | 658 | 348 | 438.68 | 0.122 | 5000 | 96.44559 | +| s1238.v | s1238 | 1416 | 399 | 67 | 240.06 | 0.067 | 5000 | 96.78673 | +| s1423.v | s1423 | 1458 | 394 | 173 | 17.26 | 0.005 | 330 | 97.01646 | +| crc_gen.v | crc_gen | 1433 | 384 | 72 | 3.37 | 0.001 | 70 | 97.20866 | +| s953a.v | s953 | 1046 | 286 | 100 | 127.13 | 0.035 | 3320 | 97.46654 | +| s953.v | s953 | 1046 | 286 | 100 | 190.7 | 0.053 | 5000 | 96.74952 | +| xtea.v | xtea | 1085 | 266 | 187 | 1809.44 | 0.503 | 5000 | 64.884796 | +| s820a.v | s820 | 723 | 202 | 50 | 72.76 | 0.020 | 2660 | 97.095436 | +| s820.v | s820 | 723 | 202 | 50 | 44.08 | 0.012 | 1630 | 97.095436 | +| s832.v | s832 | 712 | 202 | 50 | 89.28 | 0.025 | 3280 | 97.19101 | +| s838.v | s838 | 740 | 194 | 102 | 145.84 | 0.041 | 5000 | 71.14864 | +| s1196.v | s1196 | 565 | 164 | 28 | 113.72 | 0.032 | 5000 | 96.0177 | +| s510.v | s510 | 597 | 162 | 41 | 5.25 | 0.001 | 230 | 97.73869 | +| s713.v | s713 | 538 | 140 | 95 | 16.08 | 0.004 | 720 | 97.026024 | +| s641.v | s641 | 485 | 124 | 96 | 8.52 | 0.002 | 400 | 97.62887 | +| s526.v | s526 | 394 | 103 | 54 | 7.67 | 0.002 | 440 | 97.58883 | +| s526a.v | s526n | 379 | 99 | 54 | 3.77 | 0.001 | 220 | 97.097626 | +| s382.v | s382 | 372 | 97 | 54 | 1.36 | 0.000 | 80 | 97.31183 | +| s444.v | s444 | 365 | 95 | 54 | 2.18 | 0.001 | 130 | 97.53425 | +| s386.v | s386 | 343 | 94 | 29 | 19.24 | 0.005 | 1260 | 98.542274 | +| s400.v | s400 | 360 | 94 | 54 | 1.61 | 0.000 | 100 | 97.91667 | +| s420.v | s420 | 364 | 93 | 54 | 87.1 | 0.024 | 5000 | 85.71429 | +| s349.v | s349 | 342 | 88 | 53 | 1.23 | 0.000 | 80 | 98.53801 | +| s298.v | s298 | 276 | 74 | 40 | 2.26 | 0.001 | 170 | 97.46377 | +| s27.v | s27 | 52 | 14 | 15 | 50.49 | 0.014 | 5000 | 78.84615 | diff --git a/docs/Source/conf.py b/docs/Source/conf.py new file mode 100644 index 0000000..9dc205f --- /dev/null +++ b/docs/Source/conf.py @@ -0,0 +1,158 @@ +# SPDX-FileCopyrightText: 2020 Efabless Corporation +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# SPDX-License-Identifier: Apache-2.0 + +# Configuration file for the Sphinx documentation builder. +# Yes, it needs to be in this directory. Don't try to move it. +# Yes, it needs to be called conf.py + + +# -- Path setup -------------------------------------------------------------- +import os +import sys + +# -- Project information ----------------------------------------------------- +project = "Fault" +copyright = "2019-2024 The American University in Cairo" +author = "AUC Open Hardware Lab" +repo = "https://github.com/AUCOHL/Fault" +branch = "main" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +custom_extensions = [] +third_party_extensions = [ + "myst_parser", + "sphinx.ext.todo", + "sphinx.ext.autodoc", + "sphinx.ext.graphviz", + "sphinx.ext.mathjax", + "sphinxcontrib.bibtex", + "sphinx_design", + "sphinx_tippy", + "sphinx_copybutton", + "sphinx_subfigure", +] +extensions = third_party_extensions + custom_extensions +try: + import sphinxcontrib.spelling # noqa: F401 + + try: + import enchant # noqa: F401 + + extensions += [ + "sphinxcontrib.spelling", + ] + + spelling_lang = "en_US" + tokenizer_lang = "en_US" + except ImportError: + print("Failed to import 'enchant'- spellchecker cannot run", file=sys.stderr) +except ImportError: + pass + +source_suffix = { + ".md": "markdown", + ".rst": "restructuredtext", +} + +root_doc = "index" + +# Templates +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "venv", + "install", + "pdks", + ".github", + # Files included in other rst files. +] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_title = "Fault Documentation" +html_theme = "furo" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + "source_repository": repo, + "source_branch": branch, + "source_directory": "docs/source", + "footer_icons": [ + { + "name": "GitHub", + "url": repo, + "html": """ + + + + """, + "class": "", + }, + ], +} + +html_static_path = ["../_static"] +html_css_files = [ + "css/custom.css", +] + +numfig = True + +# Bibtex +bibtex_bibfiles = ["refs.bib"] +bibtex_default_style = "unsrt" + +# MyST +myst_heading_anchors = 4 +myst_enable_extensions = [ + "colon_fence", + "attrs_block", + "attrs_inline", + "dollarmath", +] +myst_url_schemes = { + "http": None, + "https": None, + "doi": "https://doi.org/{{path}}", +} + +# GraphViz +graphviz_output_format = "svg" + +# sphinx_copybutton +copybutton_exclude = ".linenos, .gp" + +# sphinx_tippy +tippy_enable_wikitips = False + +spelling_show_suggestions = True +spelling_suggestion_limit = 1 diff --git a/docs/Source/index.md b/docs/Source/index.md new file mode 100644 index 0000000..0e3ec00 --- /dev/null +++ b/docs/Source/index.md @@ -0,0 +1,92 @@ +# Fault Documentation + +Fault is a complete open source design for testing (DFT) solution. It includes +automatic test pattern generation (ATPG), scan stitching, static test vector +compaction, and JTAG insertion. Fault generates test vectors pseudo-randomly and +performs fault simulations using the stuck-at-fault model. + +
+ +

Fault Design Flow.

+
+ +Fault is composed of seven main options: + +## 1. Synth + +Synth is a [Yosys-based](https://github.com/YosysHQ/Yosys) synthesis script that +synthesizes and maps Verilog RTL into a flatten netlist using a standard cell +library. Since Fault is compatible with any flatten netlist, this option could +be skipped if the user wants to run their own synthesis script. + +## 2. Cut + +Cut removes the flip flops from the flatten netlist and converts it into a pure +combinational design. + +## 3. Bench + +Bench converts a flatten netlist to the ISCAS bench format by mapping the +netlist cells to primitive gates. This option is needed only, if atalanta is set +as the test vector generator in the Main option. + +## 4. ATPG + +ATPG is the main event. It runs Fault simulations for a generated test vector +set using the stuck-at fault model. The test vector set could be supplied to the +simulator externally or it could be internally generated using a pseudo-random +number generator or by using [Atalanta](https://github.com/hsluoyz/Atalanta). + +Fault supports two random number generators Swift system default generator and a +linear feedback shift register (LFSR). + +### 5. Compact + +Compact performs static test vector compaction on the generated test vector set. + +### 6. Chain + +Chain performs scan-chain stitching. Using +[Pyverilog](https://github.com/PyHDI/Pyverilog), a boundary scan chain is +constructed through a netlist's input and output ports. An internal register +chain is also constructed through the netlist's D-flip-flops. + +### 7. Tap + +Tap adds the +[JTAG interface](https://opencores.org/websvn/listing?repname=adv_debug_sys&path=%2Fadv_debug_sys%2Ftrunk%2FHardware%2Fjtag%2Ftap%2Fdoc%2F#path_adv_debug_sys_trunk_Hardware_jtag_tap_doc_) +to a chained netlist. This is accomplished by adding its five namesake test +access ports: serial test data in (TDI), test mode select (TMS) which navigates +an internal finite state machine, serial test data out (TDO), test clock (TCK), +and an active low test reset signal (TRST).The interface has been extended to +support a custom instruction (ScanIn) to select the internal register scan +chain. + +## Tutorial + +For a walk-through tutorial on how to use Fault, check the sidebar. + +```{toctree} +:glob: +:hidden: + +installation +usage +benchmarks +``` + +--- + +Documentation text and images are licensed under a +Creative +Commons Attribution-ShareAlike 4.0 International License. You are free to +adapt and modify the documentation's content so long as your changes are +released under the same license. + +By contributing to this documentation, you represent that you: +1. Have the right to license your contribution to the general public. +2. Agree that your contributions are irrevocably licensed under the same + licenses linked above. + +The Fault software itself is available under the Apache 2.0 license, +available in the repository. diff --git a/docs/Source/installation.md b/docs/Source/installation.md new file mode 100644 index 0000000..c4de9c2 --- /dev/null +++ b/docs/Source/installation.md @@ -0,0 +1,144 @@ +# Installation + +In order to use Fault, you have three options: + +- Using Nix (macOS, Linux) +- Using the Docker Image (Windows, macOS, Linux) +- Bring-your-own-dependencies (macOS, Linux) + +> Docker images for Fault are only available on x86-64 devices. + +## Using Nix + +Nix is a declarative utility that takes a unique approach to package management +and system configuration. + +To install Nix, follow OpenLane 2's Nix installation guide at +https://openlane2.readthedocs.io/en/stable/getting_started/common/nix_installation/index.html. + +Afterwards, running Fault is simply `nix run github:AUCOHL/Fault`. To make +the `fault` command available in path, you can +`nix profile install github:AUCOHL/Fault`. + +## Docker + +Docker is software working at the OS level that allows small environments called +"containers" to be run at-will. + +It works on Windows, macOS and Linux, where for the first two, a Linux virtual +machine is used. + +For instructions on how to install Docker, check +[Docker's website](https://docs.docker.com/install/). + +### Getting the Fault Docker image + +After installing Docker, run the following command in your terminal of choice: + +```sh +docker pull ghcr.io/aucohl/fault:latest +``` + +You can then run Fault commands using that image. For example, to run +`fault -V`: + +```sh +docker run -ti --rm ghcr.io/aucohl/fault:latest fault -V +``` + +This should print something like +`Fault X.X.X. ©The American University in Cairo 2019-2022. All rights reserved.`. +If you see that, you have successfully set the Fault environment up on your +machine. + +To use the current folder inside the Docker container, you need to add these +options to the command: + +```sh +-v :/mount -w /mount +``` + +Obviously, replacing `` with your current path. For example, if +your current folder is `/Users/me/Code`, your options would be +`-v /Users/me/Code:/mount -w /mount`. + +This makes the final command: + +```sh +docker run -ti -v :/mount -w /mount --rm ghcr.io/cloud-v/fault:latest fault -V +``` + +### Tip on Unix-based systems + +You can set what is known a shell alias so you can avoid typing the long command +repeatedly. + +```sh +alias fault='docker run -tiv `pwd`:`pwd` -w `pwd` --rm ghcr.io/aucohl/fault:latest fault' +``` + +Then, you can invoke fault's options, by directly typing `Fault`. An equivalent +to the command above for example would be: + +``` +fault -V +``` + +Note that this command mounts the existing folder with an identical path, and +not to `/mount`. + +If you're on Windows, this section will not work as paths on that operating +system are incompatible with the Linux virtual machine. Not to mention, no +default Windows shells support bash aliases. + +## Bring-your-own-dependencies + +Fault requires a number of dependencies that you may elect to install manually. + +You need a Unix-based, Swift-compatible operating system. + +Again, if you're on Windows (or you're too lazy to follow these instructions,) +you can use the Docker container. + +We will not be supporting this option as too many things can go wrong, but here +are some pointers nevertheless. + +### Build Dependencies + +* [Swift 5.8+](https://swift.org) and the Swift Package Manager + * + a compatible version of Clang (included) +* Git + +### Run-time Dependencies + +- [Yosys](https://github.com/yosyshq/yosys) +- [IcarusVerilog](https://steveicarus.github.io/iverilog/usage/installation.html) + - You will need to set the environment variable `FAULT_IVL_BASE` to point to + the `ivl` directory installed by IcarusVerilog. +- [Python 3.8+](https://www.python.org/downloads/) with PIP and venv + - You will need to set the environment variable `PYTHON_LIBARY` to point to + the `.so`/`.dylib` file for Python. + - [Pyverilog](https://github.com/pyverilog/pyverilog) +- Atalanta (Optional) +- PODEM (Optional) + +### OS-Specific Instructions + +#### macOS +macOS 12 or higher is required. + +Install the latest Xcode from the Mac App Store. + +Use [Homebrew](https://brew.sh). + +`brew install python yosys icarus-verilog` + +#### Ubuntu GNU/Linux + +Ubuntu 20.04 or higher is required. + +Using apt: + +`sudo apt-get install git clang python3 python3-dev python3-pip python3-venv yosys iverilog` + +Then install the Swift programming language: instructions are on [swift.org](https://swift.org/download/#using-downloads). diff --git a/docs/Source/usage.md b/docs/Source/usage.md new file mode 100644 index 0000000..742be1b --- /dev/null +++ b/docs/Source/usage.md @@ -0,0 +1,221 @@ +# Usage Example + +In this tutorial, we will show a typical flow of an RTL design starting from +synthesis all the way to fault simulations and chain insertion. + +We will use the `s27` design which could be found in +[Benchmarks/ISCAS_89/s27.v](https://github.com/AUCOHL/Fault/blob/master/Benchmarks/ISCAS_89/s27.v). + +## Assumptions + +We also assume you've cloned the current repository and you are using it as your +current working directory. + +## Synthesis + +The first step is to generate a synthesized netlist for the `s27` module and we +will use the `synth` command with the following options: + +```bash + fault synth -l -t -o +``` + +- `-l` : specifies the path to the liberty file of the standard cell library to + which the RTL design is to be mapped to. + +- `-t`: specifies the top module of the design. + +- `-o`: specifies the path of the output netlist. In this example, we will use + the default path which is `Netlists/ + + .nl.v` + +To generate the synthesized netlist, run : + +```bash + fault synth -t s27 -l Tech/osu035/osu035_stdcells.lib Benchmarks/ISCAS_89/s27.v +``` + +This will run a yosys-based synthesis script and it will generate a flattened +netlist in the default path at `Netlists/s27.nl.v`. + +- For combinational circuits, add dummy clock and reset ports to the design. The + clock port doesn't have to be connected to anything, necessarily, but will be + used by Fault DFT later for the generated scan-chain. + +## Netlist Cutting + +Since the `s27` module contains sequential elements, performing netlist cutting +is necessary for the fault simulations. (This step is not required for purely +combinational designs.) + +```bash + fault cut -o +``` + +To generate the cut netlist, run: + +```bash + fault cut Netlists/s27.nl.v +``` + +This will remove all the netlist flip flops converting it into a pure +combinational netlist. The removed flip-flops will be exposed as input and +output ports. The generated comb-only (only combinational logic) netlist default +path is: `Netlists/s27.nl.v.cut.v ` + +The comb-only netlist is then used for performing fault simulations in the next +step. + +## Fault Simulations + +Test vectors are generated internally by a random number generator (RNG) or by +using [atalanta](https://github.com/hsluoyz/Atalanta). + +### A) Using Internal PRNGs + +The test vectors could be simulated incrementally such that the size of the set +is increased if sufficient coverage isn't met. This is done by the following +options: + +```bash +fault -v -r -m --ceiling -c +``` + +- `-v`: Number of the initially generated test vectors. + +- `-m`: Minimum coverage percentage that should be met by the generated test + vectors. + +- `-r`: Increment in the test vector count if minimum coverage isn't met. + +- `--ceiling`: Ceiling for the number of generated test vectors. If this number + is reached, simulations are stopped regardless of the coverage. + +- `-g`: Type of the test vector generator. Three types are supported: (1) swift: + uses Swift system RNG (2) LFSR: uses a linear feedback shift register as a RNG + (3) atalanta: uses atalanta atpg for generating TVs. Default value is swift. + +- `-c`: The cell models to use for simulations. + +In this example, we will use a minimum coverage of `95%`, an increment of `50`, +an initial test vector set size of `100` , and a ceiling of `1000` test vectors. + +We will also use the default value for `-g` option where swift's system +generator will be used for pseudo-random number generation. + +To run the simulations, invoke the following: + +```bash + fault -c Tech/osu035/osu035_stdcells.v -v 100 -r 50 -m 95 --ceiling 1000 Netlists/s27.nl.v.cut.v +``` + +This will generate the coverage at the default path: +`Netlists/s27.nl.v.cut.v.tv.json`. + +### B) Using Atalanta + +In this part, we will set the test vector generator to Atalanta. But, before +running the simulations we have to convert the comb-only netlist (.cut netlist) +to bench format because atalanta is compatible only with bench format. + +The bench conversion is supported by `bench` option: + +```bash + fault bench -c -o +``` + +- `-c`: Path of the cell models library. Fault converts the cell library to json + representation for easier cell extraction. So, if .json file is available from + previous runs, the file could be passed directly. +- `-o`: Path of the output bench netlist. Default is + ` + .bench` + +To generate bench netlist, invoke the following: + +``` + fault bench -c Tech/osu035/osu035_stdcells.v Netlists/s27.nl.v.cut.v +``` + +This will generate the json representation for the osu035 cell library at: +`Tech/osu035/osu035_stdcells.v.json` which could be used for subsequent runs. + +The bench netlist will be generated at ` Netlists/s27.nl.v.cut.v.bench` + +After the bench netlist is created, we can generate test vectors using atalanta +and run fault simulations by setting the following options: + +- `-g`: Type of the test vector generator. Set to `atalanta` +- `-c`: Cell models file path. +- `-b`: Path to the bench netlist. + +```bash + fault -g atalanta -c Tech/osu035/osu035_stdcells.v -b Netlists/s27.nl.v.cut.v.bench Netlists/s27.nl.v.cut.v +``` + +This will run the simulations with the default options for the initial TV count, +increment, and ceiling. TV coverage will be generated at the default path +`Netlists/s27.nl.v.cut.v.tv.json` + +## Compaction + +`Compact` option is used to reduce the size of the test vector generated in the +previous step while maintaining the same coverage. + +```bash + fault compact -o +``` + +To run compact, invoke: + +```bash + fault compact Netlists/s27.nl.v.cut.v.tv.json +``` + +This will generate the compacted test vector set which is output in the default +path at: `fault compact Netlists/s27.nl.v.cut.v.tv.json.compacted.json` + +## Scan Chain Insertion + +`Chain` performs scan chain insertion through the netlist's internal flip-flops. +It has the following options: + +```bash + fault chain -i --clock --reset -l -c -o +``` + +- `-i`: Specifies the inputs to ignore (if any) +- `--clock`: Clock signal name which is automatically added to the ignored + inputs. +- `--reset`: **Asynchronous** Reset signal name which is also automaticallyadded + to the ignored inputs. + - `--activeLow`: If your reset is active low, also include this flag. +- `-l`: specifies the path to the liberty file of the standard cell library. +- `-c`: cell models file to verify the scan chain integrity. +- `-o`: path of the chained netlist. + +The chained netlist could be generated by running: + +```bash + fault chain -l Tech/osu035/osu035_stdcells.lib -c Tech/osu035/osu035_stdcells.v --clock CK --reset reset Netlists/s27.nl.v +``` + +This will generate the chained netlist at the default path: +`Netlists/s27.nl.v.chained.v` + +## JTAG Interface Insertion + +In this part, we will add the JTAG port to the chained netlist. To run tap, we +set the following options: + +- `-o`: Path to the output file. (Default: input + .jtag.v) +- `--clock`: Clock signal of core logic to use in simulation +- `--reset`: Reset signal of core logic to use in simulation. +- `--activeLow`: Reset signal of core logic is active low instead of active + high. +- `-c`: Cell models file to verify JTAG port using given cell model. +- `-l`: Path to the liberty file for resynthesis. + +To run tap option, invoke the following + +```bash + fault tap -l Tech/osu035/osu035_stdcells.lib -c Tech/osu035/osu035_stdcells.v -l Tech/osu035/osu035_stdcells.lib -c Tech/osu035/osu035_stdcells.v --clock CK --reset reset Netlists/s27.nl.v.chained.v +``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..e5f1536 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,14 @@ +# docs +furo==2023.8.19 +docutils>=0.17,<1 +sphinx>=7.2.2 +sphinx-autobuild>=2021.3.14 +sphinx-autodoc-typehints>=1.24.0 +sphinx-design>=0.5.0,<1 +myst-parser>=2.0.0,<3 +docstring-parser>=0.15,<1 +sphinx-tippy>=0.4.1,<1 +sphinx-copybutton>=0.5.2,<1 +sphinxcontrib-spelling>=8.0.0,<9 +sphinxcontrib-bibtex>=2.6.0,<3 +sphinx-subfigure>=0.2.4,<1