Re: [myhdl-list] MEP : Signal Containers

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

On 5/19/12 4:02 AM, Jan Decaluwe wrote:
> On 05/18/2012 09:57 PM, Christopher Felton wrote:
>
>> The advantage of a class method over a function ... no advantage per se.
>>     They both achieve the same thing in the similar manner.  But it gives
>> the ability to use a method versus a function if someone wanted.
>
> I think there has to be a much better reason than this to warrant
> the effort to support this in conversion. There should be some feature
> that many people find useful and that cannot reasonably done in
> a different way. Conversion is complex enough as it is!

Oh oh, I setup this enhancement up poorly here, doh.  In the context of 
describing hardware behavior using a class method (as proposed) or a 
python function, they will do the same thing.  So what is the benefit to 
justify the changes in the conversion code?

My opinion, the benefit is that it helps organize larger more complex 
designs (yes, complex can be subjective, what is complex?).  To me this 
benefit is worth the inclusion.  In the past couple years this topic has 
surfaced a couple times.  Others do intuitively want to use a class 
method instead of a function in some cases.

The changes can be diffed here (viewed), 
https://bitbucket.org/cfelton/myhdl_0.8dev_work/changeset/d61bf91023b7 .

The changes are localized in two spots.  The enhancement doesn't touch a 
lot of the conversion code.  Hopefully, minimizing additional complexity 
in the conversion code.

Is the concern that it will add unneeded complexity to the conversion 
code or be confusing for users?

>
>> We have had this conversation a couple times in the past.  The current
>> solution is to have a method that returns the generators from the
>> function, essentially wrapping a function in a /class method/.  By
>> allowing the /class method/ to be directly convertible would remove the
>> need to wrap a function.
>
> I don't remember - can you provide simple examples? Is the issue only
> related to the very top level, as I MEP 108  seems to suggest, or also
> to intermediate hierarchical levels?

Best of my knowledge this is only an issue when the top-level is a class 
method.  It appears class methods can be buried in the hierarchy but not 
the top-level.  Which I think it self is a valid reason to add the 
feature, for completeness.

As for an example ... simple example.  I assume you mean an example that 
would demonstrate the benefits of using a class method?  I have 
struggled with this.  An example that can be easily digested is usually 
an example that is best suited for a non-class method implementation. 
But an example where a class method might be used is usually too 
complicated to be of benefit in conversation.  The example I will try to 
provide will be missing all the "interesting" stuff.

If I wanted to create a CRC module.  I might want to use a class to 
abstract the different functions and HDL that might be used with the CRC 
module.

     class CRC(object):
         def __init__(self, GeneratorPoly=[], BusWidth=8):
             ... # bunch of stuff to check/massage
                 # the generator polynomial

         def GetHammingDistance(self):
             ...
             return <hamming distance>

         def CrcHdl(self, <ports>):
             """Generate the hardware"""
	    return <list of generators>

In this example, this IP will have various data and methods used to 
create the generator polynomial, other house keeping, and then a method 
that describes the hardware behavior.  Most of the functions are for the 
user of the component and used during elaboration.

If the /CrcHdl/ is the top-level, currently you would need to do the 
following work around.

        def CrcHdl(self, clk, rst, data_in, data_out):
            return CrcFuncHdl(clk, rst, data_in, data_out)

>
>> MEP-108 is simple, its only intention is to enable a /class method/ the
>> same as a function.  My best example of why you might want to do this is
>> the following example, http://bit.ly/w95kOd.
>>
>> The /class method/ conversion and the /class attribute/ can be viewed as
>> separate.  They can be used together but nothing says they have to be
>> and the reason for the separate MEPs.  The idea of the /class
>> attribute/, when it is a Signal (a.k.a  Signal container), basically
>> helps manage namespace and organize collection of Signals.  The MEP-107
>> for the attributes simply proposes to create a unique name for /class
>> attribute/ when it is a Signal.
>>
>> If the example in the previous post (the wishbone) didn't illustrate how
>> /class attributes/ could be used, either I am poorly explaining or we
>> might have a misunderstanding what a /class attribute/ is.  I guess, I
>> would refer you back to the internal bus examples I and Oscar provided.
> /114/50122263/
>
> I'm confused about terminology. When you talk about class attributes,
> are you sure you don't mean instance attributes instead?
>

That might be correct indeed.  At this point I did not have an 
definition that would differentiate a class attribute vs. an instance 
attribute (reviewing [1] some more ... ).

In the current proposal and threads I would have been using /class 
attribute/ to refer to class attributes and instance attributes.  And 
the examples have been instances attributes, so I see why there might be 
confusion, I will update the MEP to clarify.  I guess in future 
conversations I should simply use *attributes* and not specify class or 
instance unless applicable.


[1] http://docs.python.org/tutorial/classes.html


Regards,
Chris Felton