3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-06-07 06:33:24 +00:00

Docs: some restructure of advanced section

- Filling out index descriptions for `using_yosys` and `using_yosys/synthesis`.
- To discourage skipping over these index pages, the toctree in
  `using_yosys/index` is hidden and instead has inline links to the two
  subsections.
- Tidying todos.
- Moves technology mapping to `techmap_synth`, leaving the techmap by example in
  the internals section. `yosys_flows` gets split up, with the coarse-grain
  intro replaced by `synthesis/index`, the extract pass moving to
  `synthesis/extract` and model checking to `more_scripting/model_checking`.
This commit is contained in:
Krystine Sherwin 2024-01-26 13:06:02 +13:00
parent 4582ab59da
commit e2e7065590
No known key found for this signature in database
10 changed files with 259 additions and 273 deletions

View file

@ -9,5 +9,6 @@ More scripting
load_design
selections
interactive_investigation
model_checking
.. troubleshooting

View file

@ -0,0 +1,108 @@
Symbolic model checking
-----------------------
.. todo:: check text context
.. note::
While it is possible to perform model checking directly in Yosys, it
is highly recommended to use SBY or EQY for formal hardware verification.
Symbolic Model Checking (SMC) is used to formally prove that a circuit has (or
has not) a given property.
One application is Formal Equivalence Checking: Proving that two circuits are
identical. For example this is a very useful feature when debugging custom
passes in Yosys.
Other applications include checking if a module conforms to interface standards.
The :cmd:ref:`sat` command in Yosys can be used to perform Symbolic Model
Checking.
Checking techmap
~~~~~~~~~~~~~~~~
.. todo:: add/expand supporting text
Let's look at the following example:
.. literalinclude:: /code_examples/synth_flow/techmap_01_map.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/techmap_01_map.v``
.. literalinclude:: /code_examples/synth_flow/techmap_01.v
:language: verilog
:caption: ``docs/source/code_examples/synth_flow/techmap_01.v``
.. literalinclude:: /code_examples/synth_flow/techmap_01.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/synth_flow/techmap_01.ys``
To see if it is correct we can use the following code:
.. todo:: replace inline yosys script code
.. code:: yoscrypt
# read test design
read_verilog techmap_01.v
hierarchy -top test
# create two version of the design: test_orig and test_mapped
copy test test_orig
rename test test_mapped
# apply the techmap only to test_mapped
techmap -map techmap_01_map.v test_mapped
# create a miter circuit to test equivalence
miter -equiv -make_assert -make_outputs test_orig test_mapped miter
flatten miter
# run equivalence check
sat -verify -prove-asserts -show-inputs -show-outputs miter
Result:
.. code::
Solving problem with 945 variables and 2505 clauses..
SAT proof finished - no model found: SUCCESS!
AXI4 Stream Master
~~~~~~~~~~~~~~~~~~
The following AXI4 Stream Master has a bug. But the bug is not exposed if the
slave keeps ``tready`` asserted all the time. (Something a test bench might do.)
Symbolic Model Checking can be used to expose the bug and find a sequence of
values for ``tready`` that yield the incorrect behavior.
.. todo:: add/expand supporting text
.. literalinclude:: /code_examples/axis/axis_master.v
:language: verilog
:caption: ``docs/source/code_examples/axis/axis_master.v``
.. literalinclude:: /code_examples/axis/axis_test.v
:language: verilog
:caption: ``docs/source/code_examples/axis/axis_test.v``
.. literalinclude:: /code_examples/axis/axis_test.ys
:language: yoscrypt
:caption: ``docs/source/code_examples/axis/test.ys``
Result with unmodified ``axis_master.v``:
.. code::
Solving problem with 159344 variables and 442126 clauses..
SAT proof finished - model found: FAIL!
Result with fixed ``axis_master.v``:
.. code::
Solving problem with 159144 variables and 441626 clauses..
SAT proof finished - no model found: SUCCESS!