Skip to content

Commit

Permalink
Docs to ReadTheDocs
Browse files Browse the repository at this point in the history
  • Loading branch information
donn committed Jun 28, 2024
1 parent b0c00ee commit 75464d7
Show file tree
Hide file tree
Showing 11 changed files with 736 additions and 64 deletions.
15 changes: 15 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -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
58 changes: 0 additions & 58 deletions Installing.md

This file was deleted.

10 changes: 4 additions & 6 deletions Readme.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.

Expand Down
2 changes: 2 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
/venv
/build
29 changes: 29 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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)
57 changes: 57 additions & 0 deletions docs/Source/benchmarks.md
Original file line number Diff line number Diff line change
@@ -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 |
158 changes: 158 additions & 0 deletions docs/Source/conf.py
Original file line number Diff line number Diff line change
@@ -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": """
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
<path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
</svg>
""",
"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
Loading

0 comments on commit 75464d7

Please sign in to comment.