[myhdl-list] MEP : Signal Containers

[Christopher F. <chr...@gm...>]

The following is a *start* to a MEP that describes the conversion 
support for classes, lists, and dictionaries.  This is just a start of 
the enhancement description and does not include some of the mechanical 
(code changes) items worth identifying in a MEP.

I am posting the rough draft of the enhancement because there was 
interest in this enhancement and others might want to contribute to the 
MEP and code changes.  Also, some initial development might occur before 
Jan returns but finalization will await his review.

All feedback welcome.  After some time (initial feedback) this will be 
moved to the wiki.

Regards,
Chris

******************
Signal Containers
******************

Introduction
=============
The following is a proposal to add conversion support for Signal 
containers.  Signal containers are; classes, lists, and dictionaries 
that contain a Signal type.  Lists, and dictionaries are built-in data 
structures in the Python programming language.  A class is the common 
method to define objects.  For more information on Python classes, 
lists, and dictionaries see `[1]`_, `[2]`_, `[3]`_ and `[4]`_.

Another native data structure in the Python programming language is the 
tuple.  Tuples are non-mutable and not usable in this case.  Tuples are 
useful when defining `ROMS`_ and currently supported.  The rest of this
enhancement proposal will outline the addition of classes, lists, and
dictionaries to the MyHDL convertible subset of the Python programming 
language.  Through the rest of this document the term "container(s)" 
will be used to refer to data structures and objects that contains 
Signals and other convertible types.

.. _[1] : http://docs.python.org/tutorial/classes.html
.. _[2] : http://docs.python.org/tutorial/introduction.html#lists
.. _[3] : http://docs.python.org/tutorial/datastructures.html
.. _[4] : http://docs.python.org/tutorial/datastructures.html#dictionaries
.. _ROMS : 
http://www.myhdl.org/doc/0.6/manual/conversion_examples.html#rom-inference


The desired approach is to generate a unique name for a Signal that is 
part of a container.  If an expression includes a "container" a net name 
will be generate for the Signal, example ::

   myObject.x.next = ListOfSignal[10] + DictOfSignal['fred']

The above example has all three container types; a class, a list with 
signals and a dictionary with signals.  The conversion utilities would 
determine if the type referenced is a Signal and then create a unique 
name for the Signal. ::

   myObject_x = ListOfSignal_10 + DictOfSignal_fred

The converter will simply use the container's instance name as part of 
the net name.  The same rules that apply to hierarchy naming will be 
included.  The above might be converted to something like the following 
to avoid name collisions. ::

   mod1_mod2_myObject_x = mod1_mod2_ListOfSignal_10 + 
mod1_mod2_DictOfSignal_fred

In other cases a data structure might not contain a Signal but a 
constant (literals).  In this case the conversion methods will dig down 
to find the constant and use the constant value.

Required support:

  * Expansion of Signal container names
  * Containers as ports
  * Containers as sensitivity lists
  * Resolution of data in data structures



In general, containers can be used, as long as the final
referenced object is a convertible type (Signal, int, long, bool, 
intbv).  All of the above is supported for modeling in MyHDL 0.7, except 
for "containers as sensitivity lists" as discussed in the mailing-list.

This feature is similar to the VHDL record and SystemVerilog struct. 
The idea is that signals can be logically grouped.  This can be very 
useful to a designer to logically group signals.

Variables in containers
------------------------
Variables should be supported as well.  When variables are used, if 
needed, the variable should be converted to a long net name.  Variables 
in containers will follow the same rules as outlined for signals in a 
container.

Classes
========
Classes that contain Signals or a hierarchy of classes that eventually
contain a Signal should be converted.  Classes should be converted
according to the following rules:

   #. The object attribute referenced is a convertible type

      #. Left hand side : Signal of type intbv or bool
      #. Right hand side : int, long, bool, intbv or a Signal of type
         int, long, bool, intbv

   #. The object being referenced will be represented in the
      converted code as a long-net-name.  Long-net-names are
      derived by:

      #. Hierarchy name rules (which are?)
      #. Class path name, example ::
           class.refObj = class_refObj
           class1.class2.refObj = class1_class2_refObj


Example
--------
.. code-block :: python

   class MyObj(object):
      def __init__(self):
         x = Signal(intbv(0)[8:])
         y = Signal(intbv(0)[4:])
         z = Signal(intbv(0)[9:])

   def foo(clk, srst, xyz):

      @always(clk.posedge)
      def rtl():
	xyz.z.next = xyz.x + xyz.y

      return rtl

   if __name__ == '__main__':
      clk = Signal(False)
      xyz = MyObj()
      toVerilog(foo, clk, xyz)

Verilog example conversion for the above.

.. code-block :: verilog

    module foo
    (
      input  wire  clk,
      input  wire  [7:0] MyObj_x,
      input  wire  [3:0] MyObj_y,
      output wire  [8:0] MyObj_z
   ):

      always @(posedge clk) begin
         MyObj_z <= MyObj_x + MyObj_y
      end

   endmodule

VHDL example conversion.
.. code-block :: vhdl

    -- TBC

Conversion of class methods
----------------------------
Generally speaking, the conversion of a class method that is a generator 
(yields not returns) is convertible.  But it is not supported because 
the first argument to a class method is the object instance that 
contains the method (usually self).  In conversion this is converted as 
a port.  Another change proposed in this MEP is to ignore the first 
parameter of a class method so that class methods can be converted 
directly.  This makes the conversion of classes more complete.

For class methods, the only exception (difference) to the converter 
compared to a standard function is to ignore the first argument of the 
class method.  The rest of the conversion would functionally be 
equivalent to the function conversion.


Heterogeneous List Of Signals
==============================
Here heterogeneous is used to differentiate a list of signals that 
contain different signal types versus list of signals that is 
homogeneous, all the same type of signals.  Homogeneous list of signals 
are currently supported and convert to the underlying HDL as an array of 
bit-vectors.  This is useful for defining `memories`_.

The functions that determines a memory object will need to be enhanced 
to differentiate a homogeneous list of signals from a heterogeneous list 
of signals.

.. _memories : 
http://www.myhdl.org/doc/0.6/manual/conversion_examples.html#ram-inference


Dictionaries
============
Similar to the class conversion dictionaries should be convertible as
well.  The same rules that applied to class conversion should be applied
to dictionaries.