[myhdl-list] MEP - keep hierarchy in conversion

[Oscar D. D. <osc...@gm...>]

Hi

Sorry to keep you waiting :) . This is my MEP draft, I'll wait for your
comments before pushing to wiki

----

Introduction

MyHDL structural descriptions support an arbitrary complex hierarchy
for code conversion. As described in the FAQ, hierarchy is flattened
because conversion is based on an elaborated design.

However, there are some situations which is desirable to have an
equivalent structural description in the generated code. Usually, this
structural description consists of a top module that instantiates
several components previously defined.

One particular use case is floorplanning in FPGA, in which each
component in a structural description is allocated to fixed resources. 

As thoroughly discussed in the mail list, hierarchy conversion could
be useful in cases which a structural description is needed for
synthesis and post-synthesis processes.

Analysis

Structural descriptions in MyHDL are based on functions that returns a
list of generators. Those functions can be mapped to component
definitions, and function calls to component instantiations.

Looking at the returned value from a structural description,
information about hierarchy is keep as a list-of-lists of generators,
and flattened later for simulation and conversion.

Proposed solution

Hierarchical conversion can be supported by recursive calling to
converter function for each function present in the top-level
description. 

Attribute "maxdepth": controls the maximum depth which the
converter is recursively called.

 * 0: don't do recursive calling. This is equivalent to default
   conversion (hierarchy flattening).

 * 1:make only one recursive call. That means keep hierarchy only from
   top module. Components are converted as default hierarchy flattening
   conversion 

 * > 1: make recursive calls as deep as maxdepth value. 

 * None: Unlimited recursion depth. That means the converter will try to
   use component instantiation as possible.

File generation

Given that the converter is called recursively several times, multiple
files are generated and its contents are used for component
declaration (VHDL). Recursive calls must avoid file replication (for
VHDL case means avoid multiple package file generation). This is done
by keeping generated code in memory before pushing to files. 

Attribute "no_component_files" : 
 * False : all components code is saved to disk as soon as possible.
 * True : discard components code, only save top-module file.

Limitations

* Component conversion

All instantiated components must be top-module convertible. That means
its ports should be well-defined (for instance, don't read output only
ports), otherwise component declaration could use incorrect or
unexpected attributes (port direction, bit widths, etc.)

* Component parameters

Since converter doesn't support parameters at top-module level,
conversion has to "hard-code" them into several component declarations.
Each time converter detect different parameters (and also different bit
widths in signals), it generates a numbered component declaration for
each different parameter value.

-----

I also want to put a related issue to discuss: I need to keep generated
files in memory for this to work, but also I used this feature to write
files later for my design flow. Did anyone find itself in need to keep
the generated files in memory? If that's the case, I propose another
attribute to keep file contents in memory (by the way, I'm using
StringIO objects in a dict with filenames as keys). 

Best regards,

-- 
Oscar Díaz
Key Fingerprint = 904B 306C C3C2 7487 650B  BFAC EDA2 B702 90E9 9964
gpg --keyserver subkeys.pgp.net --recv-keys 90E99964

I recommend using OpenDocument Format
for daily use and exchange of documents.

http://www.fsf.org/campaigns/opendocument