Updated docs (build pages)

docs/source/_static/custom.css

@@ -0,0 +1,10 @@
+.table {
+    display: block;
+    overflow-x: auto;
+    white-space: nowrap;
+}
+
+.docutils .csv-table {
+    table-layout: auto; /* Let the table resize based on its content */
+    width: 100%; /* Ensure the table takes the full width */
+}

docs/source/a0.rst

@@ -1,13 +1,14 @@
-=========
-a0 module
-=========
 
-This module implements the `A0 compaction algorithm <https://doi.org/10.1109/TC.2016.2643663>`_ . The only difference 
+============
+A0 Algorithm
+============
+
+Implementation of 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.
+in the evaluation method of each iteration within the A0 class. 
 
 A0
 --
@@ -16,3 +17,64 @@ A0
    :members:
    :undoc-members:
    :show-inheritance:
+
+Preprocessing
+-------------
+It is possible to perform preprocessing in the set of assembly candidates to reduce the runtime of the A0 algorithm. The runtime of 
+the algorithm solely depends on the total number of candidates to be considered in each iteration. It is a brute-force approach to 
+the compaction problem. So the idea is the following. What 
+if, after we execute the `pre_run()` of the A0 algorithm to obtain the initial STL statistics, we are able to assess somehow
+the impact each Candidate has in terms of faults being detected?
+
+In order to obtain such information a couple of things are required. First, we need a fault report comming from Z01X with includes
+custom **fault attributes**. Secondly, we need a trace comming directly from the DUT after the execution of the original STL. The idea
+is to guide algorithm by leveraging useful state information stemming from the fault detection time of each fault. Assuming that the DUT is
+a pipelined processor, then this information must include (i) the simulation time and (ii) the program counter value. Then, by examining the
+contents of the trace, it is possible to map these program counter values and timestamps to instructions in the trace, and identify "hot-zones"
+of the STL. That is, codeline regions that contribute to the detection of the faults. 
+
+Fault Attributes
+^^^^^^^^^^^^^^^^
+After a Z01X fault simulation, it is possible to enable with ``report`` command the inclusion of the fault attributes by specifying the flag ``-showallattributes``.
+VC Z01X provides the ability to define custom fault attributes using key, value pairs. The fault coverage is reported in the coverage report for each key, value pair.
+To add such attributes to each fault one has to modify the ``strobe.sv`` file accordingly. Here is an example of attaching the simulation time and the program counter
+to a fault by modifying the strobe file.
+
+.. code-block:: systemverilog
+   
+   cmp = $fs_compare(`TOPLEVEL); // Check for differences between GM and FM
+   if (1 == cmp) begin
+      $fs_drop_status("ON", `TOPLEVEL);
+      $fs_add_attribute(1, "PC", "%h", {`TOPLEVEL.pc_id[31:1], 1'b0}); // Attach program counter
+      $fs_add_attribute(1, "sim_time", "%t", $time); // Attach simulation time
+   end else if (2 == cmp) begin
+      $fs_drop_status("PN", `TOPLEVEL);
+      $fs_add_attribute(1, "PC", "%h", {`TOPLEVEL.pc_id[31:1], 1'b0}); // Attach program counter
+      $fs_add_attribute(1, "sim_time", "%t", $time); // Attach simulation time
+   end
+
+By utilizing the ``$fs_add_attribute()`` directive we can easily add the required attributes to
+each detected fault. When the final fault report is generated with the ``-showallatributes`` flag,
+then the attributes are attached to every prime fault like this:
+
+   ::
+      
+   <  1> ON 1 {PORT "path.to.fault.site"}(* "testName"->PC="00000004"; "testName"->sim_time="   10ns"; *)
+
+Execution Trace
+^^^^^^^^^^^^^^^
+The execution trace is required in order to search for the hotzones with information stemming from the attributes reported in the fault reports. 
+By attaching adequate information on each fault, and of course, **relevant and acurate(!) to the one present in the trace** we can search within
+the STL execution trace for instances. For instance, we can search for ``<PC, Time>`` attribute pairs stemming from the fault report to pinpoint
+spatially and temporally the sequence of codelines that were executed and led to the fault detectiong. The PC values and times reported in the 
+attributes of the faults must comming from the exact same signals employed by the trace. Otherwise we may have off-by-one errors in our search 
+in the trace when trying to associate simulation times and program counter values for example. The trace, during processing, is written into a database, 
+which can be queried for retrieving rows with information comming from the fault attributes
+
+Preprocessor
+------------
+
+.. autoclass:: a0.Preprocessor
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/asm.rst

@@ -1,6 +1,6 @@
-===========
-asm module 
-===========
+======================
+Assembly File Handling
+======================
 
 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.

docs/source/conf.py

@@ -32,6 +32,9 @@
 
 html_theme = 'classic'
 html_static_path = ['_static']
+html_css_files = [
+    'custom.css',
+]
 html_sidebars = {
    '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
    'using/windows': ['windows-sidebar.html', 'searchbox.html'],

docs/source/config.rst

@@ -1,6 +1,6 @@
-=============
-config module
-=============
+=======================
+TestCrush Configuration
+=======================
 
 The ``config.py`` module contains configuration parsing and sanitization functions for testcrush. 
 The expected configuration format is TOML. Detailed information about the TOML configuration files

docs/source/grammar.rst

@@ -0,0 +1,21 @@
+====================
+Grammars and Parsing
+====================
+
+In order to process arbitrarily formated textual information, we resort to EBNF grammars and parsing. To achieve that,
+we depend on `Lark <https://lark-parser.readthedocs.io/en/latest/>`_. The structure of the ``grammar`` directory is the
+following. Each ``*.lark`` file nests a Lark-compliant grammar. We differentiate between two types of grammars. 
+
+   1. Grammars related to segments of the textual fault report (rpt) of zoix, which are prefixed with ``frpt_``
+   2. Grammars related to traces, which are prefixed with ``trace_``
+
+Each grammar must have its corresponding ``Transformer`` to traverse the AST and generate data structures. Specifically for the trace
+related grammars, what is expected from the transformer is to transform the AST into a CSV-ready format as a list of strings. 
+
+Whenever a new grammar is added with its corresponding transformer in the ``transformers.py`` the corresponding factories mush be updated
+accordingly.
+
+.. automodule:: grammars.transformers
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/index.rst

@@ -30,6 +30,7 @@ Version 0.5.0
 
    asm
    zoix
+   grammar
    a0
    utils
    config

docs/source/utils.rst

@@ -1,6 +1,6 @@
-============
-utils module
-============
+======================
+Miscellanous Utilities
+======================
 
 The ``utils.py`` module contains utility classes and functions that are used by all of the other modules such as e.g, logging.
 

docs/source/zoix.rst

@@ -1,6 +1,6 @@
-===========
-zoix module
-===========
+============
+Z01X Related 
+============
 
 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.
@@ -9,23 +9,38 @@ It is based on the `subprocess <https://docs.python.org/3/library/subprocess.htm
 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
+logic simulate these sources, and finally, fault simulate the sources in Z01X. It assumes a pre-existing 
+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.
+``ZoixInvoker`` e.g., by the TOML configuration file.
 
 
 .. autoclass:: zoix.ZoixInvoker
    :members:
    :undoc-members:
    :show-inheritance:
 
+-------------
+Fault Reports
+-------------
+We provide two classes for managing fault reports depending on their type.
 
---------------
+~~~~~~~~~~~~~~
+TxtFaultReport
+~~~~~~~~~~~~~~
+This class provides a simple parsing utility based on bracket-counting to extract sections from the textual
+fault report of Z01X (rpt file).
+
+.. autoclass:: zoix.TxtFaultReport
+   :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. For instance, if this command is specified ``report -csv -report fsim_out`` then
@@ -41,20 +56,26 @@ These correspond to the two constructor arguments of the ``CSVFaultReport`` obje
 -----
 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:
+This class is used to represent a **prime** fault. Once again, in order to abstract as musch as possible, all
+attributes of the ``Fault`` class are passed as keyword arguments. Hence, they can be arbitrarily set.
+For instance, assuming that we generate a fault list based on the the CSV fault report of VC-Z01X which contains
+entries of faults faults like:
+
+.. csv-table:: 
+   :header: "FID", "Test Name", "Prime", "Status", "Model", "Timing", "Cycle Injection", "Cycle End", "Class", "Location"
 
->>>
-"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"
+   1, "test1", "yes", "ON", "0", "", "", "", "PORT", "top.unit.cell.portA"
+   2, "test1", 1, "ON", "0", "", "", "", "PORT", "top.unit.cell.portB"
+   3, "test1", "yes", "ON", "1", "", "", "", "PORT", "top.unit.cell.portC"
 
 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.
+the corresponding values to those attributes. 
+
+With that said, each fault has two default, static attributes set by the constructor. These two attributes are
+the ``equivalent_to`` which expects another ``Fault`` type and by default is set  to ``None`` and ``equivalent_faults`` 
+which is an integer set to 1 counting the number of equivalent faults mapped to the current fault. These attributes can
+be accessed and modified in an ad-hoc manner.
 
 .. autoclass:: zoix.Fault
    :members: