From 011af82ba84ee921a646ac242d99c96c2a4b40bd Mon Sep 17 00:00:00 2001 From: Mohamed Gaber Date: Fri, 26 Jul 2024 18:41:28 +0300 Subject: [PATCH] Run tests on faster machine + update documentation --- .github/workflows/ci.yml | 2 +- Sources/Fault/Entries/tap.swift | 3 - Tests/test_fault.py | 2 +- docs/Source/index.md | 16 ++--- docs/Source/installation.md | 100 +++----------------------------- docs/Source/usage.md | 99 ++++++++++++++----------------- 6 files changed, 57 insertions(+), 165 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dea86fa..ebc2006 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,7 +9,7 @@ on: jobs: test: name: Test/Nix - runs-on: ubuntu-24.04 + runs-on: macos-14 steps: - name: Check out Git repository uses: actions/checkout@v3 diff --git a/Sources/Fault/Entries/tap.swift b/Sources/Fault/Entries/tap.swift index 1920cf7..7fd618f 100644 --- a/Sources/Fault/Entries/tap.swift +++ b/Sources/Fault/Entries/tap.swift @@ -44,9 +44,6 @@ extension Fault { @Option(name: [.short, .long], help: ".bin file for golden output. Required iff testVectors is provided.") var goldenOutput: String? - @Option(name: [.short, .long], help: "Inputs to ignore. May be specified multiple times.") - var ignoring: [String] = [] - @Option(name: [.customShort("B"), .long, .customLong("blackboxModel")], help: "Files containing definitions for blackbox models. Comma-delimited. (Default: none)") var blackboxModels: [String] = [] diff --git a/Tests/test_fault.py b/Tests/test_fault.py index 5ce8f05..a0eccfc 100644 --- a/Tests/test_fault.py +++ b/Tests/test_fault.py @@ -10,7 +10,7 @@ def run(label, steps): if step[0] == "nl2bench": cmd = step else: - cmd = shlex.split(os.getenv("PYTEST_FAULT_BIN", "swift run Fault")) + step + cmd = shlex.split(os.getenv("PYTEST_FAULT_BIN", "swift run fault")) + step print(f"$ {shlex.join(cmd)}") subprocess.check_call(cmd) diff --git a/docs/Source/index.md b/docs/Source/index.md index 0e3ec00..cd64154 100644 --- a/docs/Source/index.md +++ b/docs/Source/index.md @@ -24,13 +24,7 @@ be skipped if the user wants to run their own synthesis script. 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 +## 3. 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 @@ -40,18 +34,16 @@ 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. +ATPG also optimizes the test vector set by eliminating redundant vectors. -### 6. Chain +### 4. 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 +### 5. 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_) diff --git a/docs/Source/installation.md b/docs/Source/installation.md index c4de9c2..532aab0 100644 --- a/docs/Source/installation.md +++ b/docs/Source/installation.md @@ -6,8 +6,6 @@ In order to use Fault, you have three options: - 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 @@ -22,74 +20,9 @@ the `fault` command available in path, you can ## 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. +We no longer provide Docker images ourselves. We intend to work with +[IIC-OSIC-TOOLS](https://github.com/iic-jku/IIC-OSIC-TOOLS) to make Fault +available via Docker and will update this document when we do. ## Bring-your-own-dependencies @@ -119,26 +52,7 @@ are some pointers nevertheless. - 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). + - [nl2bench](https://github.com/donn/nl2bench) (Required if using Quaigh or Atalanta) +- [Quaigh](https://github.com/coloquinte/quaigh) (Optional but really recommended) +- [Atalanta](https://github.com/hsluoyz/atalanta) (Optional) +- [NTU EE PODEM](https://github.com/donn/VLSI-Testing) (Optional) diff --git a/docs/Source/usage.md b/docs/Source/usage.md index 00b0533..0f9474f 100644 --- a/docs/Source/usage.md +++ b/docs/Source/usage.md @@ -8,16 +8,19 @@ We will use the `s27` design which could be found in ## Assumptions -We also assume you've cloned the current repository and you are using it as your +We assume you've cloned the current repository and you are using it as your current working directory. +If you're using Nix without installing to `PATH`, replace `fault` with +`nix run .#fault --`. + ## 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 +fault synth -l -t [-o ]. ``` - `-l` : specifies the path to the liberty file of the standard cell library to @@ -52,19 +55,41 @@ is necessary for the fault simulations. (This step is not required for purely combinational designs.) ```bash - fault cut -o +fault cut [-o ] [--sclConfig ] + +``` + +```{note} Bypass Options +You will notice a new option called "bypass options." + +Bypass options are shared across multiple steps. They list signals that are +to be bypassed by the scan-chain insertion process. This includes but is not +limited to: +* Clocks +* Resets +* VDD +* GND + +The flags are as follows: +* `--clock`: The name of the clock signal +* `--reset`: The name of the active-high reset signal +* `--activeLow`: Sets the reset to active-low instgead +* `--bypassing NAME[=0|1]`: Additional signals to bypass. Bypassed signals are + held low during simulations, but by adding `=1`, they will be held high + instead. + ``` To generate the cut netlist, run: ```bash -fault cut Netlists/s27.nl.v +fault cut Netlists/s27.nl.v --clock CK --reset reset --bypassing VDD=1 --bypassing GND=0 ``` 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.cut.v ` +path is: `Netlists/s27.cut.v` The comb-only netlist is then used for performing fault simulations in the next step. @@ -81,7 +106,7 @@ is increased if sufficient coverage isn't met. This is done by the following options: ```bash -fault -v -r -m --ceiling -c --clock --reset [--ignoring [--ignoring ] ] [ --activeLow] +fault [-v ] [-r ] [-m ] [--ceiling ] [-c ] ``` - `-v`: Number of the initially generated test vectors. @@ -100,14 +125,6 @@ fault -v -r -m --ceiling ```bash -fault bench -c -o +nl2bench -o -l [-l [-l …]] ``` -- `-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. +- `-l`: Path to the lib files. At least one must be specified, but + you may specify multiple. - `-o`: Path of the output bench netlist. Default is ` + .bench To generate a .bench netlist, invoke the following: ```bash -fault bench -c Tech/osu035/osu035_stdcells.v Netlists/s27.cut.v +nl2bench -o Netlists/s27.bench -l Tech/osu035/osu035_stdcells.lib Netlists/s27.cut.v ``` -```{note} -This will also generate a JSON representation for the osu035 cell library at: -`Tech/osu035/osu035_stdcells.v.json` which will be re-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 and run fault simulations by setting the following options: @@ -175,7 +174,7 @@ and run fault simulations by setting the following options: - `-b`: Path to the bench netlist. ```bash -fault atpg -g [Atalanta|Quaigh] -c Tech/osu035/osu035_stdcells.v -b Netlists/s27.bench Netlists/s27.cut.v --clock CK -i reset -i VDD -i GND +fault atpg -g [Atalanta|Quaigh] -c Tech/osu035/osu035_stdcells.v -b Netlists/s27.bench Netlists/s27.cut.v --clock CK --reset reset --bypassing VDD=1 --bypassing GND=0 ``` This will run the simulations with the default options for the initial TV count, @@ -188,15 +187,9 @@ increment, and ceiling. TV coverage will be generated at the default path It has the following options: ```bash - fault chain -i --clock --reset -l -c -o +fault chain -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. @@ -205,9 +198,9 @@ The chained netlist could be generated by running: ```bash fault chain\ + --clock CK --reset reset --bypassing VDD=1 --bypassing GND=0\ -l Tech/osu035/osu035_stdcells.lib\ -c Tech/osu035/osu035_stdcells.v\ - --clock CK --reset reset -i VDD -i GND\ Netlists/s27.nl.v ``` @@ -220,20 +213,16 @@ 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. -- `--ignoring`: Other signals to ignore -- `--activeLow`: Ignored signals (including reset) signal of core logic are held - low instead of high. - `-c`: Cell models file to verify JTAG port using given cell model. - `-l`: Path to the liberty file for resynthesis. +- Bypass options To run tap option, invoke the following ```bash fault tap\ + --clock CK --reset reset --bypassing VDD --bypassing GND\ -l Tech/osu035/osu035_stdcells.lib\ -c Tech/osu035/osu035_stdcells.v\ - --clock CK --reset reset -i VDD -i GND\ - Netlists/s27.nl.v.chained.v + Netlists/s27.chained.v ```