Streamlined interface documentation

doc/source/manual/conversion.rst

@@ -73,15 +73,13 @@ Generator are mapped to Verilog or VHDL constructs
   it will map them to ``process`` statements or concurrent signal assignments.
 
 The module ports are inferred from signal usage
-  In MyHDL, the input or output direction of interface signals is not explicitly
+  In MyHDL, the input or output direction of ports is not explicitly
   declared. The converter investigates signal usage in the design hierarchy to
   infer whether a signal is used as input, output, or as an internal signal.
 
-Interfaces are expanded
-  MyHDL provides a power mechanism to define complex module interfaces.
-  These interfaces are name extended to individual signals in the target
-  HDL (Verilog and VHDL).  This enables MyHDL to support higher-level 
-  abstractions that are not available in the target HDL.
+Interfaces are convertible 
+  An *interface*: an object that has a number of :class:`Signal` objects as its
+  attributes. The convertor supports this by name expansion and mangling.
 
 Function calls are mapped to Verilog or VHDL subprograms
   The converter analyzes function calls and function code. Each function is
@@ -434,16 +432,15 @@ description of RAM memories.
 
 Conversion of Interfaces
 ========================
-Interfaces simplify the complicated interconnect between modules.
-In MyHDL the interfaces provide an intuitive approach to group
-logically related ports.  The grouping of ports has many benefits
-such as reducing complexity and increasing modularity.
 
-The converter will name extend the interfaces during conversion,
-in the converted code each attribute will appear as a individual 
-signal.  Because the hierarchy is flattened the name extension 
-may need to include information on the where in the hierarchy
-the interface occurs to prevent name collisions.
+Complex designs often have many signals that are passed to different levels of
+hierarchy.  Typically, many signals logically belong together. This can be
+modelled by an *interface*: an object that has a number of :class:`Signal`
+objects as its attributes.  Grouping signals into an interface simplifies the
+code, improves efficiency, and reduces errors.
+
+The convertor supports interface using hierarchical name expansion and name
+mangling. 
 
 .. _conv-meth-assign:
 

doc/source/whatsnew/0.9.rst

@@ -17,17 +17,12 @@ Interfaces (Conversion of attribute accesses)
 
 Rationale
 ---------
-Complex designs often have many signals (ports) that are passed to 
-different levels of hierarchy.  Typically, many of the signals can 
-logically be grouped together.  Grouping the signals into an 
-*interface* simplifies the code, improves efficiency, and reduces 
-errors.
 
-An *interface* is a collection of signals (:class:`Signal`)  embedded 
-in an class/object as attributes.  This provides a natural method 
-to group related signals and provides intuitive access through 
-attributes.  Multiple level of objects and attributes provides a 
-hierarchy of signal structure if desired.
+Complex designs often have many signals that are passed to different levels of
+hierarchy.  Typically, many signals logically belong together. This can be
+modelled by an *interface*: an object that has a number of :class:`Signal`
+objects as its attributes.  Grouping signals into an interface simplifies the
+code, improves efficiency, and reduces errors.
 
 The following is an example of an *interface* definition::
 
@@ -37,13 +32,10 @@ The following is an example of an *interface* definition::
 	    self.imag = Signal(intbv(0, min=min, max=max))
 
 
-Although previous versions supported *interfaces* for modeling,
-`MyHDL generator`_\s which directly referenced attributes were not 
-convertible. 
-MyHDL now supports conversion of designs which contain attribute accesses.
+Although previous versions supported interfaces for modeling, they were not 
+convertible.  MyHDL 0.9 now supports conversion of designs that use interfaces.
 
-The following 
-is an example using the above ``Complex`` interface definition::
+The following is an example using the above ``Complex`` interface definition::
 
     a,b = Complex(-8,8), Complex(-8,8)
     c = Complex(-128,128)
@@ -60,32 +52,18 @@ is an example using the above ``Complex`` interface definition::
 
 Solution
 --------
-The proposed solution is to create unique names for attributes which 
-are used by `MyHDL generator`_\s.  The converter will create a unique 
-name by using the name of the parent 
-and the name of the attribute along with the name of the MyHDL module 
-instance (if required for uniqueness).  The converter will essentially 
-replace the "." with an "_" for each *interface* element.  
-
-Even though the target HDLs do not support *interfaces*, MyHDL is
-able to add high-level features that compile during conversion to the 
-target HDL (Verilog and VHDL).  
-
-
-Conversion
-----------
-
-.. add details of the conversion, what policies are used to name 
-.. extend the Signals.  Any useful information about the approach
-.. or structure in the converter used.
-
-
-Limitations
------------
-Currently, MyHDL only converts interfaces in the form of attribute accesses.
-Dictionaries are not yet supported.
 
+The proposed solution is to create unique names for attributes which are used
+by `MyHDL generator`_\s.  The converter will create a unique name by using the
+name of the parent and the name of the attribute along with the name of the
+MyHDL module instance. The converter will essentially replace the "." with an
+"_" for each interface element. In essence, interfaces are supported
+using hierarchical name expansion and name mangling. 
 
+Note that the MyHDL convertor supports interfaces, even though
+the target HDLs do not. This is another great example where the
+convertor supports a high-level feature that is not available
+in the target HDLs.
 
 See also
 --------