MEP 108: Conversion of Top-Level Methods  

Introduction

This MEP is intended to add support for top-level methods in conversion. Using classes/objects to organize digital hardware can be a natural and a useful development approach for complex and modular IP.

In the latest release version, 0.7, top-level methods are not convertible because the object reference (self) is treated as a port. For top-level methods to be convertible the object reference (self) needs to be ignored.

Example (existing function conversion)

MyHDL converts MyHDL functions, which represent a hardware module, to Verilog and VHDL. For a function to be convertible it needs ports and to return a MyHDL generator(s). The converter code identifies the arguments of Signal type and adds them to the port list.

The following is an example of a converitble function.

def adder(x, y, z):
    @always_comb
    def logic():
       z.next = x + y
    return logic

>>> toVerilog(adder, x, y, z)
>>> toVHDL(adder, x, y, z)

Proposed Enhancement

As mentioned the enhancement proposed is to add top-level method conversion support. The method to be converted has the same requirements as a function: it needs a ports and returns a generator(s).

Using the brief examples above a top-level convertible method might look like the following:

class Adder():
   def __init__(self):
      pass
   def m_adder(self, x, y, z):
      @always_comb
      def logic():
         z.next = x + y
      return logic

The above example isn't a good example why a class would be used to create, what is often consider a piece of IP, but it is sufficient as an example for method conversion.

To convert the method in the Adder object the convertible method is passed to the conversion functions.

>>> MyAddr = Adder()
>>> toVerilog(MyAddr.m_adder, x, y, z)
>>> toVHDL(MyAddr.m_adder, x, y, z)

In the above example and with the existing (0.7) conversion code the self argument in the "m_adder" method will be converted to a port in the lower-level Verilog/VHDL.

Implementation Comments

Top Function Visitor

The use of the self argument, is only an issue for the top-level method parsing. This is because the parser flattens the design and the ports are not analyzed for functions and methods lower in the hierarchy.

A top-level function or method is passed to the converter code and in the analyze module the visit_FunctionDev visitor determines the top-level ports.

_AnalyzeTopFuncVisitor.visit_FunctionDev(...)

In the above node visitor a method is identified and the first argument is skipped.

Extract Hierarchy

The extract hierarchy is modified to identify the methods that describe hardware and determine if conversion function/method attributes are present. The extractor checks for an argument named self and retrieves the function from self. If a function is bound to self the extractor will use it in the extract hierarchy.