From 44635e71327da9bbaa2a427c6e68924f4268ef37 Mon Sep 17 00:00:00 2001 From: Jan Decaluwe Date: Wed, 8 Jul 2015 09:30:44 +0200 Subject: [PATCH] Streamlined interface documentation --- doc/source/manual/conversion.rst | 27 +++++++-------- doc/source/whatsnew/0.9.rst | 58 ++++++++++---------------------- 2 files changed, 30 insertions(+), 55 deletions(-) diff --git a/doc/source/manual/conversion.rst b/doc/source/manual/conversion.rst index 0e643008..3d1df941 100644 --- a/doc/source/manual/conversion.rst +++ b/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: diff --git a/doc/source/whatsnew/0.9.rst b/doc/source/whatsnew/0.9.rst index d035153c..5655b578 100644 --- a/doc/source/whatsnew/0.9.rst +++ b/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 --------