From 40277f754c80a1a4f577418144a058b1b39a822d Mon Sep 17 00:00:00 2001 From: Nick Deligiannis Date: Wed, 16 Oct 2024 18:05:04 +0300 Subject: [PATCH] Updated docs (build pages) --- docs/source/_static/custom.css | 10 +++++ docs/source/a0.rst | 72 +++++++++++++++++++++++++++++++--- docs/source/asm.rst | 6 +-- docs/source/conf.py | 3 ++ docs/source/config.rst | 6 +-- docs/source/grammar.rst | 21 ++++++++++ docs/source/index.rst | 1 + docs/source/utils.rst | 6 +-- docs/source/zoix.rst | 57 ++++++++++++++++++--------- 9 files changed, 150 insertions(+), 32 deletions(-) create mode 100644 docs/source/_static/custom.css create mode 100644 docs/source/grammar.rst diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..95e0400 --- /dev/null +++ b/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 */ +} diff --git a/docs/source/a0.rst b/docs/source/a0.rst index 5caf242..56524cb 100644 --- a/docs/source/a0.rst +++ b/docs/source/a0.rst @@ -1,13 +1,14 @@ -========= -a0 module -========= -This module implements the `A0 compaction algorithm `_ . The only difference +============ +A0 Algorithm +============ + +Implementation of the `A0 compaction algorithm `_ . 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 ```` 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: \ No newline at end of file diff --git a/docs/source/asm.rst b/docs/source/asm.rst index 5340c14..b2eb2b6 100644 --- a/docs/source/asm.rst +++ b/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. diff --git a/docs/source/conf.py b/docs/source/conf.py index d2048e9..6e14b0d 100644 --- a/docs/source/conf.py +++ b/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'], diff --git a/docs/source/config.rst b/docs/source/config.rst index d5a20bf..fa5e6d8 100644 --- a/docs/source/config.rst +++ b/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 diff --git a/docs/source/grammar.rst b/docs/source/grammar.rst new file mode 100644 index 0000000..7775e1d --- /dev/null +++ b/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 `_. 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: diff --git a/docs/source/index.rst b/docs/source/index.rst index 972d67b..3210912 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,6 +30,7 @@ Version 0.5.0 asm zoix + grammar a0 utils config \ No newline at end of file diff --git a/docs/source/utils.rst b/docs/source/utils.rst index f0b7d6c..f1ad0d2 100644 --- a/docs/source/utils.rst +++ b/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. diff --git a/docs/source/zoix.rst b/docs/source/zoix.rst index 16b407d..41fb24c 100644 --- a/docs/source/zoix.rst +++ b/docs/source/zoix.rst @@ -1,6 +1,6 @@ -=========== -zoix module -=========== +============ +Z01X Related +============ The ``zoix.py`` module contains utilities to perform calls to `VC-Z01X `_ It is based on the `subprocess `_ package and depends heavily on user-defined parameters. @@ -9,12 +9,12 @@ It is based on the `subprocess >> -"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: