myhdl/doc/source/whatsnew/0.7.rst

.. _new07:

***********************
What's new in MyHDL 0.7
***********************

Conversion to VHDL/Verilog rewritten with the ``ast`` module
============================================================

The most important code change is a change that hopefully no-one will
notice :-).  The conversion code is now based on the ``ast`` package
instead of the ``compiler`` package.  Since Python 2.6, the
``compiler`` package is deprecated and replaced by the new ``ast``
package in the standard library. In Python 3, the ``compiler`` package
is no longer available.

This was a considerable effort, spent on re-implementing existing
behavior instead of on new interesting features.  This was
unfortunate, but it had to be done with priority.  Now the conversion
code is ready for the future.


Shadow signals
==============

Background
----------

Compared to HDLs such as VHDL and Verilog, MyHDL signals are less
flexible for structural modeling. For example, slicing a signal
returns a slice of the current value. For behavioral code, this is
just fine. However, it implies that you cannot use such as slice in
structural descriptions. In other words, a signal slice cannot be used
as a signal.




User interface
--------------



Example
-------




Using :class:`Signal` and :class:`intbv` objects as indices directly
====================================================================

Previously, it was necessary convert :class:`Signal` and :class:`intbv` objects
explicity to :class:`int` when using them as indices for
indexing and slicing. This conversion is no longer required;
the objects can be used directly.
The corresponding classes now have an :func:`__index__` method
that takes care of the type conversion automatically.
This feature is fully supported by the VHDL/Verilog convertor.


New configuration attributes for conversion file headers
========================================================

New configuration attributes are available to control the file
headers of converted output files.

.. attribute:: toVerilog.no_myhdl_header

   Specifies that MyHDL conversion to Verilog should not generate a
   default header. Default value is *False*.

.. attribute:: toVHDL.no_myhdl_header

   Specifies that MyHDL conversion to VHDL should not generate a
   default header. Default value is *False*.

.. attribute:: toVerilog.header

   Specifies an additional custom header for Verilog output.

.. attribute:: toVHDL.header

   Specifies an additional custom header for VHDL output.

The value for the custom headers should be a string
that is suitable for the standard :class:`string.Template` constructor.
A number of variables (indicated by a ``$`` prefix)
are available for string interpolation.
For example, the standard header is defined as follows::

    myhdl_header = """\
    -- File: $filename
    -- Generated by MyHDL $version
    -- Date: $date
    """

The same interpolation variables are available in custom headers.



Conversion propagates docstring-based comments
==============================================

The convertor now propagates user comments under the form
of Python docstrings.

Docstrings are typically used in Python to document certain
objects in a standard way. Such "official" docstrings are
put into the converted output on an appropriate locations.

However, "nonofficial" docstrings are propagated also. These
are strings (triple quoted by convention) that can occur
anywhere between statements. 

Regular Python comments are ignored by the Python parser,
and they are not present in the parse tree. Therefore, these
are not propagated. Note that through the use of docstrings,
you have an elegant way to specify which comments should be
propagated and which not.


New method to specify user-defined code
=======================================

The current way to specify user-defined code for conversion is through
the ``__vhdl__`` and ``__verilog__`` hooks.  This method has a number
of disadvantages.

First, the use of "magic" variables (whose names start and end with
double underscores) was a bad choice.  According to Python
conventions, such variables should be reserved for the Python language
itself.  Moreover, when new hooks would become desirable, we would
have to specify addtional magic variables.

A second problem that standard Python strings were used to define
the user-defined output. These strings can contain the signal
names from the context for interpolation. Typically, these are
multiple-line strings that may be quite lengthy. When something
goes wrong with the string interpolation, the error messages may
be quite cryptic as the line and column information is not present.

For these reasons, a new way to specify user-defined code has
been implemented that avoids these problems.

The proper way to specify meta-information of a function is by using
function attributes. Suppose a function :func:`<func>` defines
a hardware module. We can now specify user-defined code for it
with the following function attributes:

.. attribute:: <func>.vhdl_code

    A template string for user-defined code in the VHDL output.

.. attribute:: <func>.verilog_code

    A template string for user-defined code in the Verilog output.

When such a function attribute is defined, the normal conversion
process is bypassed and the user-defined code is inserted instead.
The template strings should be suitable for the standard
:class:`string.Template` constructor. They can contain interpolation
variables (indicated by a ``$`` prefix) for all signals in the
context. Note that the function attribute can be defined anywhere where
:func:`<func>` is visible, either outside or inside the function
itself.

The old method for user-defined code is still available but will be
deprecated in the future.



More powerful mapping to case statements
========================================

The convertor has become more powerful to map if-then-else structures
to case statements in VHDL and Verilog. Previously, only
if-then-else structures testing enumerated types were considered.
Now, integer tests are considered also.



Small changes
=============

Default value of :class:`intbv` objects
---------------------------------------

The default initial value of an :class:`intbv` object has been
changed from *None* to ``0``. Though this is backward-incompatible,
the *None* value never has been put to good use, so this is
most likely not an issue.


Combinatorial always blocks use blocking assignments
----------------------------------------------------

The convertor now uses blocking assignments for combinatorial
always blocks in Verilog. This is in line with generally
accepted Verilog coding conventions.

No synthesis pragmas in Verilog output
--------------------------------------

The convertor no longer outputs the synthesis pragmas
``full_case`` and ``parallel_case``. These pragmas do
more harm than good as they can cause simulation-synthesis
mismatches. Synthesis tools should be able to infer the
appropriate optimizations from the source code directly.