deploy: 21f7af7

cad-polito-it · Sep 19, 2024 · dda5bb2 · dda5bb2
commit dda5bb2
Show file tree

Hide file tree

Showing 37 changed files with 15,658 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: d3345d70796f923144d81a159eb74eb1
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.nojekyll b/.nojekyll
diff --git a/_images/testcrush.png b/_images/testcrush.png
diff --git a/_modules/index.html b/_modules/index.html
@@ -0,0 +1,88 @@
+
+<!DOCTYPE html>
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta charset="utf-8" />
+    <title>Overview: module code &#8212; TestCrush 0.5.0 documentation</title>
+    <link rel="stylesheet" href="../_static/classic.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+    <script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+    <script src="../_static/jquery.js"></script>
+    <script src="../_static/underscore.js"></script>
+    <script src="../_static/doctools.js"></script>
+    <script src="../_static/language_data.js"></script>
+
+    <link rel="shortcut icon" href="../_static/favicon.png"/>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="../genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="../py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="nav-item nav-item-0"><a href="../index.html">TestCrush 0.5.0 documentation</a> &#187;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+
+  <h1>All modules for which code is available</h1>
+<ul><li><a href="utils.html">utils</a></li>
+</ul>
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+<h3><a href="../index.html">Table of Contents</a></h3>
+<p class="caption"><span class="caption-text">Contents:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../asm.html">asm module</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../zoix.html">zoix module</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../a0.html">a0 module</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../utils.html">utils module</a></li>
+</ul>
+
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="../search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="../genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="../py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="nav-item nav-item-0"><a href="../index.html">TestCrush 0.5.0 documentation</a> &#187;</li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2024, Nikolaos I. Deligiannis.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.4.
+    </div>
+  </body>
+</html>
diff --git a/_modules/utils.html b/_modules/utils.html
diff --git a/_sources/a0.rst.txt b/_sources/a0.rst.txt
@@ -0,0 +1,18 @@
+=========
+a0 module
+=========
+
+This module implements the `A0 compaction algorithm <https://doi.org/10.1109/TC.2016.2643663>`_ . The only difference 
+with respect to the original A0 algorithm is that in order to validate a removal of an instruction from the STL, the 
+evaluation happens on whether the new test application time is less or equal than the old test application time **AND**
+whether the new test coverage is **greater or equal** than the old test application time. However, with the provided
+utilities provided with the toolkit this can be extended or modified to the user's needs. All it takes is a few LoC
+in the evaluation method of each iteration within the A0 class.
+
+A0
+--
+
+.. autoclass:: a0.A0
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/_sources/asm.rst.txt b/_sources/asm.rst.txt
@@ -0,0 +1,49 @@
+===========
+asm module 
+===========
+
+The ``asm.py`` module contains utilities to handle file I/O operations on arbitrary assembly files.
+The purpose is to remove and to restore lines from the associated assembly file accurately.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+---
+ISA
+---
+
+This class, which implements the Singleton pattern, is used to parse a 
+user-defined `language file <https://github.com/cad-polito-it/testcrush/tree/main/langs>`_ and offers
+utilities to check whether an arbitrary string is a valid instruction according to the language file.
+
+.. autoclass:: asm.ISA
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+--------
+Codeline
+--------
+
+This is a dataclass to represent a single line of assembly code. Note that the ``lineno`` attribute
+which corresponds to the line number of the code line in the assembly file uses **0-based** indexing!
+
+.. autoclass:: asm.Codeline
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+---------------
+AssemblyHandler
+---------------
+
+This class, utilises ``ISA`` and ``Codeline`` to parse a **single** assembly file and store its code
+in chunks (lists) of ``Codeline`` objects. It offers utilities for removing and restoring arbitrary 
+lines of code from the file while keeping track of the changes performed and accurately updating the
+``lineno`` attributes of the stored code lines when needed.
+
+.. autoclass:: asm.AssemblyHandler
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
@@ -0,0 +1,33 @@
+.. TestCrush documentation master file, created by
+   sphinx-quickstart on Wed Sep 11 06:49:34 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+TestCrush documentation
+=======================
+
+.. image:: _static/testcrush.png
+
+TestCrush is a toolkit for compaction of software test libraries 
+which are written in assembly. The tool expects a configuration JSON file 
+from the user and a pre-existing logic and fault simulation flow for your 
+design(s).
+
+TestCrush implements the algorithms ``A0`` and ``A1xx`` of the journal publication
+
+   M. Gaudesi, I. Pomeranz, M. S. Reorda and G. Squillero, "New Techniques to 
+   Reduce the Execution Time of Functional Test Programs," in IEEE 
+   Transactions on Computers, vol. 66, no. 7, pp. 1268-1273, doi: 10.1109/TC.2016.2643663.
+
+
+Version 0.5.0
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   asm
+   zoix
+   a0
+   utils
diff --git a/_sources/utils.rst.txt b/_sources/utils.rst.txt
@@ -0,0 +1,10 @@
+============
+utils module
+============
+
+The ``utils.py`` module contains utility classes and functions that are used by all of the other modules such as e.g, logging.
+
+.. automodule:: utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/_sources/zoix.rst.txt b/_sources/zoix.rst.txt
@@ -0,0 +1,82 @@
+===========
+zoix module
+===========
+
+The ``zoix.py`` module contains utilities to perform calls to `VC-Z01X <https://www.synopsys.com/verification/simulation/vc-z01x.html>`_ 
+It is based on the `subprocess <https://docs.python.org/3/library/subprocess.html>`_ package and depends heavily on user-defined parameters.
+
+-----------
+ZoixInvoker
+-----------
+This class is the responsible for issuing calls to VC-Z01X. It offers utilities to compile HDL sources in VCS,
+logic simulate these sources, generate fault campaign manager sripts and finally, fault simulate the sources
+in Z01X. It assumes a pre-existing a tested and working VC-Z01X environment for a DUT and all function arguments
+are passed as variadic args and keyword arguments. The reason for this design choice is to abstract as much as
+possible from any version-specific niece that VC-Z01X might have. Hence, we offer this layer of abstraction and
+leave it to the user to specify compilation and simulation isntructions to be executed in the methods of the
+``ZoixInvoker`` e.g., by a .json configuration file.
+
+
+.. autoclass:: zoix.ZoixInvoker
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+--------------
+CSVFaultReport
+--------------
+This class manages the results of the fault simulation which are expected to be in a **CSV** format. Namelly,
+the fault summary and the fault list which are generated when the fcm (fault campaign manager) script contains 
+the ``report -csv`` instruction. This is a **hard** requirement for the whole TestCrush framework to work. The
+reason for not relying on the textual fault reports is once again the nieces that are introduced in different
+VC-Z01X versions. The ``.txt`` fault summary and report are sometimes poorly indented, and in general require
+regexp parsing. Hence, the CSVs. Nothing can go wrong with an ol'reliable format like this.
+
+.. autoclass:: zoix.CSVFaultReport
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+-----
+Fault 
+-----
+This class is used to represent a fault. However, once again in order to make it as general as possible, all
+attributes of the ``Fault`` class are passed as keyword arguments. Hence, they can be arbitrarily selected.
+For instance, the CSV fault report of VC-Z01X contains the faults like this:
+
+>>>
+"FID","Test Name","Prime","Status","Model","Timing","Cycle Injection","Cycle End","Class","Location"
+1,"test1","yes","ON","0","","","","PORT","tb_top.wrapper_i.top_i.core_i.ex_stage_i.alu_i.U10.Z"
+2,"test1",1,"ON","0","","","","PORT","tb_top.wrapper_i.top_i.core_i.ex_stage_i.alu_i.U10.A"
+3,"test1","yes","ON","1","","","","PORT","tb_top.wrapper_i.top_i.core_i.ex_stage_i.alu_i.U10.Z"
+
+The header row of this CSV snippet represents the attributes of the ``Fault`` objects, with all spaces
+substituted with underscores (_) (e.g., ``"Test Name" -> "Test_Name"``) and each subsequent row contains
+the corresponding values to those attributes. Its used by the ``CSVFaultReport`` for coverage computation
+and fault list parsing.
+
+.. autoclass:: zoix.Fault
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+--------------------------
+VC-Z01X Status Enumerators
+--------------------------
+
+.. autoclass:: zoix.Compilation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. autoclass:: zoix.LogicSimulation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: zoix.FaultSimulation
+   :members:
+   :undoc-members:
+   :show-inheritance: