Run tests on faster machine + update documentation

.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

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] = []
 

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)
 

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

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 </path/to/folder>:/mount -w /mount
-```
-
-Obviously, replacing `</path/to/folder>` 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 </path/to/folder>:/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)

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 <liberty-file>  -t <top-module-name> -o <output-netlist-path> <RTL-design-path> 
+fault synth -l <liberty-file> -t <top-module-name> [-o <output-netlist-path>]. <RTL-design-path> 
 ```
 
 - `-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 <output-cut-netlist-path> <flattened-netlist-path> 
+fault cut [-o <output-cut-netlist-path>] [--sclConfig <scl configuration file>] <flattened-netlist-path>
+<bypass options> 
+```
+
+```{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 <initial TV count> -r <increment> -m <minCoverage> --ceiling <TV count ceiling> -c <cell models> --clock <clock port> --reset <reset port> [--ignoring <ignored port 1> [--ignoring <ignored port 2> ] ] [ --activeLow] <netlist> 
+fault [-v <initial TV count>] [-r <increment>] [-m <minCoverage>] [--ceiling <TV count ceiling>] [-c <cell models>] <netlist> <bypass options> 
 ```
 
 - `-v`: Number of the initially generated test vectors.
@@ -100,14 +125,6 @@ fault -v <initial TV count> -r <increment> -m <minCoverage> --ceiling <TV count
 
 - `-c`: The cell models to use for simulations.
 
-- `--clock`: The name of the clock port.
-
-- `--ignoring`: The name of any other ports to ignore during ATPG, which will
-  be held high.
-
-- `--activeLow`: If set, all ports specified by `--ignoring` will be held low
-  instead.
-
 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.
 
@@ -117,7 +134,7 @@ 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 --clock CK --ignoring reset Netlists/s27.cut.v
+fault -c Tech/osu035/osu035_stdcells.v -v 100 -r 50 -m 95 --ceiling 1000 Netlists/s27.cut.v --clock CK --reset reset --bypassing VDD=1 --bypassing GND=0
 ```
 
 This will generate the coverage at the default path:
@@ -127,46 +144,28 @@ This will generate the coverage at the default path:
 
 In this part, we will use an external test vector generation. But, before
 running the simulations we have to convert the comb-only netlist (.cut netlist)
-to the .bench format accepted by Quaigh or Atalanta.
+to the .bench format accepted by Quaigh or Atalanta. We use a tool called
+`nl2bench` to do that.
 
 ```{note}
 Quaigh is bundled with Fault, but Atalanta is not as it is proprietary software.
 ```
 
-<!--
-First of all, convert the cut netlist to Verilog as follows:
-
-```bash
-yosys-abc -F /dev/stdin <<HD
-read Tech/osu035/osu035_stdcells.lib
-read -m Netlists/s27.cut.v
-write_bench -l Netlists/s27.bench
-HD
-```
--->
 ```bash
-fault bench -c <cell-models-file> -o <bench-netlist-output-path> <comb-only-netlist-path>
+nl2bench <cut netlist> -o <path to output bench file> -l <liberty file 0> [-l <liberty file 1> [-l <liberty file 2> …]]
 ```
 
-- `-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
   `<comb-only-netlist-path> + .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 <inputs-to-ignore> --clock <clk-signal> --reset <rst-signal> -l <liberty-file> -c <cell-models-file> -o <path-to-chained-netlist> <flattened-netlist-path>
+fault chain -l <liberty-file> -c <cell-models-file> -o <path-to-chained-netlist> <flattened-netlist-path> <bypass options>
 ```
 
-- `-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
 ```