doc about issues with VHDL cosimulation

doc/source/manual/conversion.rst

@@ -579,6 +579,59 @@ there are other cases that cannot be transformed to equivalent
 VHDL. The convertor will detect those cases and give an error.
 
 
+.. _conv-testbench:
+
+Conversion of test benches
+==========================
+
+
+After conversion, we obviously want to verify that the VHDL or Verilog
+code works correctly. In previous MyHDL versions, the proposed
+verification technique was co-simulation: use the same MyHDL test
+bench to simulate the converted Verilog code and the original MyHDL
+code.
+
+
+The proposed alternative is to convert the test bench itself, so that
+both test bench and design can be run in the HDL simulator. Of course,
+this is not a fully general solution either, as there are important
+constraints on the kind of code that can be converted. However, with
+the additional features that have been developed, it should be a
+useful solution for the purpose of verifying converted code.
+
+The question is whether the conversion restrictions permit to develop
+sufficiently complex test benches. In this section, we present some
+insights about this.
+
+The most important restrictions are the types that can be used. These
+remain "hardware-oriented" as before.
+
+Even in the previous MyHDL release, the "convertible subset" was much
+wider than the "synthesis subset". For example, :keyword:`while` and
+:keyword:`raise` statement were already convertible.
+
+The support for :func:`delay()` objects is the most important new feature
+to write high-level models and test benches.
+
+With the :keyword:`print` statement, simple debugging can be done.
+
+Of particular interest is the :keyword:`assert` statement. Originally,
+:keyword:`assert` statements were only intended to insert debugging
+assertions in code. Recently, there is a tendency to use them to write
+self-checking unit tests, controlled by unit test frameworks such as
+``py.test``. In particular, they are a powerful way to write
+self-checking test benches for MyHDL designs. As :keyword:`assert`
+statements are now convertible, a whole test suite in MyHDL can be
+converted to an equivalent test suite in Verilog and VHDL.
+
+Finally, the same techniques as for synthesizable code can be used
+to master complexity. In particular, any code outside generators
+is executed during elaboration, and therefore not considered in
+the conversion process. This feature can for example be used for
+complex calculations that set up constants or expected results.
+Furthermore, a tuple of ints can be used to hold a table of
+values that will be mapped to a case statement in Verilog and VHDL.
+
 
 
 .. _conv-meth:

doc/source/manual/cosimulation.rst

@@ -404,14 +404,28 @@ for Python exceptions that cannot be easily explained.
 
 .. _cosim-impl-vhdl:
 
-VHDL
+What about VHDL?
-----
+----------------
 
 It would be nice to have an interface to VHDL simulators such as the Modelsim
-VHDL simulator. This will require a PLI module using the PLI of the VHDL
+VHDL simulator. Let us summarize the requirements to accomplish that:
-simulator.
 
-The MyHDL project currently has no access to commercial VHDL simulators, so
+* We need a procedural interface to the internals of the simulator.
-progress in co-simulation support will depend on external interest and
+* The procedural interface should be a widely used industry standard so that we
-participation.
+  can reuse the work in several simulators.
+* MyHDL is an open-source project and therefore there should be also be an open-source
+  simulator that implements the procedural interface.
 
+
+``vpi`` for Verilog matches these requirements. It is a widely used standard
+and is supported by the open-source Verilog simulators Icarus and cver.
+
+However, for VHDL the situation is different. While there exists a standard
+called ``vhpi``, it  much less popular than ``vpi``. Also, it is unclear
+whether there exists
+an open source VHDL simulator with ``vhdl`` capabilities that are powerful
+enough for MyHDL's purposes.
+
+
+Consequently, the development of cosimulation for VHDL is currently on
+hold. For some applications, there is an alternative: see :ref:`conv-testbench`.

doc/source/whatsnew/0.6.rst

@@ -289,8 +289,8 @@ with it:
   its internal workings, such as ``vpi`` for Verilog and ``vhpi`` for
   VHDL.
 
-* vpi`` for Verilog is well-established and available for
+* ``vpi`` for Verilog is well-established and available for
-  open-source simulators such as Icarus and cver). However, ``vhpi`` for
+  open-source simulators such as Icarus and cver. However, ``vhpi`` for
   VHDL is much less established; it is unclear whether there is an open
   source solution that is powerful enough for MyHDL's purposes.