Provided by: myhdl-doc_0.11-1_all 
NAME
myhdl - MyHDL Documentation Back to the main site »
THE MYHDL MANUAL
Overview
The goal of the MyHDL project is to empower hardware designers with the elegance and
simplicity of the Python language.
MyHDL is a free, open-source package for using Python as a hardware description and
verification language. Python is a very high level language, and hardware designers can
use its full power to model and simulate their designs. Moreover, MyHDL can convert a
design to Verilog or VHDL. This provides a path into a traditional design flow.
Modeling
Python's power and clarity make MyHDL an ideal solution for high level modeling. Python
is famous for enabling elegant solutions to complex modeling problems. Moreover, Python
is outstanding for rapid application development and experimentation.
The key idea behind MyHDL is the use of Python generators to model hardware concurrency.
Generators are best described as resumable functions. MyHDL generators are similar to
always blocks in Verilog and processes in VHDL.
A hardware module (called a block in MyHDL terminology) is modeled as a function that
returns generators. This approach makes it straightforward to support features such as
arbitrary hierarchy, named port association, arrays of instances, and conditional
instantiation. Furthermore, MyHDL provides classes that implement traditional hardware
description concepts. It provides a signal class to support communication between
generators, a class to support bit oriented operations, and a class for enumeration types.
Simulation and Verification
The built-in simulator runs on top of the Python interpreter. It supports waveform viewing
by tracing signal changes in a VCD file.
With MyHDL, the Python unit test framework can be used on hardware designs. Although unit
testing is a popular modern software verification technique, it is still uncommon in the
hardware design world.
MyHDL can also be used as hardware verification language for Verilog designs, by
co-simulation with traditional HDL simulators.
Conversion to Verilog and VHDL
Subject to some limitations, MyHDL designs can be converted to Verilog or VHDL. This
provides a path into a traditional design flow, including synthesis and implementation.
The convertible subset is restricted, but much wider than the standard synthesis subset.
It includes features that can be used for high level modeling and test benches.
The converter works on an instantiated design that has been fully elaborated.
Consequently, the original design structure can be arbitrarily complex. Moreover, the
conversion limitations apply only to code inside generators. Outside generators, Python's
full power can be used without compromising convertibility.
Finally, the converter automates a number of tasks that are hard in Verilog or VHDL
directly. A notable feature is the automated handling of signed arithmetic issues.
Background information
Prerequisites
You need a basic understanding of Python to use MyHDL. If you don't know Python, don't
worry: it is is one of the easiest programming languages to learn [1]. Learning Python
is one of the best time investments that engineering professionals can make [2].
For starters, http://docs.python.org/tutorial is probably the best choice for an on-line
tutorial. For alternatives, see http://wiki.python.org/moin/BeginnersGuide.
A working knowledge of a hardware description language such as Verilog or VHDL is helpful.
Code examples in this manual are sometimes shortened for clarity. Complete executable
examples can be found in the distribution directory at example/manual/.
A small tutorial on generators
Generators were introduced in Python 2.2. Because generators are the key concept in MyHDL,
a small tutorial is included here.
Consider the following nonsensical function:
def function():
for i in range(5):
return i
You can see why it doesn't make a lot of sense. As soon as the first loop iteration is
entered, the function returns:
>>> function()
0
Returning is fatal for the function call. Further loop iterations never get a chance, and
nothing is left over from the function call when it returns.
To change the function into a generator function, we replace return with yield:
def generator():
for i in range(5):
yield i
Now we get:
>>> generator()
<generator object at 0x815d5a8>
When a generator function is called, it returns a generator object. A generator object
supports the iterator protocol, which is an expensive way of saying that you can let it
generate subsequent values by calling its next method:
>>> g = generator()
>>> g.next()
0
>>> g.next()
1
>>> g.next()
2
>>> g.next()
3
>>> g.next()
4
>>> g.next()
Traceback (most recent call last):
File "<stdin>", line 1, in ?
StopIteration
Now we can generate the subsequent values from the for loop on demand, until they are
exhausted. What happens is that the yield statement is like a return, except that it is
non-fatal: the generator remembers its state and the point in the code when it yielded. A
higher order agent can decide when to get the next value by calling the generator's next
method. We say that generators are resumable functions.
If you are familiar with hardware description languages, this may ring a bell. In
hardware simulations, there is also a higher order agent, the Simulator, that interacts
with such resumable functions; they are called processes in VHDL and always blocks in
Verilog. Similarly, Python generators provide an elegant and efficient method to model
concurrency, without having to resort to some form of threading.
The use of generators to model concurrency is the first key concept in MyHDL. The second
key concept is a related one: in MyHDL, the yielded values are used to specify the
conditions on which the generator should wait before resuming. In other words, yield
statements work as general sensitivity lists.
About decorators
Python 2.4 introduced a feature called decorators. MyHDL takes advantage of this feature
by defining a number of decorators that facilitate hardware descriptions. However, some
users may not yet be familiar with decorators. Therefore, an introduction is included
here.
A decorator consists of special syntax in front of a function declaration. It refers to a
decorator function. The decorator function automatically transforms the declared function
into some other callable object.
A decorator function deco is used in a decorator statement as follows:
@deco
def func(arg1, arg2, ...):
<body>
This code is equivalent to the following:
def func(arg1, arg2, ...):
<body>
func = deco(func)
Note that the decorator statement goes directly in front of the function declaration, and
that the function name func is automatically reused for the final result.
MyHDL uses decorators to create ready-to-simulate generators from local function
definitions. Their functionality and usage will be described extensively in this manual.
FOOTNOTES
[1] You must be bored by such claims, but in Python's case it's true.
[2] I am not biased.
Introduction to MyHDL
A basic MyHDL simulation
We will introduce MyHDL with a classic Hello World style example. All example code can be
found in the distribution directory under example/manual/. Here are the contents of a
MyHDL simulation script called hello1.py:
When we run this simulation, we get the following output:
The first line of the script imports a number of objects from the myhdl package. In Python
we can only use identifiers that are literally defined in the source file.
Then, we define a function called HelloWorld. In MyHDL, a hardware module is modeled by a
function decorated with the block decorator. The name block was chosen to avoid confusion
with the Python concept of a module. We will use this terminology further on.
The parameter list of the HelloWorld function is used to define the interface of the
hardware block. In this first example, the interface is empty.
Inside the top level function we declare a local function called say_hello that defines
the desired behavior. This function is decorated with an always decorator that has a delay
object as its parameter. The meaning is that the function will be executed whenever the
specified delay interval has expired.
Behind the curtains, the always decorator creates a Python generator and reuses the name
of the decorated function for it. Generators are the fundamental objects in MyHDL, and we
will say much more about them further on.
Finally, the top level function returns the say_hello generator. This is the simplest case
of the basic MyHDL code pattern to define the contents of a hardware block. We will
describe the general case further on.
In MyHDL, we create an instance of a hardware block by calling the corresponding function.
The block decorator make sure that the return value is actually an instance of a block
class, with a useful API. In the example, variable inst refers to a HelloWorld block
instance.
To simulate the instance, we use its run_sim method. We can use it to run the simulation
for the desired amount of timesteps.
Signals and concurrency
An actual hardware design is typically massively concurrent, which means that a large
amount of functional units are running in parallel. MyHDL supports this behavior by
allowing an arbitrary number of concurrently running generators.
With concurrency comes the problem of deterministic communication. Hardware languages use
special objects to support deterministic communication between concurrent code. In
particular, MyHDL has a Signal object which is roughly modeled after VHDL signals.
We will demonstrate signals and concurrency by extending and modifying our first example.
We define a hardware block that contains two generators, one that drives a clock signal,
and one that is sensitive to a positive edge on a clock signal:
The clock driver function clk_driver drives the clock signal. If defines a generator that
continuously toggles a clock signal after a certain delay. A new value of a signal is
specified by assigning to its next attribute. This is the MyHDL equivalent of the VHDL
signal assignment and the Verilog non-blocking assignment.
The say_hello function is modified from the first example. It is made sensitive to a
rising edge of the clock signal, specified by the posedge attribute of a signal. The edge
specifier is the argument of the always decorator. As a result, the decorated function
will be executed on every rising clock edge.
The clk signal is constructed with an initial value 0. One generator drives it, the other
is sensitive to it. The result of this communication is that the generators run in
parallel, but that their actions are coordinated by the clock signal.
When we run the simulation, we get:
Parameters, ports and hierarchy
We have seen that MyHDL uses functions to model hardware blocks. So far these functions
did not have parameters. However, to create general, reusable blocks we will need
parameters. For example, we can create a clock driver block as follows:
The block encapsulates a clock driver generator. It has two parameters.
The first parameter is clk is the clock signal. A asignal parameter is MyHDL's way to
model a dfn:port:. The second parameter is the clock period, with a default value of 20.
As the low time of the clock may differ from the high time in case of an odd period, we
cannot use the always decorator with a single delay value anymore. Instead, the drive_clk
function is now a generator function with an explicit definition of the desired behavior.
It is decorated with the instance decorator. You can see that drive_clk is a generator
function because it contains yield statements.
When a generator function is called, it returns a generator object. This is basically what
the instance decorator does. It is less sophisticated than the always decorator, but it
can be used to create a generator from any local generator function.
The yield statement is a general Python construct, but MyHDL uses it in a specific way.
It has a similar meaning as the wait statement in VHDL: the statement suspends execution
of a generator, and its clauses specify the conditions on which the generator should wait
before resuming. In this case, the generator waits for a certain delay.
Note that to make sure that the generator runs "forever", we wrap its behavior in a while
True loop.
Similarly, we can define a general Hello function as follows:
We can create any number of instances by calling the functions with the appropriate
parameters. Hierarchy can be modeled by defining the instances in a higher-level function,
and returning them. This pattern can be repeated for an arbitrary number of hierarchical
levels. Consequently, the general definition of a MyHDL instance is recursive: an instance
is either a sequence of instances, or a generator.
As an example, we will create a higher-level function with four instances of the
lower-level functions, and simulate it:
As in standard Python, positional or named parameter association can be used in
instantiations, or a mix of both [1]. All these styles are demonstrated in the example
above. Named association can be very useful if there are a lot of parameters, as the
argument order in the call does not matter in that case.
The simulation produces the following output:
Terminology review
Some commonly used terminology has different meanings in Python versus hardware design.
For a good understanding, it is important to make these differences explicit.
A module in Python refers to all source code in a particular file. A module can be reused
by other modules by importing it. In hardware design on the other hand, a module typically
refers to a reusable unit of hardware with a well defined interface. Because these
meanings are so different, the terminology chosen for a hardware module in MyHDL is block
instead, as explained earlier in this chapter.
A hardware block can can be reused in another block by instantiating it.
An instance in Python (and other object-oriented languages) refers to the object created
by a class constructor. In hardware design, an instance is a particular incarnation of a
hardware block, created by instantiating the block. In MyHDL, such as block instance is
actually an instance of a particular class. Therefore, the two meanings are not exactly
the same, but they coincide nicely.
Normally, the meaning the words "block" and "instance" should be clear from the context.
Sometimes, we qualify them with the words "hardware" or "MyHDL" for clarity.
Some remarks on MyHDL and Python
To conclude this introductory chapter, it is useful to stress that MyHDL is not a language
in itself. The underlying language is Python, and MyHDL is implemented as a Python
package called myhdl. Moreover, it is a design goal to keep the myhdl package as
minimalistic as possible, so that MyHDL descriptions are very much "pure Python".
To have Python as the underlying language is significant in several ways:
• Python is a very powerful high level language. This translates into high productivity
and elegant solutions to complex problems.
• Python is continuously improved by some very clever minds, supported by a large user
base. Python profits fully from the open source development model.
• Python comes with an extensive standard library. Some functionality is likely to be of
direct interest to MyHDL users: examples include string handling, regular expressions,
random number generation, unit test support, operating system interfacing and GUI
development. In addition, there are modules for mathematics, database connections,
networking programming, internet data handling, and so on.
Summary and perspective
Here is an overview of what we have learned in this chapter:
• Generators are the basic building blocks of MyHDL models. They provide the way to model
massive concurrency and sensitivity lists.
• MyHDL provides decorators that create useful generators from local functions and a
decorator to create hardware blocks.
• Hardware structure and hierarchy is described with Python functions, decorated with the
block decorator.
• Signal objects are used to communicate between concurrent generators.
• A block instance provides a method to simulate it.
These concepts are sufficient to start modeling and simulating with MyHDL.
However, there is much more to MyHDL. Here is an overview of what can be learned from the
following chapters:
• MyHDL supports hardware-oriented types that make it easier to write typical hardware
models. These are described in Chapter hwtypes.
• MyHDL supports sophisticated and high level modeling techniques. This is described in
Chapter model-hl.
• MyHDL enables the use of modern software verification techniques, such as unit testing,
on hardware designs. This is the topic of Chapter unittest.
• It is possible to co-simulate MyHDL models with other HDL languages such as Verilog and
VHDL. This is described in Chapter cosim.
• Last but not least, MyHDL models can be converted to Verilog or VHDL, providing a path
to a silicon implementation. This is the topic of Chapter conv.
FOOTNOTES
[1] All positional parameters have to go before any named parameter.
Hardware-oriented types
The intbv class
Hardware design involves dealing with bits and bit-oriented operations. The standard
Python type int has most of the desired features, but lacks support for indexing and
slicing. For this reason, MyHDL provides the intbv class. The name was chosen to suggest
an integer with bit vector flavor.
intbv works transparently with other integer-like types. Like class int, it provides
access to the underlying two's complement representation for bitwise operations. However,
unlike int, it is a mutable type. This means that its value can be changed after object
creation, through methods and operators such as slice assignment.
intbv supports the same operators as int for arithmetic. In addition, it provides a number
of features to make it suitable for hardware design. First, the range of allowed values
can be constrained. This makes it possible to check the value at run time during
simulation. Moreover, back end tools can determine the smallest possible bit width for
representing the object. Secondly, it supports bit level operations by providing an
indexing and slicing interface.
intbv objects are constructed in general as follows:
intbv([val=None] [, min=None] [, max=None])
val is the initial value. min and max can be used to constrain the value. Following the
Python conventions, min is inclusive, and max is exclusive. Therefore, the allowed value
range is min .. max-1.
Let's look at some examples. An unconstrained intbv object is created as follows:
>>> a = intbv(24)
After object creation, min and max are available as attributes for inspection. Also, the
standard Python function len can be used to determine the bit width. If we inspect the
previously created object, we get:
>>> a
intbv(24)
>>> print(a.min)
None
>>> print(a.max)
None
>>> len(a)
0
As the instantiation was unconstrained, the min and max attributes are undefined.
Likewise, the bit width is undefined, which is indicated by a return value 0.
A constrained intbv object is created as follows:
>>> a = intbv(24, min=0, max=25)
Inspecting the object now gives:
>>> a
intbv(24)
>>> a.min
0
>>> a.max
25
>>> len(a)
5
We see that the allowed value range is 0 .. 24, and that 5 bits are required to represent
the object.
The min and max bound attributes enable fine-grained control and error checking of the
value range. In particular, the bound values do not have to be symmetric or powers of 2.
In all cases, the bit width is set appropriately to represent the values in the range. For
example:
>>> a = intbv(6, min=0, max=7)
>>> len(a)
3
>>> a = intbv(6, min=-3, max=7)
>>> len(a)
4
>>> a = intbv(6, min=-13, max=7)
>>> len(a)
5
Bit indexing
A common requirement in hardware design is access to the individual bits. The intbv class
implements an indexing interface that provides access to the bits of the underlying two's
complement representation. The following illustrates bit index read access:
>>> from myhdl import bin
>>> a = intbv(24)
>>> bin(a)
'11000'
>>> int(a[0])
0
>>> int(a[3])
1
>>> b = intbv(-23)
>>> bin(b)
'101001'
>>> int(b[0])
1
>>> int(b[3])
1
>>> int(b[4])
0
We use the bin function provide by MyHDL because it shows the two's complement
representation for negative values, unlike Python's builtin with the same name. Note that
lower indices correspond to less significant bits. The following code illustrates bit
index assignment:
>>> bin(a)
'11000'
>>> a[3] = 0
>>> bin(a)
'10000'
>>> a
intbv(16)
>>> b
intbv(-23)
>>> bin(b)
'101001'
>>> b[3] = 0
>>> bin(b)
'100001'
>>> b
intbv(-31)
Bit slicing
The intbv type also supports bit slicing, for both read access assignment. For example:
>>> a = intbv(24)
>>> bin(a)
'11000'
>>> a[4:1]
intbv(4)
>>> bin(a[4:1])
'100'
>>> a[4:1] = 0b001
>>> bin(a)
'10010'
>>> a
intbv(18)
In accordance with the most common hardware convention, and unlike standard Python,
slicing ranges are downward. As in standard Python, the slicing range is half-open: the
highest index bit is not included. Unlike standard Python however, this index corresponds
to the leftmost item.
Both indices can be omitted from the slice. If the rightmost index is omitted, it is 0 by
default. If the leftmost index is omitted, the meaning is to access "all" higher order
bits. For example:
>>> bin(a)
'11000'
>>> bin(a[4:])
'1000'
>>> a[4:] = '0001'
>>> bin(a)
'10001'
>>> a[:] = 0b10101
>>> bin(a)
'10101'
The half-openness of a slice may seem awkward at first, but it helps to avoid one-off
count issues in practice. For example, the slice a[8:] has exactly 8 bits. Likewise, the
slice a[7:2] has 7-2=5 bits. You can think about it as follows: for a slice [i:j], only
bits below index i are included, and the bit with index j is the last bit included.
When an intbv object is sliced, a new intbv object is returned. This new intbv object is
always positive, and the value bounds are set up in accordance with the bit width
specified by the slice. For example:
>>> a = intbv(6, min=-3, max=7)
>>> len(a)
4
>>> b = a[4:]
>>> b
intbv(6L)
>>> len(b)
4
>>> b.min
0
>>> b.max
16
In the example, the original object is sliced with a slice equal to its bit width. The
returned object has the same value and bit width, but its value range consists of all
positive values that can be represented by the bit width.
The object returned by a slice is positive, even when the original object is negative:
>>> a = intbv(-3)
>>> bin(a, width=5)
'11101'
>>> b = a[5:]
>>> b
intbv(29L)
>>> bin(b)
'11101'
In this example, the bit pattern of the two objects is identical within the bit width, but
their values have opposite sign.
Sometimes hardware engineers prefer to constrain an object by defining its bit width
directly, instead of the range of allowed values. Using the slicing properties of the
intbv class one can do that as follows:
>>> a = intbv(24)[5:]
What actually happens here is that first an unconstrained intbv is created, which is then
sliced. Slicing an intbv returns a new intbv with the constraints set up appropriately.
Inspecting the object now shows:
>>> a.min
0
>>> a.max
32
>>> len(a)
5
Note that the max attribute is 32, as with 5 bits it is possible to represent the range 0
.. 31. Creating an intbv in this way is convenient but has the disadvantage that only
positive value ranges between 0 and a power of 2 can be specified.
The modbv class
In hardware modeling, there is often a need for the elegant modeling of wrap-around
behavior. intbv instances do not support this automatically, as they assert that any
assigned value is within the bound constraints. However, wrap-around modeling can be
straightforward. For example, the wrap-around condition for a counter is often decoded
explicitly, as it is needed for other purposes. Also, the modulo operator provides an
elegant one-liner in many scenarios:
count.next = (count + 1) % 2**8
However, some interesting cases are not supported by the intbv type. For example, we
would like to describe a free running counter using a variable and augmented assignment as
follows:
count_var += 1
This is not possible with the intbv type, as we cannot add the modulo behavior to this
description. A similar problem exist for an augmented left shift as follows:
shifter <<= 4
To support these operations directly, MyHDL provides the modbv type. modbv is implemented
as a subclass of intbv. The two classes have an identical interface and work together in
a straightforward way for arithmetic operations. The only difference is how the bounds
are handled: out-of-bound values result in an error with intbv, and in wrap-around with
modbv. For example, the modulo counter above can be modeled as follows:
count = Signal(modbv(0, min=0, max=2**8))
...
count.next = count + 1
The wrap-around behavior is defined in general as follows:
val = (val - min) % (max - min) + min
In a typical case when min==0, this reduces to:
val = val % max
Unsigned and signed representation
intbv is designed to be as high level as possible. The underlying value of an intbv object
is a Python int, which is represented as a two's complement number with "indefinite" bit
width. The range bounds are only used for error checking, and to calculate the minimum
required bit width for representation. As a result, arithmetic can be performed like with
normal integers.
In contrast, HDLs such as Verilog and VHDL typically require designers to deal with
representational issues, especially for synthesizable code. They provide low-level types
like signed and unsigned for arithmetic. The rules for arithmetic with such types are much
more complicated than with plain integers.
In some cases it can be useful to interpret intbv objects in terms of "signed" and
"unsigned". Basically, it depends on attribute min. if min < 0, then the object is
"signed", otherwise it is "unsigned". In particular, the bit width of a "signed" object
will account for a sign bit, but that of an "unsigned" will not, because that would be
redundant. From earlier sections, we have learned that the return value from a slicing
operation is always "unsigned".
In some applications, it is desirable to convert an "unsigned" intbv to a "signed", in
other words, to interpret the msb bit as a sign bit. The msb bit is the highest order bit
within the object's bit width. For this purpose, intbv provides the intbv.signed method.
For example:
>>> a = intbv(12, min=0, max=16)
>>> bin(a)
'1100'
>>> b = a.signed()
>>> b
-4
>>> bin(b, width=4)
'1100'
intbv.signed extends the msb bit into the higher-order bits of the underlying object
value, and returns the result as an integer. Naturally, for a "signed" the return value
will always be identical to the original value, as it has the sign bit already.
As an example let's take a 8 bit wide data bus that would be modeled as follows:
data_bus = intbv(0)[8:]
Now consider that a complex number is transferred over this data bus. The upper 4 bits of
the data bus are used for the real value and the lower 4 bits for the imaginary value. As
real and imaginary values have a positive and negative value range, we can slice them off
from the data bus and convert them as follows:
real.next = data_bus[8:4].signed()
imag.next = data_bus[4:].signed()
Structural modeling
Introduction
Hardware descriptions need to support the concepts of module instantiation and hierarchy.
In MyHDL, an instance is recursively defined as being either a sequence of instances, or a
generator. Hierarchy is modeled by defining instances in a higher-level function, and
returning them. The following is a schematic example of the basic case.
from myhdl import block
@block
def top(...):
...
instance_1 = module_1(...)
instance_2 = module_2(...)
...
instance_n = module_n(...)
...
return instance_1, instance_2, ... , instance_n
Note that MyHDL uses conventional procedural techniques for modeling structure. This
makes it straightforward to model more complex cases.
Conditional instantiation
To model conditional instantiation, we can select the returned instance under parameter
control. For example:
from myhdl import block
SLOW, MEDIUM, FAST = range(3)
@block
def top(..., speed=SLOW):
...
def slowAndSmall():
...
...
def fastAndLarge():
...
if speed == SLOW:
return slowAndSmall()
elif speed == FAST:
return fastAndLarge()
else:
raise NotImplementedError
Lists of instances and signals
Python lists are easy to create. We can use them to model lists of instances.
Suppose we have a top module that instantiates a single channel submodule, as follows:
from myhdl import block, Signal
@block
def top(...):
din = Signal(0)
dout = Signal(0)
clk = Signal(bool(0))
reset = Signal(bool(0))
channel_inst = channel(dout, din, clk, reset)
return channel_inst
If we wanted to support an arbitrary number of channels, we can use lists of signals and a
list of instances, as follows:
from myhdl import block, Signal
@block
def top(..., n=8):
din = [Signal(0) for i in range(n)]
dout = [Signal(0) for in range(n)]
clk = Signal(bool(0))
reset = Signal(bool(0))
channel_inst = [None for i in range(n)]
for i in range(n):
channel_inst[i] = channel(dout[i], din[i], clk, reset)
return channel_inst
Converting between lists of signals and bit vectors
Compared to HDLs such as VHDL and Verilog, MyHDL signals are less flexible for structural
modeling. For example, slicing a signal returns a slice of the current value. For
behavioral code, this is just fine. However, it implies that you cannot use such as slice
in structural descriptions. In other words, a signal slice cannot be used as a signal.
In MyHDL, you can address such cases by a concept called shadow signals. A shadow signal
is constructed out of other signals and follows their value changes automatically. For
example, a _SliceSignal follows the value of an index or a slice from another signal.
Likewise, A ConcatSignal follows the values of a number of signals as a concatenation.
As an example, suppose we have a system with N requesters that need arbitration. Each
requester has a request output and a grant input. To connect them in the system, we can
use list of signals. For example, a list of request signals can be constructed as follows:
request_list = [Signal(bool()) for i in range(M)]
Suppose that an arbiter module is available that is instantiated as follows:
arb = arbiter(grant_vector, request_vector, clock, reset)
The request_vector input is a bit vector that can have any of its bits asserted. The
grant_vector is an output bit vector with just a single bit asserted, or none. Such a
module is typically based on bit vectors because they are easy to process in RTL code. In
MyHDL, a bit vector is modeled using the intbv type.
We need a way to "connect" the list of signals to the bit vector and vice versa. Of
course, we can do this with explicit code, but shadow signals can do this automatically.
For example, we can construct a request_vector as a ConcatSignal object:
request_vector = ConcatSignal(*reversed(request_list)
Note that we reverse the list first. This is done because the index range of lists is the
inverse of the range of intbv bit vectors. By reversing, the indices correspond to the
same bit.
The inverse problem exist for the grant_vector. It would be defined as follows:
grant_vector = Signal(intbv(0)[M:])
To construct a list of signals that are connected automatically to the bit vector, we can
use the Signal call interface to construct _SliceSignal objects:
grant_list = [grant_vector(i) for i in range(M)]
Note the round brackets used for this type of slicing. Also, it may not be necessary to
construct this list explicitly. You can simply use grant_vector(i) in an instantiation.
To decide when to use normal or shadow signals, consider the data flow. Use normal signals
to connect to outputs. Use shadow signals to transform these signals so that they can be
used as inputs.
Inferring the list of instances
In MyHDL, instances have to be returned explicitly by a top level function. It may be
convenient to assemble the list of instances automatically. For this purpose, MyHDL
provides the function instances. Using the first example in this section, it is used as
follows:
from myhdl import block, instances
@block
def top(...):
...
instance_1 = module_1(...)
instance_2 = module_2(...)
...
instance_n = module_n(...)
...
return instances()
Function instances uses introspection to inspect the type of the local variables defined
by the calling function. All variables that comply with the definition of an instance are
assembled in a list, and that list is returned.
RTL modeling
Introduction
RTL (Register Transfer Level) is a modeling abstraction level that is typically used to
write synthesizable models. Synthesis refers to the process by which an HDL description
is automatically compiled into an implementation for an ASIC or FPGA. This chapter
describes how MyHDL supports it.
Combinatorial logic
Template
Combinatorial logic is described with a code pattern as follows:
from myhdl import block, always_comb
@block
def top(<parameters>):
...
@always_comb
def comb_logic():
<functional code>
...
return comb_logic, ...
The always_comb decorator describes combinatorial logic. The name refers to a similar
construct in SystemVerilog. The decorated function is a local function that specifies what
happens when one of the input signals of the logic changes. The always_comb decorator
infers the input signals automatically. It returns a generator that is sensitive to all
inputs, and that executes the function whenever an input changes.
Example
The following is an example of a combinatorial multiplexer
To verify it, we will simulate the logic with some random patterns. The random module in
Python's standard library comes in handy for such purposes. The function randrange(n)
returns a random natural integer smaller than n. It is used in the test bench code to
produce random input values.
It is often useful to keep the random values reproducible. This can be accomplished by
providing a seed value as in the code. The run produces the following output:
Sequential logic
Template
Sequential RTL models are sensitive to a clock edge. In addition, they may be sensitive to
a reset signal. The always_seq decorator supports this model directly:
from myhdl import block, always_seq
@block
def top(<parameters>, clock, ..., reset, ...):
...
@always_seq(clock.posedge, reset=reset)
def seq_logic():
<functional code>
...
return seq_logic, ...
The always_seq decorator automatically infers the reset functionality. It detects which
signals need to be reset, and uses their initial values as the reset values. The reset
signal itself needs to be specified as a ResetSignal object. For example:
reset = ResetSignal(0, active=0, isasync=True)
The first parameter specifies the initial value. The active parameter specifies the value
on which the reset is active, and the isasync parameter specifies whether it is an
asychronous (True) or a synchronous (False) reset. If no reset is needed, you can assign
None to the reset parameter in the always_seq parameter.
Example
The following code is a description of an incrementer with enable, and an asynchronous
reset.
For the test bench, we will use an independent clock generator, stimulus generator, and
monitor. After applying enough stimulus patterns, we can raise the StopSimulation
exception to stop the simulation run. The test bench for a small incrementer and a small
number of patterns is a follows
The simulation produces the following output
Alternative template
The template with the always_seq decorator is convenient as it infers the reset
functionality automatically. Alternatively, you can use a more explicit template as
follows:
from myhdl import block, always
@block
def top(<parameters>, clock, ..., reset, ...):
...
@always(clock.posedge, reset.negedge)
def seq_logic():
if not reset:
<reset code>
else:
<functional code>
return seq_logic,...
With this template, the reset values have to be specified explicitly.
Finite State Machine modeling
Finite State Machine (FSM) modeling is very common in RTL design and therefore deserves
special attention.
For code clarity, the state values are typically represented by a set of identifiers. A
standard Python idiom for this purpose is to assign a range of integers to a tuple of
identifiers, like so
>>> SEARCH, CONFIRM, SYNC = range(3)
>>> CONFIRM
1
However, this technique has some drawbacks. Though it is clearly the intention that the
identifiers belong together, this information is lost as soon as they are defined. Also,
the identifiers evaluate to integers, whereas a string representation of the identifiers
would be preferable. To solve these issues, we need an enumeration type.
MyHDL supports enumeration types by providing a function enum. The arguments to enum are
the string representations of the identifiers, and its return value is an enumeration
type. The identifiers are available as attributes of the type. For example
>>> from myhdl import enum
>>> t_State = enum('SEARCH', 'CONFIRM', 'SYNC')
>>> t_State
<Enum: SEARCH, CONFIRM, SYNC>
>>> t_State.CONFIRM
CONFIRM
We can use this type to construct a state signal as follows:
state = Signal(t_State.SEARCH)
As an example, we will use a framing controller FSM. It is an imaginary example, but
similar control structures are often found in telecommunication applications. Suppose that
we need to find the Start Of Frame (SOF) position of an incoming frame of bytes. A sync
pattern detector continuously looks for a framing pattern and indicates it to the FSM with
a syncFlag signal. When found, the FSM moves from the initial SEARCH state to the CONFIRM
state. When the syncFlag is confirmed on the expected position, the FSM declares SYNC,
otherwise it falls back to the SEARCH state. This FSM can be coded as follows
At this point, we will use the example to demonstrate the MyHDL support for waveform
viewing. During simulation, signal changes can be written to a VCD output file. The VCD
file can then be loaded and viewed in a waveform viewer tool such as gtkwave.
The user interface of this feature consists of a single function, traceSignals. To
explain how it works, recall that in MyHDL, an instance is created by assigning the result
of a function call to an instance name. For example:
tb_fsm = testbench()
To enable VCD tracing, the instance should be created as follows instead:
tb_fsm = traceSignals(testbench)
Note that the first argument of traceSignals consists of the uncalled function. By calling
the function under its control, traceSignals gathers information about the hierarchy and
the signals to be traced. In addition to a function argument, traceSignals accepts an
arbitrary number of non-keyword and keyword arguments that will be passed to the function
call.
A small test bench for our framing controller example, with signal tracing enabled, is
shown below:
When we run the test bench, it generates a VCD file called testbench.vcd. When we load
this file into gtkwave, we can view the waveforms: [image]
Signals are dumped in a suitable format. This format is inferred at the Signal
construction time, from the type of the initial value. In particular, bool signals are
dumped as single bits. (This only works starting with Python 2.3, when bool has become a
separate type). Likewise, intbv signals with a defined bit width are dumped as bit
vectors. To support the general case, other types of signals are dumped as a string
representation, as returned by the standard str function.
WARNING:
Support for literal string representations is not part of the VCD standard. It is
specific to gtkwave. To generate a standard VCD file, you need to use signals with a
defined bit width only.
High level modeling
Introduction
To write synthesizable models in MyHDL, you should stick to the RTL templates shown in
model-rtl. However, modeling in MyHDL is much more powerful than that. Conceptually,
MyHDL is a library for general event-driven modeling and simulation of hardware systems.
There are many reasons why it can be useful to model at a higher abstraction level than
RTL. For example, you can use MyHDL to verify architectural features, such as system
throughput, latency and buffer sizes. You can also write high level models for specialized
technology-dependent cores that are not going through synthesis. Last but not least, you
can use MyHDL to write test benches that verify a system model or a synthesizable
description.
This chapter explores some of the options for high level modeling with MyHDL.
Modeling with bus-functional procedures
A bus-functional procedure is a reusable encapsulation of the low-level operations needed
to implement some abstract transaction on a physical interface. Bus-functional procedures
are typically used in flexible verification environments.
Once again, MyHDL uses generator functions to support bus-functional procedures. In
MyHDL, the difference between instances and bus-functional procedure calls comes from the
way in which a generator function is used.
As an example, we will design a bus-functional procedure of a simplified UART transmitter.
We assume 8 data bits, no parity bit, and a single stop bit, and we add print statements
to follow the simulation behavior:
T_9600 = int(1e9 / 9600)
def rs232_tx(tx, data, duration=T_9600):
""" Simple rs232 transmitter procedure.
tx -- serial output data
data -- input data byte to be transmitted
duration -- transmit bit duration
"""
print "-- Transmitting %s --" % hex(data)
print "TX: start bit"
tx.next = 0
yield delay(duration)
for i in range(8):
print "TX: %s" % data[i]
tx.next = data[i]
yield delay(duration)
print "TX: stop bit"
tx.next = 1
yield delay(duration)
This looks exactly like the generator functions in previous sections. It becomes a
bus-functional procedure when we use it differently. Suppose that in a test bench, we want
to generate a number of data bytes to be transmitted. This can be modeled as follows:
testvals = (0xc5, 0x3a, 0x4b)
def stimulus():
tx = Signal(1)
for val in testvals:
txData = intbv(val)
yield rs232_tx(tx, txData)
We use the bus-functional procedure call as a clause in a yield statement. This
introduces a fourth form of the yield statement: using a generator as a clause. Although
this is a more dynamic usage than in the previous cases, the meaning is actually very
similar: at that point, the original generator should wait for the completion of a
generator. In this case, the original generator resumes when the rs232_tx(tx, txData)
generator returns.
When simulating this, we get:
-- Transmitting 0xc5 --
TX: start bit
TX: 1
TX: 0
TX: 1
TX: 0
TX: 0
TX: 0
TX: 1
TX: 1
TX: stop bit
-- Transmitting 0x3a --
TX: start bit
TX: 0
TX: 1
TX: 0
TX: 1
...
We will continue with this example by designing the corresponding UART receiver
bus-functional procedure. This will allow us to introduce further capabilities of MyHDL
and its use of the yield statement.
Until now, the yield statements had a single clause. However, they can have multiple
clauses as well. In that case, the generator resumes as soon as the wait condition
specified by one of the clauses is satisfied. This corresponds to the functionality of
sensitivity lists in Verilog and VHDL.
For example, suppose we want to design an UART receive procedure with a timeout. We can
specify the timeout condition while waiting for the start bit, as in the following
generator function:
def rs232_rx(rx, data, duration=T_9600, timeout=MAX_TIMEOUT):
""" Simple rs232 receiver procedure.
rx -- serial input data
data -- data received
duration -- receive bit duration
"""
# wait on start bit until timeout
yield rx.negedge, delay(timeout)
if rx == 1:
raise StopSimulation, "RX time out error"
# sample in the middle of the bit duration
yield delay(duration // 2)
print "RX: start bit"
for i in range(8):
yield delay(duration)
print "RX: %s" % rx
data[i] = rx
yield delay(duration)
print "RX: stop bit"
print "-- Received %s --" % hex(data)
If the timeout condition is triggered, the receive bit rx will still be 1. In that case,
we raise an exception to stop the simulation. The StopSimulation exception is predefined
in MyHDL for such purposes. In the other case, we proceed by positioning the sample point
in the middle of the bit duration, and sampling the received data bits.
When a yield statement has multiple clauses, they can be of any type that is supported as
a single clause, including generators. For example, we can verify the transmitter and
receiver generator against each other by yielding them together, as follows:
def test():
tx = Signal(1)
rx = tx
rxData = intbv(0)
for val in testvals:
txData = intbv(val)
yield rs232_rx(rx, rxData), rs232_tx(tx, txData)
Both forked generators will run concurrently, and the original generator will resume as
soon as one of them finishes (which will be the transmitter in this case). The simulation
output shows how the UART procedures run in lockstep:
-- Transmitting 0xc5 --
TX: start bit
RX: start bit
TX: 1
RX: 1
TX: 0
RX: 0
TX: 1
RX: 1
TX: 0
RX: 0
TX: 0
RX: 0
TX: 0
RX: 0
TX: 1
RX: 1
TX: 1
RX: 1
TX: stop bit
RX: stop bit
-- Received 0xc5 --
-- Transmitting 0x3a --
TX: start bit
RX: start bit
TX: 0
RX: 0
...
For completeness, we will verify the timeout behavior with a test bench that disconnects
the rx from the tx signal, and we specify a small timeout for the receive procedure:
def testTimeout():
tx = Signal(1)
rx = Signal(1)
rxData = intbv(0)
for val in testvals:
txData = intbv(val)
yield rs232_rx(rx, rxData, timeout=4*T_9600-1), rs232_tx(tx, txData)
The simulation now stops with a timeout exception after a few transmit cycles:
-- Transmitting 0xc5 --
TX: start bit
TX: 1
TX: 0
TX: 1
StopSimulation: RX time out error
Recall that the original generator resumes as soon as one of the forked generators
returns. In the previous cases, this is just fine, as the transmitter and receiver
generators run in lockstep. However, it may be desirable to resume the caller only when
all of the forked generators have finished. For example, suppose that we want to
characterize the robustness of the transmitter and receiver design to bit duration
differences. We can adapt our test bench as follows, to run the transmitter at a faster
rate:
T_10200 = int(1e9 / 10200)
def testNoJoin():
tx = Signal(1)
rx = tx
rxData = intbv(0)
for val in testvals:
txData = intbv(val)
yield rs232_rx(rx, rxData), rs232_tx(tx, txData, duration=T_10200)
Simulating this shows how the transmission of the new byte starts before the previous one
is received, potentially creating additional transmission errors:
-- Transmitting 0xc5 --
TX: start bit
RX: start bit
...
TX: 1
RX: 1
TX: 1
TX: stop bit
RX: 1
-- Transmitting 0x3a --
TX: start bit
RX: stop bit
-- Received 0xc5 --
RX: start bit
TX: 0
It is more likely that we want to characterize the design on a byte by byte basis, and
align the two generators before transmitting each byte. In MyHDL, this is done with the
join function. By joining clauses together in a yield statement, we create a new clause
that triggers only when all of its clause arguments have triggered. For example, we can
adapt the test bench as follows:
def testJoin():
tx = Signal(1)
rx = tx
rxData = intbv(0)
for val in testvals:
txData = intbv(val)
yield join(rs232_rx(rx, rxData), rs232_tx(tx, txData, duration=T_10200))
Now, transmission of a new byte only starts when the previous one is received:
-- Transmitting 0xc5 --
TX: start bit
RX: start bit
...
TX: 1
RX: 1
TX: 1
TX: stop bit
RX: 1
RX: stop bit
-- Received 0xc5 --
-- Transmitting 0x3a --
TX: start bit
RX: start bit
TX: 0
RX: 0
Modeling memories with built-in types
Python has powerful built-in data types that can be useful to model hardware memories.
This can be merely a matter of putting an interface around some data type operations.
For example, a dictionary comes in handy to model sparse memory structures. (In other
languages, this data type is called associative array, or hash table.) A sparse memory is
one in which only a small part of the addresses is used in a particular application or
simulation. Instead of statically allocating the full address space, which can be large,
it is better to dynamically allocate the needed storage space. This is exactly what a
dictionary provides. The following is an example of a sparse memory model:
def sparseMemory(dout, din, addr, we, en, clk):
""" Sparse memory model based on a dictionary.
Ports:
dout -- data out
din -- data in
addr -- address bus
we -- write enable: write if 1, read otherwise
en -- interface enable: enabled if 1
clk -- clock input
"""
memory = {}
@always(clk.posedge)
def access():
if en:
if we:
memory[addr.val] = din.val
else:
dout.next = memory[addr.val]
return access
Note how we use the val attribute of the din signal, as we don't want to store the signal
object itself, but its current value. Similarly, we use the val attribute of the addr
signal as the dictionary key.
In many cases, MyHDL code uses a signal's current value automatically when there is no
ambiguity: for example, when a signal is used in an expression. However, in other cases,
such as in this example, you have to refer to the value explicitly: for example, when the
Signal is used as a dictionary key, or when it is not used in an expression. One option
is to use the val attribute, as in this example. Another possibility is to use the int()
or bool() functions to typecast the Signal to an integer or a boolean value. These
functions are also useful with intbv objects.
As a second example, we will demonstrate how to use a list to model a synchronous fifo:
def fifo(dout, din, re, we, empty, full, clk, maxFilling=sys.maxint):
""" Synchronous fifo model based on a list.
Ports:
dout -- data out
din -- data in
re -- read enable
we -- write enable
empty -- empty indication flag
full -- full indication flag
clk -- clock input
Optional parameter:
maxFilling -- maximum fifo filling, "infinite" by default
"""
memory = []
@always(clk.posedge)
def access():
if we:
memory.insert(0, din.val)
if re:
dout.next = memory.pop()
filling = len(memory)
empty.next = (filling == 0)
full.next = (filling == maxFilling)
return access
Again, the model is merely a MyHDL interface around some operations on a list: insert to
insert entries, pop to retrieve them, and len to get the size of a Python object.
Modeling errors using exceptions
In the previous section, we used Python data types for modeling. If such a type is used
inappropriately, Python's run time error system will come into play. For example, if we
access an address in the sparseMemory model that was not initialized before, we will get a
traceback similar to the following (some lines omitted for clarity):
Traceback (most recent call last):
...
File "sparseMemory.py", line 31, in access
dout.next = memory[addr.val]
KeyError: Signal(51)
Similarly, if the fifo is empty, and we attempt to read from it, we get:
Traceback (most recent call last):
...
File "fifo.py", line 34, in fifo
dout.next = memory.pop()
IndexError: pop from empty list
Instead of these low level errors, it may be preferable to define errors at the functional
level. In Python, this is typically done by defining a custom Error exception, by
subclassing the standard Exception class. This exception is then raised explicitly when an
error condition occurs.
For example, we can change the sparseMemory function as follows (with the doc string is
omitted for brevity):
class Error(Exception):
pass
def sparseMemory2(dout, din, addr, we, en, clk):
memory = {}
@always(clk.posedge)
def access():
if en:
if we:
memory[addr.val] = din.val
else:
try:
dout.next = memory[addr.val]
except KeyError:
raise Error, "Uninitialized address %s" % hex(addr)
return access
This works by catching the low level data type exception, and raising the custom exception
with an appropriate error message instead. If the sparseMemory function is defined in a
module with the same name, an access error is now reported as follows:
Traceback (most recent call last):
...
File "sparseMemory.py", line 61, in access
raise Error, "Uninitialized address %s" % hex(addr)
Error: Uninitialized address 0x33
Likewise, the fifo function can be adapted as follows, to report underflow and overflow
errors:
class Error(Exception):
pass
def fifo2(dout, din, re, we, empty, full, clk, maxFilling=sys.maxint):
memory = []
@always(clk.posedge)
def access():
if we:
memory.insert(0, din.val)
if re:
try:
dout.next = memory.pop()
except IndexError:
raise Error, "Underflow -- Read from empty fifo"
filling = len(memory)
empty.next = (filling == 0)
full.next = (filling == maxFilling)
if filling > maxFilling:
raise Error, "Overflow -- Max filling %s exceeded" % maxFilling
return access
In this case, the underflow error is detected as before, by catching a low level exception
on the list data type. On the other hand, the overflow error is detected by a regular
check on the length of the list.
Object oriented modeling
The models in the previous sections used high-level built-in data types internally.
However, they had a conventional RTL-style interface. Communication with such a module is
done through signals that are attached to it during instantiation.
A more advanced approach is to model hardware blocks as objects. Communication with
objects is done through method calls. A method encapsulates all details of a certain task
performed by the object. As an object has a method interface instead of an RTL-style
hardware interface, this is a much higher level approach.
As an example, we will design a synchronized queue object. Such an object can be filled
by producer, and independently read by a consumer. When the queue is empty, the consumer
should wait until an item is available. The queue can be modeled as an object with a
put(item) and a get method, as follows:
from myhdl import *
def trigger(event):
event.next = not event
class queue:
def __init__(self):
self.l = []
self.sync = Signal(0)
self.item = None
def put(self,item):
# non time-consuming method
self.l.append(item)
trigger(self.sync)
def get(self):
# time-consuming method
if not self.l:
yield self.sync
self.item = self.l.pop(0)
The queue object constructor initializes an internal list to hold items, and a sync signal
to synchronize the operation between the methods. Whenever put puts an item in the queue,
the signal is triggered. When the get method sees that the list is empty, it waits on the
trigger first. get is a generator method because it may consume time. As the yield
statement is used in MyHDL for timing control, the method cannot "yield" the item.
Instead, it makes it available in the item instance variable.
To test the queue operation, we will model a producer and a consumer in the test bench.
As a waiting consumer should not block a whole system, it should run in a concurrent
"thread". As always in MyHDL, concurrency is modeled by Python generators. Producer and
consumer will thus run independently, and we will monitor their operation through some
print statements:
q = queue()
def Producer(q):
yield delay(120)
for i in range(5):
print "%s: PUT item %s" % (now(), i)
q.put(i)
yield delay(max(5, 45 - 10*i))
def Consumer(q):
yield delay(100)
while 1:
print "%s: TRY to get item" % now()
yield q.get()
print "%s: GOT item %s" % (now(), q.item)
yield delay(30)
def main():
P = Producer(q)
C = Consumer(q)
return P, C
sim = Simulation(main())
sim.run()
Note that the generator method get is called in a yield statement in the Consumer
function. The new generator will take over from Consumer, until it is done. Running this
test bench produces the following output:
% python queue.py
100: TRY to get item
120: PUT item 0
120: GOT item 0
150: TRY to get item
165: PUT item 1
165: GOT item 1
195: TRY to get item
200: PUT item 2
200: GOT item 2
225: PUT item 3
230: TRY to get item
230: GOT item 3
240: PUT item 4
260: TRY to get item
260: GOT item 4
290: TRY to get item
StopSimulation: No more events
Unit testing
Introduction
Many aspects in the design flow of modern digital hardware design can be viewed as a
special kind of software development. From that viewpoint, it is a natural question
whether advances in software design techniques can not also be applied to hardware design.
One software design approach that deserves attention is Extreme Programming (XP). It is a
fascinating set of techniques and guidelines that often seems to go against the
conventional wisdom. On other occasions, XP just seems to emphasize the common sense,
which doesn't always coincide with common practice. For example, XP stresses the
importance of normal workweeks, if we are to have the fresh mind needed for good software
development.
It is not my intention nor qualification to present a tutorial on Extreme Programming.
Instead, in this section I will highlight one XP concept which I think is very relevant to
hardware design: the importance and methodology of unit testing.
The importance of unit tests
Unit testing is one of the corner stones of Extreme Programming. Other XP concepts, such
as collective ownership of code and continuous refinement, are only possible by having
unit tests. Moreover, XP emphasizes that writing unit tests should be automated, that they
should test everything in every class, and that they should run perfectly all the time.
I believe that these concepts apply directly to hardware design. In addition, unit tests
are a way to manage simulation time. For example, a state machine that runs very slowly on
infrequent events may be impossible to verify at the system level, even on the fastest
simulator. On the other hand, it may be easy to verify it exhaustively in a unit test,
even on the slowest simulator.
It is clear that unit tests have compelling advantages. On the other hand, if we need to
test everything, we have to write lots of unit tests. So it should be easy and pleasant to
create, manage and run them. Therefore, XP emphasizes the need for a unit test framework
that supports these tasks. In this chapter, we will explore the use of the unittest module
from the standard Python library for creating unit tests for hardware designs.
Unit test development
In this section, we will informally explore the application of unit test techniques to
hardware design. We will do so by a (small) example: testing a binary to Gray encoder as
introduced in section hwtypes-indexing.
Defining the requirements
We start by defining the requirements. For a Gray encoder, we want to the output to comply
with Gray code characteristics. Let's define a code as a list of codewords, where a
codeword is a bit string. A code of order n has 2**n codewords.
A well-known characteristic is the one that Gray codes are all about:
Consecutive codewords in a Gray code should differ in a single bit.
Is this sufficient? Not quite: suppose for example that an implementation returns the lsb
of each binary input. This would comply with the requirement, but is obviously not what we
want. Also, we don't want the bit width of Gray codewords to exceed the bit width of the
binary codewords.
Each codeword in a Gray code of order n must occur exactly once in the binary code of the
same order.
With the requirements written down we can proceed.
Writing the test first
A fascinating guideline in the XP world is to write the unit test first. That is, before
implementing something, first write the test that will verify it. This seems to go
against our natural inclination, and certainly against common practices. Many engineers
like to implement first and think about verification afterwards.
But if you think about it, it makes a lot of sense to deal with verification first.
Verification is about the requirements only --- so your thoughts are not yet cluttered
with implementation details. The unit tests are an executable description of the
requirements, so they will be better understood and it will be very clear what needs to be
done. Consequently, the implementation should go smoother. Perhaps most importantly, the
test is available when you are done implementing, and can be run anytime by anybody to
verify changes.
Python has a standard unittest module that facilitates writing, managing and running unit
tests. With unittest, a test case is written by creating a class that inherits from
unittest.TestCase. Individual tests are created by methods of that class: all method names
that start with test are considered to be tests of the test case.
We will define a test case for the Gray code properties, and then write a test for each of
the requirements. The outline of the test case class is as follows:
import unittest
class TestGrayCodeProperties(unittest.TestCase):
def testSingleBitChange(self):
"""Check that only one bit changes in successive codewords."""
....
def testUniqueCodeWords(self):
"""Check that all codewords occur exactly once."""
....
Each method will be a small test bench that tests a single requirement. To write the
tests, we don't need an implementation of the Gray encoder, but we do need the interface
of the design. We can specify this by a dummy implementation, as follows:
For the first requirement, we will test all consecutive input numbers, and compare the
current output with the previous one For each input, we check that the difference is
exactly a single bit. For the second requirement, we will test all input numbers and put
the result in a list. The requirement implies that if we sort the result list, we should
get a range of numbers. For both requirements, we will test all Gray codes up to a certain
order MAX_WIDTH. The test code looks as follows:
Note how the actual check is performed by a self.assertEqual method, defined by the
unittest.TestCase class. Also, we have factored out running the tests for all Gray codes
in a separate method runTests.
Test-driven implementation
With the test written, we begin with the implementation. For illustration purposes, we
will intentionally write some incorrect implementations to see how the test behaves.
The easiest way to run tests defined with the unittest framework, is to put a call to its
main method at the end of the test module:
unittest.main()
Let's run the test using the dummy Gray encoder shown earlier:
% python test_gray_properties.py
testSingleBitChange (__main__.TestGrayCodeProperties)
Check that only one bit changes in successive codewords. ... ERROR
testUniqueCodeWords (__main__.TestGrayCodeProperties)
Check that all codewords occur exactly once. ... ERROR
As expected, this fails completely. Let us try an incorrect implementation, that puts the
lsb of in the input on the output:
Running the test produces:
python test_gray_properties.py
testSingleBitChange (__main__.TestGrayCodeProperties)
Check that only one bit changes in successive codewords. ... ok
testUniqueCodeWords (__main__.TestGrayCodeProperties)
Check that all codewords occur exactly once. ... FAIL
======================================================================
FAIL: testUniqueCodeWords (__main__.TestGrayCodeProperties)
Check that all codewords occur exactly once.
----------------------------------------------------------------------
Traceback (most recent call last):
File "test_gray_properties.py", line 42, in testUniqueCodeWords
self.runTests(test)
File "test_gray_properties.py", line 53, in runTests
sim.run(quiet=1)
File "/home/jand/dev/myhdl/myhdl/_Simulation.py", line 154, in run
waiter.next(waiters, actives, exc)
File "/home/jand/dev/myhdl/myhdl/_Waiter.py", line 127, in next
clause = next(self.generator)
File "test_gray_properties.py", line 40, in test
self.assertEqual(actual, expected)
AssertionError: Lists differ: [0, 0, 1, 1] != [0, 1, 2, 3]
First differing element 1:
0
1
- [0, 0, 1, 1]
+ [0, 1, 2, 3]
----------------------------------------------------------------------
Ran 2 tests in 0.083s
FAILED (failures=1)
Now the test passes the first requirement, as expected, but fails the second one. After
the test feedback, a full traceback is shown that can help to debug the test output.
Finally, we use a correct implementation:
Now the tests pass:
Additional requirements
In the previous section, we concentrated on the general requirements of a Gray code. It is
possible to specify these without specifying the actual code. It is easy to see that there
are several codes that satisfy these requirements. In good XP style, we only tested the
requirements and nothing more.
It may be that more control is needed. For example, the requirement may be for a
particular code, instead of compliance with general properties. As an illustration, we
will show how to test for the original Gray code, which is one specific instance that
satisfies the requirements of the previous section. In this particular case, this test
will actually be easier than the previous one.
We denote the original Gray code of order n as Ln. Some examples:
L1 = ['0', '1']
L2 = ['00', '01', '11', '10']
L3 = ['000', '001', '011', '010', '110', '111', '101', 100']
It is possible to specify these codes by a recursive algorithm, as follows:
1. L1 = ['0', '1']
2. Ln+1 can be obtained from Ln as follows. Create a new code Ln0 by prefixing all
codewords of Ln with '0'. Create another new code Ln1 by prefixing all codewords of Ln
with '1', and reversing their order. Ln+1 is the concatenation of Ln0 and Ln1.
Python is well-known for its elegant algorithmic descriptions, and this is a good example.
We can write the algorithm in Python as follows:
The code ['0' + codeword for ...] is called a list comprehension. It is a concise way to
describe lists built by short computations in a for loop.
The requirement is now that the output code matches the expected code Ln. We use the
nextLn function to compute the expected result. The new test case code is as follows:
As it happens, our implementation is apparently an original Gray code:
Co-simulation with Verilog
Introduction
One of the most exciting possibilities of MyHDLis to use it as a hardware verification
language (HVL). A HVL is a language used to write test benches and verification
environments, and to control simulations.
Nowadays, it is generally acknowledged that HVLs should be equipped with modern software
techniques, such as object orientation. The reason is that verification it the most
complex and time-consuming task of the design process. Consequently, every useful
technique is welcome. Moreover, test benches are not required to be implementable.
Therefore, unlike with synthesizable code, there are no constraints on creativity.
Technically, verification of a design implemented in another language requires
co-simulation. MyHDL is enabled for co-simulation with any HDL simulator that has a
procedural language interface (PLI). The MyHDLside is designed to be independent of a
particular simulator, On the other hand, for each HDL simulator a specific PLI module will
have to be written in C. Currently, the MyHDL release contains a PLI module for two
Verilog simulators: Icarus and Cver.
The HDL side
To introduce co-simulation, we will continue to use the Gray encoder example from the
previous chapters. Suppose that we want to synthesize it and write it in Verilog for that
purpose. Clearly we would like to reuse our unit test verification environment.
To start, let's recall how the Gray encoder in MyHDL looks like:
To show the co-simulation flow, we don't need the Verilog implementation yet, but only the
interface. Our Gray encoder in Verilog would have the following interface:
module bin2gray(B, G);
parameter width = 8;
input [width-1:0] B;
output [width-1:0] G;
....
To write a test bench, one creates a new module that instantiates the design under test
(DUT). The test bench declares nets and regs (or signals in VHDL) that are attached to
the DUT, and to stimulus generators and response checkers. In an all-HDL flow, the
generators and checkers are written in the HDL itself, but we will want to write them in
MyHDL. To make the connection, we need to declare which regs & nets are driven and read by
the MyHDLsimulator. For our example, this is done as follows:
module dut_bin2gray;
reg [`width-1:0] B;
wire [`width-1:0] G;
initial begin
$from_myhdl(B);
$to_myhdl(G);
end
bin2gray dut (.B(B), .G(G));
defparam dut.width = `width;
endmodule
The $from_myhdl task call declares which regs are driven by MyHDL, and the $to_myhdl task
call which regs & nets are read by it. These tasks take an arbitrary number of arguments.
They are defined in a PLI module written in C and made available in a simulator-dependent
manner. In Icarus Verilog, the tasks are defined in a myhdl.vpi module that is compiled
from C source code.
The MyHDL side
MyHDL supports co-simulation by a Cosimulation object. A Cosimulation object must know
how to run a HDL simulation. Therefore, the first argument to its constructor is a command
string to execute a simulation.
The way to generate and run an simulation executable is simulator dependent. For example,
in Icarus Verilog, a simulation executable for our example can be obtained obtained by
running the iverilog compiler as follows:
% iverilog -o bin2gray -Dwidth=4 bin2gray.v dut_bin2gray.v
This generates a bin2gray executable for a parameter width of 4, by compiling the
contributing Verilog files.
The simulation itself is run by the vvp command:
% vvp -m ./myhdl.vpi bin2gray
This runs the bin2gray simulation, and specifies to use the myhdl.vpi PLI module present
in the current directory. (This is just a command line usage example; actually simulating
with the myhdl.vpi module is only meaningful from a Cosimulation object.)
We can use a Cosimulation object to provide a HDL version of a design to the MyHDL
simulator. Instead of a generator function, we write a function that returns a
Cosimulation object. For our example and the Icarus Verilog simulator, this is done as
follows:
import os
from myhdl import Cosimulation
cmd = "iverilog -o bin2gray.o -Dwidth=%s " + \
"../../test/verilog/bin2gray.v " + \
"../../test/verilog/dut_bin2gray.v "
def bin2gray(B, G):
width = len(B)
os.system(cmd % width)
return Cosimulation("vvp -m ../myhdl.vpi bin2gray.o", B=B, G=G)
After the executable command argument, the Cosimulation constructor takes an arbitrary
number of keyword arguments. Those arguments make the link between MyHDL Signals and HDL
nets, regs, or signals, by named association. The keyword is the name of an argument in a
$to_myhdl or $from_myhdl call; the argument is a MyHDL Signal.
With all this in place, we can now use the existing unit test to verify the Verilog
implementation. Note that we kept the same name and parameters for the the bin2gray
function: all we need to do is to provide this alternative definition to the existing unit
test.
Let's try it on the Verilog design:
module bin2gray(B, G);
parameter width = 8;
input [width-1:0] B;
output [width-1:0] G;
assign G = (B >> 1) ^ B;
endmodule // bin2gray
When we run our unit tests, we get:
% python test_gray.py
testSingleBitChange (test_gray_properties.TestGrayCodeProperties)
Check that only one bit changes in successive codewords. ... ok
testUniqueCodeWords (test_gray_properties.TestGrayCodeProperties)
Check that all codewords occur exactly once. ... ok
testOriginalGrayCode (test_gray_original.TestOriginalGrayCode)
Check that the code is an original Gray code. ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.706s
OK
Restrictions
In the ideal case, it should be possible to simulate any HDL description seamlessly with
MyHDL. Moreover the communicating signals at each side should act transparently as a
single one, enabling fully race free operation.
For various reasons, it may not be possible or desirable to achieve full generality. As
anyone that has developed applications with the Verilog PLI can testify, the restrictions
in a particular simulator, and the differences over various simulators, can be quite
frustrating. Moreover, full generality may require a disproportionate amount of
development work compared to a slightly less general solution that may be sufficient for
the target application.
Consequently, I have tried to achieve a solution which is simple enough so that one can
reasonably expect that any PLI-enabled simulator can support it, and that is relatively
easy to verify and maintain. At the same time, the solution is sufficiently general to
cover the target application space.
The result is a compromise that places certain restrictions on the HDL code. In this
section, these restrictions are presented.
Only passive HDL can be co-simulated
The most important restriction of the MyHDL co-simulation solution is that only "passive"
HDL can be co-simulated. This means that the HDL code should not contain any statements
with time delays. In other words, the MyHDL simulator should be the master of time; in
particular, any clock signal should be generated at the MyHDL side.
At first this may seem like an important restriction, but if one considers the target
application for co-simulation, it probably isn't.
MyHDL supports co-simulation so that test benches for HDL designs can be written in
Python. Let's consider the nature of the target HDL designs. For high-level, behavioral
models that are not intended for implementation, it should come as no surprise that I
would recommend to write them in MyHDL directly; that is one of the goals of the MyHDL
effort. Likewise, gate level designs with annotated timing are not the target application:
static timing analysis is a much better verification method for such designs.
Rather, the targeted HDL designs are naturally models that are intended for
implementation, most likely through synthesis. As time delays are meaningless in
synthesizable code, the restriction is compatible with the target application.
Race sensitivity issues
In a typical RTL code, some events cause other events to occur in the same time step. For
example, when a clock signal triggers some signals may change in the same time step. For
race-free operation, an HDL must differentiate between such events within a time step.
This is done by the concept of "delta" cycles. In a fully general, race free
co-simulation, the co-simulators would communicate at the level of delta cycles. However,
in MyHDL co-simulation, this is not entirely the case.
Delta cycles from the MyHDL simulator toward the HDL co-simulator are preserved. However,
in the opposite direction, they are not. The signals changes are only returned to the
MyHDL simulator after all delta cycles have been performed in the HDL co-simulator.
What does this mean? Let's start with the good news. As explained in the previous section,
the concept behind MyHDL co-simulation implies that clocks are generated at the MyHDL
side. When using a MyHDL clock and its corresponding HDL signal directly as a clock,
co-simulation is race free. In other words, the case that most closely reflects the MyHDL
co-simulation approach, is race free.
The situation is different when you want to use a signal driven by the HDL (and the
corresponding MyHDL signal) as a clock. Communication triggered by such a clock is not
race free. The solution is to treat such an interface as a chip interface instead of an
RTL interface. For example, when data is triggered at positive clock edges, it can safely
be sampled at negative clock edges. Alternatively, the MyHDL data signals can be declared
with a delay value, so that they are guaranteed to change after the clock edge.
Implementation notes
This section requires some knowledge of PLI terminology.
Enabling a simulator for co-simulation requires a PLI module written in C. In Verilog, the
PLI is part of the "standard". However, different simulators implement different versions
and portions of the standard. Worse yet, the behavior of certain PLI callbacks is not
defined on some essential points. As a result, one should plan to write or at least
customize a specific PLI module for any simulator. The release contains a PLI module for
the open source Icarus and Cver simulators.
This section documents the current approach and status of the PLI module implementation
and some reflections on future implementations.
Icarus Verilog
Delta cycle implementation
To make co-simulation work, a specific type of PLI callback is needed. The callback should
be run when all pending events have been processed, while allowing the creation of new
events in the current time step (e.g. by the MyHDL simulator). In some Verilog
simulators, the cbReadWriteSync callback does exactly that. However, in others, including
Icarus, it does not. The callback's behavior is not fully standardized; some simulators
run the callback before non- blocking assignment events have been processed.
Consequently, I had to look for a workaround. One half of the solution is to use the
cbReadOnlySync callback. This callback runs after all pending events have been processed.
However, it does not permit one to create new events in the current time step. The second
half of the solution is to map MyHDL delta cycles onto real Verilog time steps. Note that
fortunately I had some freedom here because of the restriction that only passive HDL code
can be co-simulated.
I chose to make the time granularity in the Verilog simulator a 1000 times finer than in
the MyHDL simulator. For each MyHDL time step, 1000 Verilog time steps are available for
MyHDL delta cycles. In practice, only a few delta cycles per time step should be needed.
Exceeding this limit almost certainly indicates a design error; the limit is checked at
run-time. The factor 1000 also makes it easy to distinguish "real" time from delta cycle
time when printing out the Verilog time.
Passive Verilog check
As explained before, co-simulated Verilog should not contain delay statements. Ideally,
there should be a run-time check to flag non-compliant code. However, there is currently
no such check in the Icarus module.
The check can be written using the cbNextSimTime VPI callback in Verilog. However, Icarus
0.7 doesn't support this callback. In the meantime, support for it has been added to the
Icarus development branch. When Icarus 0.8 is released, a check will be added.
In the mean time, just don't do this. It may appear to "work" but it really won't as
events will be missed over the co-simulation interface.
Cver
MyHDL co-simulation is supported with the open source Verilog simulator Cver. The PLI
module is based on the one for Icarus and basically has the same functionality. Only some
cosmetic modifications were required.
Other Verilog simulators
The Icarus module is written with VPI calls, which are provided by the most recent
generation of the Verilog PLI. Some simulators may only support TF/ACC calls, requiring a
complete redesign of the interface module.
If the simulator supports VPI, the Icarus module should be reusable to a large extent.
However, it may be possible to improve on it. The workaround to support delta cycles
described in Section Delta cycle implementation may not be necessary. In some simulators,
the cbReadWriteSync callback occurs after all events (including non-blocking assignments)
have been processed. In that case, the functionality can be supported without a finer time
granularity in the Verilog simulator.
There are also Verilog standardization efforts underway to resolve the ambiguity of the
cbReadWriteSync callback. The solution will be to introduce new, well defined callbacks.
From reading some proposals, I conclude that the cbEndOfSimTime callback would provide the
required functionality.
The MyHDL project currently has no access to commercial Verilog simulators, so progress in
co-simulation support depends on external interest and participation. Users have reported
that they are using MyHDL co-simulation with the simulators from Aldec and Modelsim.
Interrupted system calls
The PLI module uses read and write system calls to communicate between the co-simulators.
The implementation assumes that these calls are restarted automatically by the operating
system when interrupted. This is apparently what happens on the Linux box on which MyHDL
is developed.
It is known how non-restarted interrupted system calls should be handled, but currently
such code cannot be tested on the MyHDL development platform. Also, it is not clear
whether this is still a relevant issue with modern operating systems. Therefore, this
issue has not been addressed at this moment. However, assertions have been included that
should trigger when this situation occurs.
Whenever an assertion fires in the PLI module, please report it. The same holds for
Python exceptions that cannot be easily explained.
What about VHDL?
It would be nice to have an interface to VHDL simulators such as the Modelsim VHDL
simulator. Let us summarize the requirements to accomplish that:
• We need a procedural interface to the internals of the simulator.
• The procedural interface should be a widely used industry standard so that we can reuse
the work in several simulators.
• MyHDL is an open-source project and therefore there should be also be an open-source
simulator that implements the procedural interface.
vpi for Verilog matches these requirements. It is a widely used standard and is supported
by the open-source Verilog simulators Icarus and cver.
However, for VHDL the situation is different. While there exists a standard called vhpi,
it much less popular than vpi. Also, to our knowledge there is only one credible open
source VHDL simulator (GHDL) and it is unclear whether it has vhpi capabilities that are
powerful enough for MyHDL's purposes.
Consequently, the development of co-simulation for VHDL is currently on hold. For some
applications, there is an alternative: see conv-testbench.
Conversion to Verilog and VHDL
Introduction
Subject to some limitations, MyHDL supports the automatic conversion of MyHDL code to
Verilog or VHDL code. This feature provides a path from MyHDL into a standard Verilog or
VHDL based design environment.
This chapter describes the concepts of conversion. Concrete examples can be found in the
companion chapter conv-usage.
Solution description
To be convertible, the hardware description should satisfy certain restrictions, defined
as the convertible subset. This is described in detail in The convertible subset.
A convertible design can be converted to an equivalent model in Verilog or VHDL, using the
function toVerilog or toVHDL from the MyHDL library.
When the design is intended for implementation a third-party synthesis tool is used to
compile the Verilog or VHDL model into an implementation for an ASIC or FPGA. With this
step, there is an automated path from a hardware description in Python to an FPGA or ASIC
implementation.
The conversion does not start from source files, but from an instantiated design that has
been elaborated by the Python interpreter. The converter uses the Python profiler to track
the interpreter's operation and to infer the design structure and name spaces. It then
selectively compiles pieces of source code for additional analysis and for conversion.
Features
Conversion after elaboration
Elaboration refers to the initial processing of a hardware description to achieve a
representation of a design instance that is ready for simulation or synthesis. In
particular, structural parameters and constructs are processed in this step. In
MyHDL, the Python interpreter itself is used for elaboration. A Simulation object
is constructed with elaborated design instances as arguments. Likewise, conversion
works on an elaborated design instance. The Python interpreter is thus used as much
as possible.
Arbitrarily complex structure
As the conversion works on an elaborated design instance, any modeling constraints
only apply to the leaf elements of the design structure, that is, the co-operating
generators. In other words, there are no restrictions on the description of the
design structure: Python's full power can be used for that purpose. Also, the
design hierarchy can be arbitrarily deep.
Generator are mapped to Verilog or VHDL constructs
The converter analyzes the code of each generator and maps it to equivalent
constructs in the target HDL. For Verilog, it will map generators to always blocks,
continuous assignments or initial blocks. For VHDL, 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 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 convertible
An interface: an object that has a number of Signal objects as its attributes. The
converter 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 mapped to
an appropriate subprogram in the target HDL: a function or task in Verilog, and a
function or procedure in VHDL. In order to support the full power of Python
functions, a unique subprogram is generated per Python function call.
If-then-else structures may be mapped to case statements
Python does not provide a case statement. However, the converter recognizes
if-then-else structures in which a variable is sequentially compared to items of an
enumeration type, and maps such a structure to a Verilog or VHDL case statement
with the appropriate synthesis attributes.
Choice of encoding schemes for enumeration types
The enum function in MyHDL returns an enumeration type. This function takes an
additional parameter encoding that specifies the desired encoding in the
implementation: binary, one hot, or one cold. The converter generates the
appropriate code for the specified encoding.
RAM memory
Certain synthesis tools can map Verilog memories or VHDL arrays to RAM structures.
To support this interesting feature, the converter maps lists of signals to Verilog
memories or VHDL arrays.
ROM memory
Some synthesis tools can infer a ROM from a case statement. The converter does the
expansion into a case statement automatically, based on a higher level description.
The ROM access is described in a single line, by indexing into a tuple of integers.
Signed arithmetic
In MyHDL, working with negative numbers is trivial: one just uses an intbv object
with an appropriate constraint on its values. In contrast, both Verilog and VHDL
make a difference between an unsigned and a signed representation. To work with
negative values, the user has to declare a signed variable explicitly. But when
signed and unsigned operands are mixed in an expression, things may become tricky.
In Verilog, when signed and unsigned operands are mixed, all operands are
interpreted as unsigned. Obviously, this leads to unexpected results. The designer
will have to add sign extensions and type casts to solve this.
In VHDL, mixing signed and unsigned will generally not work. The designer will have
to match the operands manually by adding resizings and type casts.
In MyHDL, these issues don't exist because intbv objects simply work as
(constrained) integers. Moreover, the converter automates the cumbersome tasks that
are required in Verilog and VHDL. It uses signed or unsigned types based on the
value constraints of the intbv objects, and automatically performs the required
sign extensions, resizings, and type casts.
User-defined code
If desired, the user can bypass the conversion process and describe user-defined
code to be inserted instead.
The convertible subset
Introduction
Unsurprisingly, not all MyHDL code can be converted. Although the restrictions are
significant, the convertible subset is much broader than the RTL synthesis subset which is
an industry standard. In other words, MyHDL code written according to the RTL synthesis
rules, should always be convertible. However, it is also possible to write convertible
code for non-synthesizable models or test benches.
The converter attempts to issue clear error messages when it encounters a construct that
cannot be converted.
Recall that any restrictions only apply to the design after elaboration. In practice,
this means that they apply only to the code of the generators, that are the leaf
functional blocks in a MyHDL design.
Coding style
A natural restriction on convertible code is that it should be written in MyHDL style:
cooperating generators, communicating through signals, and with sensitivity specify resume
conditions.
For pure modeling, it doesn't matter how generators are created. However, in convertible
code they should be created using one of the MyHDL decorators: instance, always,
always_seq, or always_comb.
Supported types
The most important restriction regards object types. Only a limited amount of types can
be converted. Python int and long objects are mapped to Verilog or VHDL integers. All
other supported types need to have a defined bit width. The supported types are the Python
bool type, the MyHDL intbv type, and MyHDL enumeration types returned by function enum.
intbv objects must be constructed so that a bit width can be inferred. This can be done
by specifying minimum and maximum values, e.g. as follows:
index = intbv(0, min=MIN, max=MAX)
The Verilog converter supports intbv objects that can take negative values.
Alternatively, a slice can be taken from an intbv object as follows:
index = intbv(0)[N:]
Such as slice returns a new intbv object, with minimum value 0 , and maximum value 2**N.
In addition to the scalar types described above, the converter also supports a number of
tuple and list based types. The mapping from MyHDL types is summarized in the following
table.
┌─────────────────┬──────────────────┬───────┬──────────────────┬────────┐
│MyHDL type │ VHDL type │ Notes │ Verilog type │ Notes │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│int │ integer │ │ integer │ │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│bool │ std_logic │ (1) │ reg │ │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│intbv with min │ unsigned │ (2) │ reg │ │
│>= 0 │ │ │ │ │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│intbv with min │ signed │ (2) │ reg signed │ │
│< 0 │ │ │ │ │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│enum │ dedicated │ │ reg │ │
│ │ enumeration type │ │ │ │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│tuple of int │ mapped to case │ (3) │ mapped to case │ (3) │
│ │ statement │ │ statement │ │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│list of bool │ array of │ │ reg │ (5) │
│ │ std_logic │ │ │ │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│list of intbv │ array of │ (4) │ reg │ (4)(5) │
│with min >= 0 │ unsigned │ │ │ │
├─────────────────┼──────────────────┼───────┼──────────────────┼────────┤
│list of intbv │ array of signed │ (4) │ reg signed │ (4)(5) │
│with min < 0 │ │ │ │ │
└─────────────────┴──────────────────┴───────┴──────────────────┴────────┘
Notes:
1. The VHDL std_logic type is defined in the standard VHDL package IEEE.std_logic_1164.
2. The VHDL unsigned and signed types used are those from the standard VHDL packages
IEEE.numeric_std.
3. A MyHDL tuple of int is used for ROM inference, and can only be used in a very specific
way: an indexing operation into the tuple should be the rhs of an assignment.
4. All list members should have identical value constraints.
5. Lists are mapped to Verilog memories.
The table as presented applies to MyHDL variables. The converter also supports MyHDL
signals that use bool, intbv or enum objects as their underlying type. For VHDL, these are
mapped to VHDL signals with an underlying type as specified in the table above. Verilog
doesn't have the signal concept. For Verilog, a MyHDL signal is mapped to a Verilog reg as
in the table above, or to a Verilog wire, depending on the signal usage.
The converter supports MyHDL list of signals provided the underlying signal type is either
bool or intbv. They may be mapped to a VHDL signal with a VHDL type as specified in the
table, or to a Verilog memory. However, list of signals are not always mapped to a
corresponding VHDL or Verilog object. See Conversion of lists of signals for more info.
Supported statements
The following is a list of the statements that are supported by the Verilog converter,
possibly qualified with restrictions or usage notes.
assert An assert statement in Python looks as follow:
assert test_expression
It can be converted provided test_expression is convertible.
break
continue
def
for The only supported iteration scheme is iterating through sequences of integers
returned by built-in function range or MyHDL function downrange. The optional else
clause is not supported.
if if, elif, and else clauses are fully supported.
pass
print
A print statement with multiple arguments:
print arg1, arg2, ...
is supported. However, there are restrictions on the arguments. First, they should be
of one of the following forms:
arg
formatstring % arg
formatstring % (arg1, arg2, ...)
where arg is a bool, int, intbv, enum, or a Signal of these types.
The formatstring contains ordinary characters and conversion specifiers as in Python.
However, the only supported conversion specifiers are %s and %d. Justification and
width specification are thus not supported.
Printing without a newline:
print arg1 ,
is not supported.
raise This statement is mapped to statements that end the simulation with an error
message.
return
yield A yield expression is used to specify a sensitivity list. The yielded expression
can be a Signal, a signal edge as specified by MyHDL functions Signal.posedge or
Signal.negedge, or a tuple of signals and edge specifications. It can also be a
delay object.
while The optional else clause is not supported.
Supported built-in functions
The following is a list of the built-in functions that are supported by the converter.
bool This function can be used to typecast an object explicitly to its boolean
interpretation.
len For Signal and intbv objects, function len returns the bit width.
int This function can be used to typecast an object explicitly to its integer
interpretation.
Docstrings
The converter propagates comments under the form of Python docstrings.
Docstrings are typically used in Python to document certain objects in a standard way.
Such "official" docstrings are put into the converted output at appropriate locations.
The converter supports official docstrings for the top level module and for generators.
Within generators, "nonofficial" docstrings are propagated also. These are strings (triple
quoted by convention) that can occur anywhere between statements.
Regular Python comments are ignored by the Python parser, and they are not present in the
parse tree. Therefore, these are not propagated. With docstrings, you have an elegant way
to specify which comments should be propagated and which not.
Conversion of lists of signals
Lists of signals are useful for many purposes. For example, they make it easy to create a
repetitive structure. Another application is the description of memory behavior.
The converter output is non-hierarchical. That implies that all signals are declared at
the top-level in VHDL or Verilog (as VHDL signals, or Verilog regs and wires.) However,
some signals that are a list member at some level in the MyHDL design hierarchy may be
used as a plain signal at a lower level. For such signals, a choice has to be made whether
to declare a Verilog memory or VHDL array, or a number of plain signal names.
If possible, plain signal declarations are preferred, because Verilog memories and arrays
have some restrictions in usage and tool support. This is possible if the list syntax is
strictly used outside generator code, for example when lists of signals are used to
describe structure.
Conversely, when list syntax is used in some generator, then a Verilog memory or VHDL
array will be declared. The typical example is the description of RAM memories.
Conversion of Interfaces
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 Signal objects as its attributes. Grouping signals into an
interface simplifies the code, improves efficiency, and reduces errors.
The converter supports interface using hierarchical name expansion and name mangling.
Assignment issues
Name assignment in Python
Name assignment in Python is a different concept than in many other languages. This point
is very important for effective modeling in Python, and even more so for synthesizable
MyHDL code. Therefore, the issues are discussed here explicitly.
Consider the following name assignments:
a = 4
a = ``a string''
a = False
In many languages, the meaning would be that an existing variable a gets a number of
different values. In Python, such a concept of a variable doesn't exist. Instead,
assignment merely creates a new binding of a name to a certain object, that replaces any
previous binding. So in the example, the name a is bound a number of different objects in
sequence.
The converter has to investigate name assignment and usage in MyHDL code, and to map names
to Verilog or VHDL objects. To achieve that, it tries to infer the type and possibly the
bit width of each expression that is assigned to a name.
Multiple assignments to the same name can be supported if it can be determined that a
consistent type and bit width is being used in the assignments. This can be done for
boolean expressions, numeric expressions, and enumeration type literals.
In other cases, a single assignment should be used when an object is created. Subsequent
value changes are then achieved by modification of an existing object. This technique
should be used for Signal and intbv objects.
Signal assignment
Signal assignment in MyHDL is implemented using attribute assignment to attribute next.
Value changes are thus modeled by modification of the existing object. The converter
investigates the Signal object to infer the type and bit width of the corresponding
Verilog or VHDL object.
intbv objects
Type intbv is likely to be the workhorse for synthesizable modeling in MyHDL. An intbv
instance behaves like a (mutable) integer whose individual bits can be accessed and
modified. Also, it is possible to constrain its set of values. In addition to error
checking, this makes it possible to infer a bit width, which is required for
implementation.
As noted before, it is not possible to modify value of an intbv object using name
assignment. In the following, we will show how it can be done instead. Consider:
a = intbv(0)[8:]
This is an intbv object with initial value 0 and bit width 8. To change its value to 5, we
can use slice assignment:
a[8:] = 5
The same can be achieved by leaving the bit width unspecified, which has the meaning to
change "all" bits:
a[:] = 5
Often the new value will depend on the old one. For example, to increment an intbv with
the technique above:
a[:] = a + 1
Python also provides augmented assignment operators, which can be used to implement
in-place operations. These are supported on intbv objects and by the converter, so that
the increment can also be done as follows:
a += 1
Excluding code from conversion
For some tasks, such as debugging, it may be useful to insert arbitrary Python code that
should not be converted.
The converter supports this by ignoring all code that is embedded in a if __debug__ test.
The value of the __debug__ variable is not taken into account.
User-defined code
MyHDL provides a way to include user-defined code during the conversion process. There are
special function attributes that are understood by the converter but ignored by the
simulator. The attributes are verilog_code for Verilog and vhdl_code for VHDL. They
operate like a special return value. When defined in a MyHDL function, the converter will
use their value instead of the regular return value. Effectively, it will stop converting
at that point.
The value of verilog_code or vhdl_code should be a Python template string. A template
string supports $-based substitutions. The $name notation can be used to refer to the
variable names in the context of the string. The converter will substitute the appropriate
values in the string and then insert it instead of the regular converted output.
There is one more issue with user-defined code. Normally, the converter infers inputs,
internal signals, and outputs. It also detects undriven and multiple driven signals. To do
this, it assumes that signals are not driven by default. It then processes the code to
find out which signals are driven from where.
Proper signal usage inference cannot be done with user-defined code. Without user help,
this will result in warnings or errors during the inference process, or in compilation
errors from invalid code. The user can solve this by setting the driven or read attribute
for signals that are driven or read from the user-defined code. These attributes are
False by default. The allowed "true" values of the driven attribute are True, 'wire' and
'reg'. The latter two values specifies how the user-defined Verilog code drives the signal
in Verilog. To decide which value to use, consider how the signal should be declared in
Verilog after the user-defined code is inserted.
For an example of user-defined code, see conv-usage-custom.
Template transformation
NOTE:
This section is only relevant for VHDL.
There is a difference between VHDL and Verilog in the way in which sensitivity to signal
edges is specified. In Verilog, edge specifiers can be used directly in the sensitivity
list. In VHDL, this is not possible: only signals can be used in the sensitivity list. To
check for an edge, one uses the rising_edge() or falling_edge() functions in the code.
MyHDL follows the Verilog scheme to specify edges in the sensitivity list. Consequently,
when mapping such code to VHDL, it needs to be transformed to equivalent VHDL. This is an
important issue because it affects all synthesizable templates that infer sequential
logic.
We will illustrate this feature with some examples. This is the MyHDL code for a D
flip-flop:
@always(clk.posedge)
def logic():
q.next = d
It is converted to VHDL as follows:
DFF_LOGIC: process (clk) is
begin
if rising_edge(clk) then
q <= d;
end if;
end process DFF_LOGIC;
The converter can handle the more general case. For example, this is MyHDL code for a D
flip-flop with asynchronous set, asynchronous reset, and preference of set over reset:
@always(clk.posedge, set.negedge, rst.negedge)
def logic():
if set == 0:
q.next = 1
elif rst == 0:
q.next = 0
else:
q.next = d
This is converted to VHDL as follows:
DFFSR_LOGIC: process (clk, set, rst) is
begin
if (set = '0') then
q <= '1';
elsif (rst = '0') then
q <= '0';
elsif rising_edge(clk) then
q <= d;
end if;
end process DFFSR_LOGIC;
All cases with practical utility can be handled in this way. However, there are other
cases that cannot be transformed to equivalent VHDL. The converter will detect those cases
and give an error.
Conversion output verification by co-simulation
NOTE:
This section is only relevant for Verilog.
To verify the converted Verilog output, co-simulation can be used. To make this task
easier, the converter also generates a test bench that makes it possible to simulate the
Verilog design using the Verilog co-simulation interface. This permits one to verify the
Verilog code with the same test bench used for the MyHDL code.
Conversion of test benches
After conversion, we obviously want to verify that the VHDL or Verilog code works
correctly. For Verilog, we can use co-simulation as discussed earlier. However, for VHDL,
co-simulation is currently not supported.
An alternative is to convert the test bench itself, so that both test bench and design can
be run in the HDL simulator. Of course, this is not a fully general solution, as there are
important constraints on the kind of code that can be converted. Thus, the question is
whether the conversion restrictions permit one to develop sufficiently complex test
benches. In this section, we present some insights about this.
The most important restrictions regard the types that can be used, as discussed earlier in
this chapter. However, the "convertible subset" is wider than the "synthesis subset". We
will present a number of non-synthesizable feature that are of interest for test benches.
the while loop
while loops can be used for high-level control structures.
the raise statement
A raise statement can stop the simulation on an error condition.
delay objects
Delay modeling is essential for test benches.
the print statement
print statements can be used for simple debugging.
the assert statement.
Originally, assert statements were only intended to insert debugging assertions in
code. Recently, there is a tendency to use them to write self-checking unit tests,
controlled by unit test frameworks such as py.test. In particular, they are a
powerful way to write self-checking test benches for MyHDL designs. As assert
statements are convertible, a whole unit test suite in MyHDL can be converted to an
equivalent test suite in Verilog and VHDL.
Additionally, the same techniques as for synthesizable code can be used to master
complexity. In particular, any code outside generators is executed during elaboration, and
therefore not considered in the conversion process. This feature can for example be used
for complex calculations that set up constants or expected results. Furthermore, a tuple
of ints can be used to hold a table of values that will be mapped to a case statement in
Verilog and VHDL.
Methodology notes
Simulate first
In the Python philosophy, the run-time rules. The Python compiler doesn't attempt to
detect a lot of errors beyond syntax errors, which given Python's ultra-dynamic nature
would be an almost impossible task anyway. To verify a Python program, one should run it,
preferably using unit testing to verify each feature.
The same philosophy should be used when converting a MyHDL description to Verilog: make
sure the simulation runs fine first. Although the converter checks many things and
attempts to issue clear error messages, there is no guarantee that it does a meaningful
job unless the simulation runs fine.
Handling hierarchy
Recall that conversion occurs after elaboration. A consequence is that the converted
output is non-hierarchical. In many cases, this is not an issue. The purpose of conversion
is to provide a path into a traditional design flow by using Verilog and VHDL as a
"back-end" format. Hierarchy is quite relevant to humans, but much less so to tools.
However, in some cases hierarchy is desirable. For example, if you convert a test bench
you may prefer to keep its code separate from the design under test. In other words,
conversion should stop at the design under test instance, and insert an instantiation
instead.
There is a workaround to accomplish this with a small amount of additional work. The
workaround is to define user-defined code consisting of an instantiation of the design
under test. As discussed in User-defined code, when the converter sees the hook it will
stop converting and insert the instantiation instead. Of course, you will want to convert
the design under test itself also. Therefore, you should use a flag that controls whether
the hook is defined or not and set it according to the desired conversion.
Known issues
Verilog and VHDL integers are 32 bit wide
Usually, Verilog and VHDL integers are 32 bit wide. In contrast, Python is moving
toward integers with undefined width. Python int and long variables are mapped to
Verilog integers; so for values wider than 32 bit this mapping is incorrect.
Synthesis pragmas are specified as Verilog comments.
The recommended way to specify synthesis pragmas in Verilog is through attribute
lists. However, the Icarus simulator doesn't support them for case statements (to
specify parallel_case and full_case pragmas). Therefore, the old but deprecated
method of synthesis pragmas in Verilog comments is still used.
Inconsistent place of the sensitivity list inferred from always_comb.
The semantics of always_comb, both in Verilog and MyHDL, is to have an implicit
sensitivity list at the end of the code. However, this may not be synthesizable.
Therefore, the inferred sensitivity list is put at the top of the corresponding
always block or process. This may cause inconsistent behavior at the start of the
simulation. The workaround is to create events at time 0.
Conversion examples
Introduction
In this chapter, we will demonstrate the conversion process with a number of examples. For
the concepts of MyHDL conversion, read the companion chapter conv.
A small sequential design
Consider the following MyHDL code for an incrementer block:
This design can be converted to Verilog and VHDL. The first step is to elaborate it, just
as we do for simulation. Then we can use the convert method on the elaborated instance.
For flexibility, we wrap the conversion in a convert_inc function. inc_1 is an elaborated
design instance that provides the conversion method.
The conversion to Verilog generates an equivalent Verilog module in file inc.v. The
Verilog code looks as follows:
The converter infers a proper Verilog module interface and maps the MyHDL generator to a
Verilog always block.
Similarly, the conversion to VHDL generates a file inc.vhd with the following content:
The MyHDL generator is mapped to a VHDL process in this case.
Note that the VHDL file refers to a VHDL package called pck_myhdl_<version>. This package
contains a number of convenience functions that make the conversion easier.
Note also the use of an inout in the interface. This is not recommended VHDL design
practice, but it is required here to have a valid VHDL design that matches the behavior of
the MyHDL design. As this is only an issue for ports and as the converter output is
non-hierarchical, the issue is not very common and has an easy workaround.
A small combinatorial design
The second example is a small combinatorial design, more specifically the binary to Gray
code converter from previous chapters:
As before, you can create an instance and convert to Verilog and VHDL as follows:
The generated Verilog code looks as follows:
The generated VHDL code looks as follows:
A hierarchical design
The converter can handle designs with an arbitrarily deep hierarchy.
For example, suppose we want to design an incrementer with Gray code output. Using the
designs from previous sections, we can proceed as follows:
According to Gray code properties, only a single bit will change in consecutive values.
However, as the bin2gray module is combinatorial, the output bits may have transient
glitches, which may not be desirable. To solve this, let's create an additional level of
hierarchy and add an output register to the design. (This will create an additional
latency of a clock cycle, which may not be acceptable, but we will ignore that here.)
We can convert this hierarchical design as follows:
The Verilog output code looks as follows:
The VHDL output code looks as follows:
Note that the output is a flat "net list of blocks", and that hierarchical signal names
are generated as necessary.
Optimizations for finite state machines
As often in hardware design, finite state machines deserve special attention.
In Verilog and VHDL, finite state machines are typically described using case statements.
Python doesn't have a case statement, but the converter recognizes particular if-then-else
structures and maps them to case statements. This optimization occurs when a variable
whose type is an enumerated type is sequentially tested against enumeration items in an
if-then-else structure. Also, the appropriate synthesis pragmas for efficient synthesis
are generated in the Verilog code.
As a further optimization, function enum was enhanced to support alternative encoding
schemes elegantly, using an additional parameter encoding. For example:
t_State = enum('SEARCH', 'CONFIRM', 'SYNC', encoding='one_hot')
The default encoding is 'binary'; the other possibilities are 'one_hot' and 'one_cold'.
This parameter only affects the conversion output, not the behavior of the type. The
generated Verilog code for case statements is optimized for an efficient implementation
according to the encoding. Note that in contrast, a Verilog designer has to make
nontrivial code changes to implement a different encoding scheme.
As an example, consider the following finite state machine, whose state variable uses the
enumeration type defined above:
ACTIVE_LOW = bool(0)
FRAME_SIZE = 8
t_State = enum('SEARCH', 'CONFIRM', 'SYNC', encoding="one_hot")
def FramerCtrl(SOF, state, syncFlag, clk, reset_n):
""" Framing control FSM.
SOF -- start-of-frame output bit
state -- FramerState output
syncFlag -- sync pattern found indication input
clk -- clock input
reset_n -- active low reset
"""
index = Signal(intbv(0)[8:]) # position in frame
@always(clk.posedge, reset_n.negedge)
def FSM():
if reset_n == ACTIVE_LOW:
SOF.next = 0
index.next = 0
state.next = t_State.SEARCH
else:
index.next = (index + 1) % FRAME_SIZE
SOF.next = 0
if state == t_State.SEARCH:
index.next = 1
if syncFlag:
state.next = t_State.CONFIRM
elif state == t_State.CONFIRM:
if index == 0:
if syncFlag:
state.next = t_State.SYNC
else:
state.next = t_State.SEARCH
elif state == t_State.SYNC:
if index == 0:
if not syncFlag:
state.next = t_State.SEARCH
SOF.next = (index == FRAME_SIZE-1)
else:
raise ValueError("Undefined state")
return FSM
The conversion is done as before:
SOF = Signal(bool(0))
syncFlag = Signal(bool(0))
clk = Signal(bool(0))
reset_n = Signal(bool(1))
state = Signal(t_State.SEARCH)
toVerilog(FramerCtrl, SOF, state, syncFlag, clk, reset_n)
toVHDL(FramerCtrl, SOF, state, syncFlag, clk, reset_n)
The Verilog output looks as follows:
module FramerCtrl (
SOF,
state,
syncFlag,
clk,
reset_n
);
output SOF;
reg SOF;
output [2:0] state;
reg [2:0] state;
input syncFlag;
input clk;
input reset_n;
reg [7:0] index;
always @(posedge clk, negedge reset_n) begin: FRAMERCTRL_FSM
if ((reset_n == 0)) begin
SOF <= 0;
index <= 0;
state <= 3'b001;
end
else begin
index <= ((index + 1) % 8);
SOF <= 0;
// synthesis parallel_case full_case
casez (state)
3'b??1: begin
index <= 1;
if (syncFlag) begin
state <= 3'b010;
end
end
3'b?1?: begin
if ((index == 0)) begin
if (syncFlag) begin
state <= 3'b100;
end
else begin
state <= 3'b001;
end
end
end
3'b1??: begin
if ((index == 0)) begin
if ((!syncFlag)) begin
state <= 3'b001;
end
end
SOF <= (index == (8 - 1));
end
default: begin
$finish;
end
endcase
end
end
endmodule
The VHDL output looks as follows:
package pck_FramerCtrl is
type t_enum_t_State_1 is (
SEARCH,
CONFIRM,
SYNC
);
attribute enum_encoding of t_enum_t_State_1: type is "001 010 100";
end package pck_FramerCtrl;
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;
use std.textio.all;
use work.pck_myhdl_06.all;
use work.pck_FramerCtrl.all;
entity FramerCtrl is
port (
SOF: out std_logic;
state: inout t_enum_t_State_1;
syncFlag: in std_logic;
clk: in std_logic;
reset_n: in std_logic
);
end entity FramerCtrl;
architecture MyHDL of FramerCtrl is
signal index: unsigned(7 downto 0);
begin
FRAMERCTRL_FSM: process (clk, reset_n) is
begin
if (reset_n = '0') then
SOF <= '0';
index <= "00000000";
state <= SEARCH;
elsif rising_edge(clk) then
index <= ((index + 1) mod 8);
SOF <= '0';
case state is
when SEARCH =>
index <= "00000001";
if to_boolean(syncFlag) then
state <= CONFIRM;
end if;
when CONFIRM =>
if (index = 0) then
if to_boolean(syncFlag) then
state <= SYNC;
else
state <= SEARCH;
end if;
end if;
when SYNC =>
if (index = 0) then
if (not to_boolean(syncFlag)) then
state <= SEARCH;
end if;
end if;
SOF <= to_std_logic(signed(resize(index, 9)) = (8 - 1));
when others =>
assert False report "End of Simulation" severity Failure;
end case;
end if;
end process FRAMERCTRL_FSM;
end architecture MyHDL;
RAM inference
Certain synthesis tools can infer RAM structures. To support this feature, the converter
maps lists of signals in MyHDL to Verilog memories and VHDL arrays.
The following MyHDL example is a ram model that uses a list of signals to model the
internal memory.
def RAM(dout, din, addr, we, clk, depth=128):
""" Ram model """
mem = [Signal(intbv(0)[8:]) for i in range(depth)]
@always(clk.posedge)
def write():
if we:
mem[addr].next = din
@always_comb
def read():
dout.next = mem[addr]
return write, read
With the appropriate signal definitions for the interface ports, it is converted to the
following Verilog code. Note how the list of signals mem is mapped to a Verilog memory.
module ram (
dout,
din,
addr,
we,
clk
);
output [7:0] dout;
wire [7:0] dout;
input [7:0] din;
input [6:0] addr;
input we;
input clk;
reg [7:0] mem [0:128-1];
always @(posedge clk) begin: RAM_1_WRITE
if (we) begin
mem[addr] <= din;
end
end
assign dout = mem[addr];
endmodule
In VHDL, the list of MyHDL signals is modeled as a VHDL array signal:
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;
use work.pck_myhdl_06.all;
entity ram is
port (
dout: out unsigned(7 downto 0);
din: in unsigned(7 downto 0);
addr: in unsigned(6 downto 0);
we: in std_logic;
clk: in std_logic
);
end entity ram;
architecture MyHDL of ram is
type t_array_mem is array(0 to 128-1) of unsigned(7 downto 0);
signal mem: t_array_mem;
begin
RAM_WRITE: process (clk) is
begin
if rising_edge(clk) then
if to_boolean(we) then
mem(to_integer(addr)) <= din;
end if;
end if;
end process RAM_WRITE;
dout <= mem(to_integer(addr));
end architecture MyHDL;
ROM inference
Some synthesis tools can infer a ROM memory from a case statement. The Verilog converter
can perform the expansion into a case statement automatically, based on a higher level
description. The ROM access is described in a single line, by indexing into a tuple of
integers. The tuple can be described manually, but also by programmatical means. Note that
a tuple is used instead of a list to stress the read-only character of the memory.
The following example illustrates this functionality. ROM access is described as follows:
def rom(dout, addr, CONTENT):
@always_comb
def read():
dout.next = CONTENT[int(addr)]
return read
The ROM content is described as a tuple of integers. When the ROM content is defined, the
conversion can be performed:
CONTENT = (17, 134, 52, 9)
dout = Signal(intbv(0)[8:])
addr = Signal(intbv(0)[4:])
toVerilog(rom, dout, addr, CONTENT)
toVHDL(rom, dout, addr, CONTENT)
The Verilog output code is as follows:
module rom (
dout,
addr
);
output [7:0] dout;
reg [7:0] dout;
input [3:0] addr;
always @(addr) begin: ROM_READ
// synthesis parallel_case full_case
case (addr)
0: dout <= 17;
1: dout <= 134;
2: dout <= 52;
default: dout <= 9;
endcase
end
endmodule
The VHDL output code is as follows:
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;
use std.textio.all;
use work.pck_myhdl_06.all;
entity rom is
port (
dout: out unsigned(7 downto 0);
addr: in unsigned(3 downto 0)
);
end entity rom;
architecture MyHDL of rom is
begin
ROM_READ: process (addr) is
begin
case to_integer(addr) is
when 0 => dout <= "00010001";
when 1 => dout <= "10000110";
when 2 => dout <= "00110100";
when others => dout <= "00001001";
end case;
end process ROM_READ;
end architecture MyHDL;
User-defined code
MyHDL provides a way to include user-defined code during the conversion process, using the
special function attributes vhdl_code and verilog_code.
For example:
def inc_comb(nextCount, count, n):
@always(count)
def logic():
# do nothing here
pass
nextCount.driven = "wire"
return logic
inc_comb.verilog_code =\
"""
assign $nextCount = ($count + 1) % $n;
"""
inc_comb.vhdl_code =\
"""
$nextCount <= ($count + 1) mod $n;
"""
The converted code looks as follows in Verilog:
module inc_comb (
nextCount,
count
);
output [7:0] nextCount;
wire [7:0] nextCount;
input [7:0] count;
assign nextCount = (count + 1) % 256;
endmodule
and as follows in VHDL:
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;
use work.pck_myhdl_06.all;
entity inc_comb is
port (
nextCount: out unsigned(7 downto 0);
count: in unsigned(7 downto 0)
);
end entity inc_comb;
architecture MyHDL of inc_comb is
begin
nextCount <= (count + 1) mod 256;
end architecture MyHDL;
In this example, conversion of the inc_comb function is bypassed and the user-defined code
is inserted instead. The user-defined code is a Python template string that can refer to
signals and parameters in the MyHDL context through $-based substitutions. During
conversion, the appropriate hierarchical names and parameter values will be substituted.
The MyHDL code contains the following assignment:
nextCount.driven = "wire"
This specifies that the nextCount signal is driven as a Verilog wire from this module.
For more info about user-defined code, see conv-custom.
Reference
MyHDL is implemented as a Python package called myhdl. This chapter describes the objects
that are exported by this package.
Simulation
The Simulation class
class Simulation(arg[, arg ...])
Class to construct a new simulation. Each argument should be a MyHDL instance. In
MyHDL, an instance is recursively defined as being either a sequence of instances,
or a MyHDL generator, or a Cosimulation object. See section MyHDL generators and
trigger objects for the definition of MyHDL generators and their interaction with a
Simulation object. See Section Co-simulation for the Cosimulation object. At most
one Cosimulation object can be passed to a Simulation constructor.
A Simulation object has the following method:
Simulation.run([duration])
Run the simulation forever (by default) or for a specified duration.
Simulation.quit()
Quit the simulation after it has run for a specified duration. The method should be
called (the simulation instance must be quit) before another simulation instance is
created. The method is called by default when the simulation is run forever.
Simulation support functions
now() Returns the current simulation time.
exception StopSimulation
Base exception that is caught by the Simulation.run() method to stop a simulation.
Waveform tracing
traceSignals(func [, *args] [, **kwargs])
Enables signal tracing to a VCD file for waveform viewing. func is a function that
returns an instance. traceSignals calls func under its control and passes *args and
**kwargs to the call. In this way, it finds the hierarchy and the signals to be
traced.
The return value is the same as would be returned by the call func(*args,
**kwargs). The top-level instance name and the basename of the VCD output filename
is func.func_name by default. If the VCD file exists already, it will be moved to a
backup file by attaching a timestamp to it, before creating the new file.
The traceSignals callable has the following attribute:
name This attribute is used to overwrite the default top-level instance name and
the basename of the VCD output filename.
directory
This attribute is used to set the directory to which VCD files are written.
By default, the current working directory is used.
filename
This attribute is used to set the filename to which VCD files are written.
By default, the name attribbute is used.
timescale
This attribute is used to set the timescale corresponding to unit steps,
according to the VCD format. The assigned value should be a string. The
default timescale is "1ns".
Modeling
The block decorator
block()
The block decorator enables a method-based API which is more consistent, simplifies
implementation, and reduces the size of the myhdl namespace.
The methods work on block instances, created by calling a function decorated with
the block decorator:
@block
def myblock(<ports>):
...
return <instances>
inst = myblock(<port-associations>)
# inst supports the methods of the block instance API
The API on a block instance looks as follows:
<block_instance>.run_sim(duration=None)
Run a simulation "forever" (default) or for a specified duration.
<block_instance>.config_sim(backend='myhdl', trace=False)
Optional simulation configuration:
backend: Defaults to 'myhdl
trace: Enable waveform tracing, default False.
<block_instance>.quit_sim()
Quit an active simulation. This is method is currently required because only a
single simulation can be active.
<block_instance>.convert(hdl='Verilog', **kwargs)
Converts MyHDL code to a target HDL.
hdl: 'VHDL' or 'Verilog'. Defaults to Verilog.
Supported keyword arguments:
path: Destination folder. Defaults to current working dir.
name: Module and output file name. Defaults to self.mod.__name__.
trace: Whether the testbench should dump all signal waveforms. Defaults to False.
testbench: Verilog only. Specifies whether a testbench should be created. Defaults
to True.
timescale: timescale parameter. Defaults to '1ns/10ps'. Verilog only.
<block_instance>.verify_convert()
Verify conversion output, by comparing target HDL simulation log with MyHDL
simulation log.
<block_instance>.analyze_convert()
Analyze conversion output by compilation with target HDL compiler.
Signals
The SignalType type
class SignalType
This type is the abstract base type of all signals. It is not used to construct
signals, but it can be used to check whether an object is a signal.
Regular signals
class Signal([val=None] [, delay=0])
This class is used to construct a new signal and to initialize its value to val.
Optionally, a delay can be specified.
A Signal object has the following attributes:
posedge
Attribute that represents the positive edge of a signal, to be used in
sensitivity lists.
negedge
Attribute that represents the negative edge of a signal, to be used in
sensitivity lists.
next Read-write attribute that represents the next value of the signal.
val Read-only attribute that represents the current value of the signal.
This attribute is always available to access the current value; however
in many practical case it will not be needed. Whenever there is no
ambiguity, the Signal object's current value is used implicitly. In
particular, all Python's standard numeric, bit-wise, logical and
comparison operators are implemented on a Signal object by delegating to
its current value. The exception is augmented assignment. These operators
are not implemented as they would break the rule that the current value
should be a read-only attribute. In addition, when a Signal object is
assigned to the next attribute of another Signal object, its current
value is assigned instead.
min Read-only attribute that is the minimum value (inclusive) of a numeric
signal, or None for no minimum.
max Read-only attribute that is the maximum value (exclusive) of a numeric
signal, or None for no maximum.
driven Writable attribute that can be used to indicate that the signal is
supposed to be driven from the MyHDL code, and possibly how it should be
declared in Verilog after conversion. The allowed values are 'reg',
'wire', True and False.
This attribute is useful when the converter cannot infer automatically
whether and how a signal is driven. This occurs when the signal is driven
from user-defined code. 'reg' and 'wire' are "true" values that permit
finer control for the Verilog case.
read Writable boolean attribute that can be used to indicate that the signal
is read.
This attribute is useful when the converter cannot infer automatically
whether a signal is read. This occurs when the signal is read from
user-defined code.
A Signal object also has a call interface:
__call__(left[, right=None])
This method returns a _SliceSignal shadow signal.
class ResetSignal(val, active, isasync)
This Signal subclass defines reset signals. val, active, and isasync are mandatory
arguments. val is a boolean value that specifies the initial value, active is a
boolean value that specifies the active level. isasync is a boolean value that
specifies the reset style: asynchronous (True) or synchronous (False).
This class should be used in conjunction with the always_seq decorator.
Shadow signals
class _SliceSignal(sig, left[, right=None])
This class implements read-only structural slicing and indexing. It creates a new
shadow signal of the slice or index of the parent signal sig. If the right
parameter is omitted, you get indexing instead of slicing. Parameters left and
right have the usual meaning for slice indices: in particular, left is
non-inclusive but right is inclusive. sig should be appropriate for slicing and
indexing, which means it should be based on intbv in practice.
The class constructor is not intended to be used explicitly. Instead, use the call
interface of a regular signal.The following calls are equivalent:
sl = _SliceSignal(sig, left, right)
sl = sig(left, right)
class ConcatSignal(*args)
This class creates a new shadow signal of the concatenation of its arguments.
You can pass an arbitrary number of arguments to the constructor. The arguments
should be bit-oriented with a defined number of bits. The following argument types
are supported: intbv objects with a defined bit width, bool objects, signals of the
previous objects, and bit strings.
The new signal follows the value changes of the signal arguments. The non-signal
arguments are used to define constant values in the concatenation.
class TristateSignal(val)
This class is used to construct a new tristate signal. The underlying type is
specified by the val parameter. It is a Signal subclass and has the usual
attributes, with one exception: it doesn't support the next attribute.
Consequently, direct signal assignment to a tristate signal is not supported. The
initial value is the tristate value None. The current value of a tristate is
determined by resolving the values from its drivers. When exactly one driver value
is different from None, that is the resolved value; otherwise it is None. When more
than one driver value is different from None, a contention warning is issued.
This class has the following method:
driver()
Returns a new driver to the tristate signal. It is initialized to None. A
driver object is an instance of a special SignalType subclass. In
particular, its next attribute can be used to assign a new value to it.
MyHDL generators and trigger objects
MyHDL generators are standard Python generators with specialized yield statements. In
hardware description languages, the equivalent statements are called sensitivity lists.
The general format of yield statements in in MyHDL generators is:
yield clause [, clause ...]
When a generator executes a yield statement, its execution is suspended at that point. At
the same time, each clause is a trigger object which defines the condition upon which the
generator should be resumed. However, per invocation of a yield statement, the generator
resumes exactly once, regardless of the number of clauses. This happens on the first
trigger that occurs.
In this section, the trigger objects and their functionality will be described.
Some MyHDL objects that are described elsewhere can directly be used as trigger objects.
In particular, a Signal can be used as a trigger object. Whenever a signal changes value,
the generator resumes. Likewise, the objects referred to by the signal attributes posedge
and negedge are trigger objects. The generator resumes on the occurrence of a positive or
a negative edge on the signal, respectively. An edge occurs when there is a change from
false to true (positive) or vice versa (negative). For the full description of the Signal
class and its attributes, see section Signals.
Furthermore, MyHDL generators can be used as clauses in yield statements. Such a
generator is forked, and starts operating immediately, while the original generator waits
for it to complete. The original generator resumes when the forked generator returns.
In addition, the following functions return trigger objects:
delay(t)
Return a trigger object that specifies that the generator should resume after a
delay t.
join(arg[, arg ...])
Join a number of trigger objects together and return a joined trigger object. The
effect is that the joined trigger object will trigger when all of its arguments
have triggered.
Finally, as a special case, the Python None object can be present in a yield statement. It
is the do-nothing trigger object. The generator immediately resumes, as if no yield
statement were present. This can be useful if the yield statement also has generator
clauses: those generators are forked, while the original generator resumes immediately.
Decorator functions to create generators
MyHDL defines a number of decorator functions, that make it easier to create generators
from local generator functions.
instance()
The instance decorator is the most general decorator. It automatically creates a
generator by calling the decorated generator function.
It is used as follows:
def top(...):
...
@instance
def inst():
<generator body>
...
return inst, ...
This is equivalent to:
def top(...):
...
def _gen_func():
<generator body>
...
inst = _gen_func()
...
return inst, ...
always(arg[, *args])
The always decorator is a specialized decorator that targets a widely used coding
pattern. It is used as follows:
def top(...):
...
@always(event1, event2, ...)
def inst()
<body>
...
return inst, ...
This is equivalent to the following:
def top(...):
...
def _func():
<body>
def _gen_func()
while True:
yield event1, event2, ...
_func()
...
inst = _gen_func()
...
return inst, ...
The argument list of the decorator corresponds to the sensitivity list. Only
signals, edge specifiers, or delay objects are allowed. The decorated function
should be a classic function.
always_comb()
The always_comb decorator is used to describe combinatorial logic.
def top(...):
...
@always_comb
def comb_inst():
<combinatorial body>
...
return comb_inst, ...
The always_comb decorator infers the inputs of the combinatorial logic and the
corresponding sensitivity list automatically. The decorated function should be a
classic function.
always_seq(edge, reset)
The always_seq decorator is used to describe sequential (clocked) logic.
The edge parameter should be a clock edge (clock.posedge or clock.negedge). The
reset parameter should a ResetSignal object.
MyHDL data types
MyHDL defines a number of data types that are useful for hardware description.
The intbv class
class intbv([val=0] [, min=None] [, max=None])
This class represents int-like objects with some additional features that make it
suitable for hardware design.
The val argument can be an int, a long, an intbv or a bit string (a string with
only '0's or '1's). For a bit string argument, the value is calculated as in
int(bitstring, 2). The optional min and max arguments can be used to specify the
minimum and maximum value of the intbv object. As in standard Python practice for
ranges, the minimum value is inclusive and the maximum value is exclusive.
The minimum and maximum values of an intbv object are available as attributes:
min Read-only attribute that is the minimum value (inclusive) of an intbv, or
None for no minimum.
max Read-only attribute that is the maximum value (exclusive) of an intbv, or
None for no maximum.
signed()
Interprets the msb bit as as sign bit and extends it into the higher-order
bits of the underlying object value. The msb bit is the highest-order bit
within the object's bit width.
Return type
integer
Unlike int objects, intbv objects are mutable; this is also the reason for their
existence. Mutability is needed to support assignment to indexes and slices, as is common
in hardware design. For the same reason, intbv is not a subclass from int, even though int
provides most of the desired functionality. (It is not possible to derive a mutable
subtype from an immutable base type.)
An intbv object supports the same comparison, numeric, bitwise, logical, and conversion
operations as int objects. See http://www.python.org/doc/current/lib/typesnumeric.html for
more information on such operations. In all binary operations, intbv objects can work
together with int objects. For mixed-type numeric operations, the result type is an int or
a long. For mixed-type bitwise operations, the result type is an intbv.
In addition, intbv supports a number of sequence operators. In particular, the len
function returns the object's bit width. Furthermore, intbv objects support indexing and
slicing operations:
┌────────────┬──────────────────────────┬────────┐
│Operation │ Result │ Notes │
├────────────┼──────────────────────────┼────────┤
│bv[i] │ item i of bv │ (1) │
├────────────┼──────────────────────────┼────────┤
│bv[i] = x │ item i of bv is replaced │ (1) │
│ │ by x │ │
├────────────┼──────────────────────────┼────────┤
│bv[i:j] │ slice of bv from i │ (2)(3) │
│ │ downto j │ │
├────────────┼──────────────────────────┼────────┤
│bv[i:j] = t │ slice of bv from i │ (2)(4) │
│ │ downto j is replaced by │ │
│ │ t │ │
└────────────┴──────────────────────────┴────────┘
1. Indexing follows the most common hardware design conventions: the lsb bit is the
rightmost bit, and it has index 0. This has the following desirable property: if the
intbv value is decomposed as a sum of powers of 2, the bit with index i corresponds to
the term 2**i.
2. In contrast to standard Python sequencing conventions, slicing range are downward. This
is a consequence of the indexing convention, combined with the common convention that
the most significant digits of a number are the leftmost ones. The Python convention of
half-open ranges is followed: the bit with the highest index is not included. However,
it is the leftmost bit in this case. As in standard Python, this takes care of one-off
issues in many practical cases: in particular, bv[i:] returns i bits; bv[i:j] has i-j
bits. When the low index j is omitted, it defaults to 0. When the high index i is
omitted, it means "all" higher order bits.
3. The object returned from a slicing access operation is always a positive intbv; higher
order bits are implicitly assumed to be zero. The bit width is implicitly stored in the
return object, so that it can be used in concatenations and as an iterator. In
addition, for a bit width w, the min and max attributes are implicitly set to 0 and
2**w, respectively.
4. When setting a slice to a value, it is checked whether the slice is wide enough.
In addition, an intbv object supports the iterator protocol. This makes it possible to
iterate over all its bits, from the high index to index 0. This is only possible for intbv
objects with a defined bit width.
The modbv class
class modbv([val=0] [, min=None] [, max=None])
The modbv class implements modular bit vector types.
It is implemented as a subclass of intbv and supports the same parameters and
operators. The difference is in the handling of the min and max boundaries.
Instead of throwing an exception when those constraints are exceeded, the value of
modbv objects wraps around according to the following formula:
val = (val - min) % (max - min) + min
This formula is a generalization of modulo wrap-around behavior that is often
useful when describing hardware system behavior.
The enum factory function
enum(arg [, arg ...] [, encoding='binary'])
Returns an enumeration type.
The arguments should be string literals that represent the desired names of the
enumeration type attributes. The returned type should be assigned to a type name.
For example:
t_EnumType = enum('ATTR_NAME_1', 'ATTR_NAME_2', ...)
The enumeration type identifiers are available as attributes of the type name, for
example: t_EnumType.ATTR_NAME_1
The optional keyword argument encoding specifies the encoding scheme used in
Verilog output. The available encodings are 'binary', 'one_hot', and 'one_cold'.
Modeling support functions
MyHDL defines a number of additional support functions that are useful for hardware
description.
bin
bin(num[, width])
Returns a bit string representation. If the optional width is provided, and if it
is larger than the width of the default representation, the bit string is padded
with the sign bit.
This function complements the standard Python conversion functions hex and oct. A
binary string representation is often useful in hardware design.
Return type
string
concat
concat(base[, arg ...])
Returns an intbv object formed by concatenating the arguments.
The following argument types are supported: intbv objects with a defined bit width,
bool objects, signals of the previous objects, and bit strings. All these objects
have a defined bit width.
The first argument base is special as it does not need to have a defined bit width.
In addition to the previously mentioned objects, unsized intbv, int and long
objects are supported, as well as signals of such objects.
Return type
intbv
downrange
downrange(high[, low=0])
Generates a downward range list of integers.
This function is modeled after the standard range function, but works in the
downward direction. The returned interval is half-open, with the high index not
included. low is optional and defaults to zero. This function is especially useful
in conjunction with the intbv class, that also works with downward indexing.
instances
instances()
Looks up all MyHDL instances in the local name space and returns them in a list.
Return type
list
Co-simulation
MyHDL
class Cosimulation(exe, **kwargs)
Class to construct a new Cosimulation object.
The exe argument is the command to execute an HDL simulation, which can be either a
string of the entire command line or a list of strings. In the latter case, the
first element is the executable, and subsequent elements are program arguments.
Providing a list of arguments allows Python to correctly handle spaces or other
characters in program arguments.
The kwargs keyword arguments provide a named association between signals (regs &
nets) in the HDL simulator and signals in the MyHDL simulator. Each keyword should
be a name listed in a $to_myhdl or $from_myhdl call in the HDL code. Each argument
should be a Signal declared in the MyHDL code.
Verilog
$to_myhdl(arg, [, arg ...])
Task that defines which signals (regs & nets) should be read by the MyHDL
simulator. This task should be called at the start of the simulation.
$from_myhdl(arg, [, arg ...])
Task that defines which signals should be driven by the MyHDL simulator. In
Verilog, only regs can be specified. This task should be called at the start of the
simulation.
Conversion to Verilog and VHDL
Conversion
toVerilog(func [, *args] [, **kwargs])
Converts a MyHDL design instance to equivalent Verilog code, and also generates
a test bench to verify it. func is a function that returns an instance.
toVerilog calls func under its control and passes *args and **kwargs to the
call.
The return value is the same as would be returned by the call func(*args,
**kwargs). It should be assigned to an instance name.
The top-level instance name and the basename of the Verilog output filename is
func.func_name by default.
For more information about the restrictions on convertible MyHDL code, see
section conv-subset in Chapter conv.
toVerilog has the following attribute:
name This attribute is used to overwrite the default top-level instance name and
the basename of the Verilog output filename.
directory
This attribute is used to set the directory to which converted verilog files
are written. By default, the current working directory is used.
timescale
This attribute is used to set the timescale in Verilog format. The assigned
value should be a string. The default timescale is "1ns/10ps".
toVHDL(func[, *args][, **kwargs])
Converts a MyHDL design instance to equivalent VHDL code. func is a function that
returns an instance. toVHDL calls func under its control and passes *args and
**kwargs to the call.
The return value is the same as would be returned by the call func(*args,
**kwargs). It can be assigned to an instance name. The top-level instance name and
the basename of the Verilog output filename is func.func_name by default.
toVHDL has the following attributes:
name This attribute is used to overwrite the default top-level instance name and
the basename of the VHDL output.
directory
This attribute is used to set the directory to which converted VHDL files
are written. By default, the current working directory is used.
component_declarations
This attribute can be used to add component declarations to the VHDL output.
When a string is assigned to it, it will be copied to the appropriate place
in the output file.
library
This attribute can be used to set the library in the VHDL output file. The
assigned value should be a string. The default library is work.
std_logic_ports
This boolean attribute can be used to have only std_logic type ports on the
top-level interface (when True) instead of the default signed/unsigned types
(when False, the default).
User-defined Verilog and VHDL code
User-defined code can be inserted in the Verilog or VHDL output through the use of
function attributes. Suppose a function <func> defines a hardware module. User-defined
code can be specified for the function with the following function attributes:
<func>.vhdl_code
A template string for user-defined code in the VHDL output.
<func>.verilog_code
A template string for user-defined code in the Verilog output.
When such a function attribute is defined, the normal conversion process is bypassed and
the user-defined code is inserted instead. The template strings should be suitable for
the standard string.Template constructor. They can contain interpolation variables
(indicated by a $ prefix) for all signals in the context. Note that the function attribute
can be defined anywhere where <func> is visible, either outside or inside the function
itself.
These function attributes cannot be used with generator functions or decorated local
functions, as these are not elaborated before simulation or conversion. In other words,
they can only be used with functions that define structure.
Conversion output verification
MyHDL provides an interface to verify converted designs. This is used extensively in the
package itself to verify the conversion functionality. This capability is exported by the
package so that users can use it also.
Verification interface
All functions related to conversion verification are implemented in the myhdl.conversion
package.
verify(func[, *args][, **kwargs])
Used like toVHDL and toVerilog. It converts MyHDL code, simulates both the MyHDL
code and the HDL code and reports any differences. The default HDL simulator is
GHDL.
This function has the following attribute:
simulator
Used to set the name of the HDL simulator. "GHDL" is the default.
analyze(func[, *args][, **kwargs])
Used like toVHDL and toVerilog. It converts MyHDL code, and analyzes the resulting
HDL. Used to verify whether the HDL output is syntactically correct.
This function has the following attribute:
simulator
Used to set the name of the HDL simulator used to analyze the code. "GHDL"
is the default.
HDL simulator registration
To use a HDL simulator to verify conversions, it needs to be registered first. This is
needed once per simulator.
A number of HDL simulators are preregistered in the MyHDL distribution, as follows:
┌───────────┬──────────────────────────────┐
│Identifier │ Simulator │
├───────────┼──────────────────────────────┤
│"GHDL" │ The GHDL VHDL simulator │
├───────────┼──────────────────────────────┤
│"vsim" │ The ModelSim VHDL simulator │
├───────────┼──────────────────────────────┤
│"icarus" │ The Icarus Verilog simulator │
├───────────┼──────────────────────────────┤
│"cver" │ The cver Verilog simulator │
└───────────┴──────────────────────────────┘
│"vlog" │ The Modelsim VHDL simulator │
└───────────┴──────────────────────────────┘
Of course, a simulator has to be installed before it can be used.
If another simulator is required, it has to be registered by the user. This is done with
the function registerSimulation that lives in the module myhdl.conversion._verify. The
same module also has the registrations for the predefined simulators.
The verification functions work by comparing the HDL simulator output with the MyHDL
simulator output. Therefore, they have to deal with the specific details of each HDL
simulator output, which may be somewhat tricky. This is reflected in the interface of the
registerSimulation function. As registration is rarely needed, this interface is not
further described here.
Please refer to the source code in myhdl.conversion._verify to learn how registration
works. If you need help, please contact the MyHDL community.
WHAT'S NEW IN MYHDL 0.11
The isasync arguments
The async argument has been replaced with isasync to avoid the Python 3.7 keyword
conflict.
PYTHON 3 SUPPORT
MyHDL supports Python 3.4 and above. At the moment, core functions, cosimulation and
Verilog conversion work perfectly. However, there are a few unresolved VHDL conversion
bugs.
All users are encouraged to try out their existing projects and tests with Python 3 and
submit bug reports if anything goes wrong.
WHAT'S NEW IN MYHDL 0.10
The block decorator
Rationale
The historical approach for hierarchy extraction in MyHDL suffers from significant issues.
This results in complex code, a number of non-intuitive API concepts, and difficulties for
future development.
In this release, a new block decorator is introduced to address these issues.
For an in-depth discussion, see mep-114.
API
block() :noindex:
The block decorator enables a method-based API which is more consistent, simplifies
implementation, and reduces the size of the myhdl namespace.
The methods work on block instances, created by calling a function decorated with
the block decorator:
@block
def myblock(<ports>):
...
return <instances>
inst = myblock(<port-associations>)
# inst supports the methods of the block instance API
The API on a block instance looks as follows:
<block_instance>.run_sim(duration=None)
Run a simulation "forever" (default) or for a specified duration.
<block_instance>.config_sim(backend='myhdl', trace=False)
Optional simulation configuration:
backend: Defaults to 'myhdl
trace: Enable waveform tracing, default False.
<block_instance>.quit_sim()
Quit an active simulation. This is method is currently required because only a
single simulation can be active.
<block_instance>.convert(hdl='Verilog', **kwargs)
Converts MyHDL code to a target HDL.
hdl: 'VHDL' or 'Verilog'. Defaults to Verilog.
Supported keyword arguments:
path: Destination folder. Defaults to current working dir.
name: Module and output file name. Defaults to self.mod.__name__.
trace: Whether the testbench should dump all signal waveforms. Defaults to False.
testbench: Verilog only. Specifies whether a testbench should be created. Defaults
to True.
timescale: timescale parameter. Defaults to '1ns/10ps'. Verilog only.
<block_instance>.verify_convert()
Verify conversion output, by comparing target HDL simulation log with MyHDL
simulation log.
<block_instance>.analyze_convert()
Analyze conversion output by compilation with target HDL compiler.
Backwards compatibility issues
In the 0.10 release, the old API still available next to the new API based on the block
decorator.
It is likely that the old deprecated API will be removed in a future release, resulting in
backwards incompatibility for legacy code. Therefore, users are encouraged to start using
the new API in their development methodology.
WHAT'S NEW IN MYHDL 0.9
Python 3 support
Experimental Python 3 support has been added to MyHDL 0.9. This was a major effort to
modernize the code. As a result, Python 2 and 3 are supported from a single codebase.
See /python3 for more info.
Interfaces (Conversion of attribute accesses)
Rationale
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 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:
class Complex:
def __init__(self, min=-2, max=2):
self.real = Signal(intbv(0, min=min, max=max))
self.imag = Signal(intbv(0, min=min, max=max))
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:
a,b = Complex(-8,8), Complex(-8,8)
c = Complex(-128,128)
def complex_multiply(clock, reset, a, b, c):
@always_seq(clock.posedge, reset=reset)
def cmult():
c.real.next = (a.real*b.real) - (a.imag*b.imag)
c.imag.next = (a.real*b.imag) + (a.imag*b.real)
return cmult
Solution
The proposed solution is to create unique names for attributes which are used by MyHDL
generators. 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 converter supports interfaces, even though the target HDLs do not.
This is another great example where the converter supports a high-level feature that is
not available in the target HDLs.
See also
For additional information see the original proposal mep-107.
Other noteworthy improvements
ConcatSignal interface
The interface of ConcatSignal was enhanced. In addition to signals, you can now also use
constant values in the concatenation.
std_logic type ports
toVHDL has a new attribute std_logic_ports. When set, only std_logic type ports are used
in the interface of the top-level VHDL module.
Development flow
The MyHDL development flow has been modernized by moving to git and github for version
control. In addition, travis has set up so that all pull requests are tested
automatically, enabling continuous intergration.
Acknowledgments
The Python 3 support effort was coordinated by Keerthan Jaic, who also implemented most of
if. Convertible interfaces were championed by Chris Felton, and implemented by Keerthan
Jaic.
MyHDL development is a collaborative effort, as can be seen on github. Thanks to all who
contributed with suggestions, issues and pull requests.
WHAT'S NEW IN MYHDL 0.8
Modular bit vector types
Rationale
In hardware modeling, there is often a need for the elegant modeling of wrap-around
behavior. intbv instances don't provide this automatically, because they assert that any
assigned value is within the bound constraints. Therefore, one has currently has to use
other language features for wrap-around modeling.
Often, this is straightforward. For example, the wrap-around condition for a counter is
often decoded explicitly, as it is needed for other purposes. Also, the modulo operator
provides an elegant one-liner in most scenarios.
However, in some important cases the current solution is not satisfactory. For example, we
would like to describe a free running counter using a variable and augmented assignment as
follows:
count += 1
This is not possible with the intbv type, as we cannot add the modulo behavior to this
description. A similar problem exist of for a left shift as follows:
shifter <<= 4
These operations can only supported directly with a new type. For these reasons, it was
felt that this would be a useful addition to MyHDL.
Solution
The proposed solution is to borrow the idea behind Ada modular types. These are natural
integer types with wrap-around behaviour.
The wrap-around behavior of modular types is based on the sound mathematical concept of
modulo arithmetic. Therefore, the modulus is not limited to powers of 2.
Ada's modular type is called mod. In MyHDL, we want also want to give it "bit-vector"
support, like intbv. Therefore, proposed MyHDL type is called modbv.
Implementation
modbv is implemented as a subclass of intbv. The two classes have an identical interface
and work together in a straightforward way for arithmetic operations.
The only difference is how the bounds are handled: out-of-bound values result in an error
with intbv, and in wrap-around with modbv. The Wrap-around behavior would be defined as
follows, with val denoting the current value and min/max the bounds:
val = (val - min) % (max - min) + min
Interface
class modbv([val=0] [, min=None] [, max=None])
The modbv class implements modular bit vector types.
It is implemented as a subclass of intbv and supports the same parameters and
operators. The difference is in the handling of the min and max boundaries.
Instead of throwing an exception when those constraints are exceeded, the value of
modbv objects wraps around according to the following formula:
val = (val - min) % (max - min) + min
This formula is a generalization of modulo wrap-around behavior that is often
useful when describing hardware system behavior.
Conversion
Full-range modbv objects are those where the max bound is a power of 2, and the min bound
is 0 or the negative of the max bound. For these objects, conversion worked
out-of-the-box because this corresponds to the target types in Verilog and VHDL.
Currently, conversion is restricted to full-range modbv objects. It may be possible to
support conversion of the modulo behavior of more general cases, but this requires more
sophistication in the converter. This may be considered in the future.
See also
For a more in-depth discussion, see mep-106.
always_seq decorator
Rationale
In classical synthesizable RTL coding, the reset behavior is described explicitly. A
typical template is as follows:
@always(clock.posedge, reset.negedge)
def seq():
if reset == 0:
<reset code>
else:
<functional code>
The reset behavior is described using a the top-level if-else structure with a number of
assignments under the if. A significant piece of code at a prominent location is therefore
dedicated to non-functional behavior.
Reset behavior coding is error-prone. For a proper gate-level implementation, most if not
all registers should typically be reset. However, it is easy to forget some reset
assignments. Such bugs are not necessarily easily detected during RTL or gate-level
simulations.
In the template, the edge that asserts reset is in the sensitivity list. It is easy to
forget this, and in that case the reset will not behave asynchronously as intended but
synchronously. Note also that it is somewhat strange to specify an edge sensitivity when
describing asynchronous behavior.
Solution
The proposed solution is to infer the reset structure automatically. The main idea is to
use the initial values of signals as the specification of reset values. This is possible
in MyHDL, because all objects are constructed with an initial value. The assumption is
that the initial value also specifies the desired reset value.
The solution is implemented with two new MyHDL constructs. The first one is a new
decorator called always_seq. Using this decorator, code with identical behavior as in the
previous section can be described as follows:
@always_seq(clock.posedge, reset=reset)
<functional code>
The always_seq decorator takes two arguments: a clock edge and a reset signal. It inspects
the code to find the registers, and uses the initial values to construct the reset
behavior.
The second construct is a specialized signal subclass called ResetSignal. It is used as
follows:
reset = ResetSignal(1, active=0, async=True)
The ResetSignal constructor has three arguments: the initial value as usual, an active
argument with the active level, and an async argument that specifies whether the reset
style is asynchronous or synchronous.
The proposed solution has some very desirable features.
Explicit reset behavior coding is no longer necessary. Code reviewers are thus no longer
distracted by non-functional code. It is sufficient to check the initial values to verify
whether the reset value is correctly specified. Moreover, one indentation level is saved
for functional coding.
Even more importantly, the reset structure is correct by construction. All registers are
automatically included in the reset behavior, and the sensitivity list is automatically
correct according to the reset style.
Traditionally, the reset behavior is spread out over all sequential processes. Therefore,
it has to be debugged by investigating all those processes. Even worse, if a change in
style or active level is required, all processes are affected. In contrast, with the
proposed technique all reset features are specified at single location in the ResetSignal
constructor. Changes are trivial. For example, to change to an active high synchronous
reset one merely has to change the constructor as follows:
reset = ResetSignal(1, active=1, async=False)
Occasionally, it is useful to have registers without reset at all. The proposed technique
is also useful in that case. In particular, the always_seq decorator accepts None as the
reset argument:
@always_seq(clock.posedge, reset=None)
A reviewer will have no doubt what the intention is. In contrast, in the case of a
traditional always block, the reviewer may think that the designer has delayed the
detailed reset coding for later and then forgotten about it.
Interface
always_seq(edge, reset)
The always_seq decorator is used to describe sequential (clocked) logic.
The edge parameter should be a clock edge (clock.posedge or clock.negedge). The
reset parameter should a ResetSignal object.
class ResetSignal(val, active, async)
This Signal subclass defines reset signals. val, active, and async are mandatory
arguments. val is a boolean value that specifies the initial value, active is a
boolean value that specifies the active level. async is a boolean value that
specifies the reset style: asynchronous (True) or asynchronous (False).
Conversion
As modeling the reset behavior is a typical task in synthesizable RTL coding, the proposed
technique is fully convertible to Verilog and VHDL.
Limitations
All registers in a process are reset
All registers in a process are automatically included in the reset behavior. If it is the
intention that some registers should not be reset, those registers and the corresponding
code should be factored out in a separate process.
Actually, this is not really a limitation but a feature. If some registers in a process
are reset and others not, a synthesis tool may generate undesirable feedback loops that
are active during the reset condition. This is not good practice and probably not the
intention.
Register inferencing from variables is not supported
An important limitation is that the proposed technique is limited to registers inferred
from signals. Registers inferred from variables are not supported, because such state
variables cannot be described in classic functions (in particular the functions required
by MyHDL decorators such as always_seq and always).
In fact, the reason is a Python2 limitation. Currently, to infer registers from variables,
one has to use the instance decorator and declare the state variables outside an infinite
while True loop.
In Python3, this limitation can be lifted with the introduction of the nonlocal
declaration. This will make it possible for functions to modify variables in the enclosing
scope. It should be possible to adapt the always_seq and always decorators to support such
variables.
See also
For a more in-depth discussion, see mep-109.
Other improvements
Conversion of top-level class methods
Often it is desirable to embed an HDL module description in a class. Previous versions
would only convert a class method if it was not the top-level. This release adds the
conversion of top-level class methods.
Example
class DFilter(object):
def __init__(self,delay_length=3,fs=1):
<init code>
def nulls(self):
<support method code>
def m_top(self,clock,reset,x,y):
<myhdl module code>
clock = Signal(bool(0))
reset = ResetSignal(0,active=0,async=True)
x = Signal(intbv(0, min=-8, max=8))
y = Signal(intbv(0, min=-64, max=64))
filt = DFilter()
toVerilog(filt.m_top,clock,reset,x,y)
toVHDL(filt.m_top,clock,reset,x,y)
See also
For a more in-depth discussion, see mep-108.
Tracing lists of signals
Tracing lists of signals is now supported. Contributed by Frederik Teichtert,
http://teichert-ing.de . The following shows how the list of signals are displayed in a
waveform viewer
delay_taps = [Signal(intbv(0,min=-8,max=8)) for ii in range(3)]
[image]
library attribute for toVHDL
toVHDL now has a library function that can be used to set the library name in the VHDL
output. The assigned value should be a string. The default library is "work".
timescale attribute for traceSignals
traceSignals now has a timescale attribute that can be used to set the timescale in the
VCD output. The assigned value should be a string. The default timescale is "1ns".
Acknowledgments
Several people have contributed to MyHDL 0.8 by giving feedback, making suggestions,
fixing bugs and implementing features. In particular, I would like to thank Christopher
Felton and Frederik Teichert.
I would also like to thank Easics for the opportunity to use MyHDL in industrial projects.
WHAT'S NEW IN MYHDL 0.7
Conversion to VHDL/Verilog rewritten with the ast module
The most important code change is a change that hopefully no-one will notice :-). The
conversion code is now based on the ast package instead of the compiler package. Since
Python 2.6, the compiler package is deprecated and replaced by the new ast package in the
standard library. In Python 3, the compiler package is no longer available.
This was a considerable effort, spent on re-implementing existing behavior instead of on
new interesting features. This was unfortunate, but it had to be done with priority. Now
the conversion code is ready for the future.
Shadow signals
Background
Compared to HDLs such as VHDL and Verilog, MyHDL signals are less flexible for structural
modeling. For example, slicing a signal returns a slice of the current value. For
behavioral code, this is just fine. However, it implies that you cannot use such as slice
in structural descriptions. In other words, a signal slice cannot be used as a signal. To
solve these issues, a new concept was introduced: shadow signals.
The whole reasoning behind shadow signals is explained in more detail in mep-105.
Introducing shadow signals
A shadow signal is related to another signal or signals as a shadow to its parent object.
It follows any change to its parent signal or signals directly. However, it is not the
same as the original: in particular, the user cannot assign to a shadow signal. Also,
there may be a delta cycle delay between a change in the original and the corresponding
change in the shadow signal. Finally, to be useful, the shadow signal performs some kind
of transformation of the values of its parent signal or signals.
A shadow signal is convenient because it is directly constructed from its parent signals.
The constructor infers everything that's needed: the type info, the initial value, and the
transformation of the parent signal values. For simulation, the transformation is defined
by a generator which is automatically created and added to the list of generators to be
simulated. For conversion, the constructor defines a piece of dedicated Verilog and VHDL
code which is automatically added to the converter output.
Currently, three kinds of shadow signals have been implemented. The original inspiration
for shadow signals was to have solution for structural slicing. This is the purpose of the
_SliceSignal subclass. The opposite is also useful: a signal that shadows a composition of
other signals. This is the purpose of the ConcatSignal subclass.
As often is the case, the idea of shadow signals had some useful side effects. In
particular, I realized that the TristateSignal proposed in mep-103 could be interpreted
as a shadow signal of its drivers. With the machinery of the shadow signal in place, it
became easier to support this for simulation and conversion.
Concrete shadow signal subclasses
class _SliceSignal(sig, left[, right=None])
This class implements read-only structural slicing and indexing. It creates a new signal
that shadows the slice or index of the parent signal sig. If the right parameter is
omitted, you get indexing instead of slicing. Parameters left and right have the usual
meaning for slice indices: in particular, left is non-inclusive but right is inclusive.
sig should be appropriate for slicing and indexing, which means it should be based on
intbv in practice.
The class constructors is not intended to be used explicitly. Instead, regular signals now
have a call interface that returns a _SliceSignal:
Signal.__call__(left[, right=None])
Therefore, instead of:
sl = _SliceSignal(sig, left, right)
you can do:
sl = sig(left, right)
Obviously, the call interface was intended to be similar to a slicing interface. Of
course, it is not exactly the same which may seem inconvenient. On the other hand, there
are Python functions with a similar slicing functionality and a similar interface, such as
the range function. Moreover, the call interface conveys the notion that something is
being constructed, which is what really happens.
class ConcatSignal(*args)
This class creates a new signal that shadows the concatenation of its parent signal
values. You can pass an arbitrary number of signals to the constructor. The signal
arguments should be bit-oriented with a defined number of bits.
class TristateSignal(val)
This class is used to construct a new tristate signal. The underlying type is
specified by the val parameter. It is a Signal subclass and has the usual
attributes, with one exception: it doesn't support the next attribute.
Consequently, direct signal assignment to a tristate signal is not supported.
The initial value is the tristate value None. The current value of a tristate
is determined by resolving the values from its drivers. When exactly one driver
value is different from None, that is the resolved value; otherwise it is None.
When more than one driver value is different from None, a contention warning is
issued.
This class has the following method:
driver()
Returns a new driver to the tristate signal. It is initialized to None. A
driver object is an instance of a special SignalType subclass. In particular,
its next attribute can be used to assign a new value to it.
Example
A typical application of shadow signals is conversion of list of signals to bit vectors
and vice versa.
For example, suppose we have a system with N requesters that need arbitration. Each
requester has a request output and a grant input. To connect them in the system, we can
use list of signals. For example, a list of request signals can be constructed as follows:
request_list = [Signal(bool()) for i in range(M)]
Suppose that an arbiter module is available that is instantiated as follows:
arb = arbiter(grant_vector, request_vector, clock, reset)
The request_vector input is a bit vector that can have any of its bits asserted. The
grant_vector is an output bit vector with just a single bit asserted, or none. Such a
module is typically based on bit vectors because they are easy to process in RTL code. In
MyHDL, a bit vector is modeled using the intbv type.
We need a way to "connect" the list of signals to the bit vector and vice versa. Of
course, we can do this with explicit code, but shadow signals can do this automatically.
For example, we can construct a request_vector as a ConcatSignal object:
request_vector = ConcatSignal(*reversed(request_list)
Note that we reverse the list first. This is done because the index range of lists is the
inverse of the range of intbv bit vectors. By reversing, the indices correspond to the
same bit.
The inverse problem exist for the grant_vector. It would be defined as follows:
grant_vector = Signal(intbv(0)[M:])
To construct a list of signals that are connected automatically to the bit vector, we can
use the Signal call interface to construct _SliceSignal objects:
grant_list = [grant_vector(i) for i in range(M)]
Note the round brackets used for this type of slicing. Also, it may not be necessary to
construct this list explicitly. You can simply use grant_vector(i) in an instantiation.
To decide when to use normal or shadow signals, consider the data flow. Use normal signals
to connect to outputs. Use shadow signals to transform these signals so that they can be
used as inputs.
Using Signal and intbv objects as indices
Previously, it was necessary convert Signal and intbv objects explicitly to int when using
them as indices for indexing and slicing. This conversion is no longer required; the
objects can be used directly. The corresponding classes now have an __index__ method that
takes care of the type conversion automatically. This feature is fully supported by the
VHDL/Verilog converter.
New configuration attributes for conversion file headers
New configuration attributes are available to control the file headers of converted output
files.
toVerilog.no_myhdl_header
Specifies that MyHDL conversion to Verilog should not generate a default header.
Default value is False.
toVHDL.no_myhdl_header
Specifies that MyHDL conversion to VHDL should not generate a default header.
Default value is False.
toVerilog.header
Specifies an additional custom header for Verilog output.
toVHDL.header
Specifies an additional custom header for VHDL output.
The value for the custom headers should be a string that is suitable for the standard
string.Template constructor. A number of variables (indicated by a $ prefix) are
available for string interpolation. For example, the standard header is defined as
follows:
myhdl_header = """\
-- File: $filename
-- Generated by MyHDL $version
-- Date: $date
"""
The same interpolation variables are available in custom headers.
Conversion propagates docstrings
The converter now propagates comments under the form of Python docstrings.
Docstrings are typically used in Python to document certain objects in a standard way.
Such "official" docstrings are put into the converted output at appropriate locations.
The converter supports official docstrings for the top level module and for generators.
Within generators, "nonofficial" docstrings are propagated also. These are strings (triple
quoted by convention) that can occur anywhere between statements.
Regular Python comments are ignored by the Python parser, and they are not present in the
parse tree. Therefore, these are not propagated. With docstrings, you have an elegant way
to specify which comments should be propagated and which not.
New method to specify user-defined code
The current way to specify user-defined code for conversion is through the __vhdl__ and
__verilog__ hooks. This method has a number of disadvantages.
First, the use of "magic" variables (whose names start and end with double underscores)
was a bad choice. According to Python conventions, such variables should be reserved for
the Python language itself. Moreover, when new hooks would become desirable, we would
have to specify additional magic variables.
A second problem that standard Python strings were used to define the user-defined output.
These strings can contain the signal names from the context for interpolation. Typically,
these are multiple-line strings that may be quite lengthy. When something goes wrong with
the string interpolation, the error messages may be quite cryptic as the line and column
information is not present.
For these reasons, a new way to specify user-defined code has been implemented that avoids
these problems.
The proper way to specify meta-information of a function is by using function attributes.
Suppose a function <func> defines a hardware module. We can now specify user-defined code
for it with the following function attributes:
<func>.vhdl_code
A template string for user-defined code in the VHDL output.
<func>.verilog_code
A template string for user-defined code in the Verilog output.
When such a function attribute is defined, the normal conversion process is bypassed and
the user-defined code is inserted instead. The template strings should be suitable for
the standard string.Template constructor. They can contain interpolation variables
(indicated by a $ prefix) for all signals in the context. Note that the function attribute
can be defined anywhere where <func> is visible, either outside or inside the function
itself.
The old method for user-defined code is still available but is deprecated and will be
unsupported in the future.
More powerful mapping to case statements
The converter has become more powerful to map if-then-else structures to case statements
in VHDL and Verilog. Previously, only if-then-else structures testing enumerated types
were considered. Now, integer tests are considered also.
Small changes
SignalType as the base class of Signals
Signal has become a function instead of a class. It returns different Signal subtypes
depending on parameters. This implies that you cannot use Signal for type checking.
The base type of all Signals is now SignalType. This type can be used to check whether an
object is a Signal instance.
Default value of intbv objects
The default initial value of an intbv object has been changed from None to 0. Though this
is backward-incompatible, the None value never has been put to good use, so this is most
likely not an issue.
Combinatorial always blocks use blocking assignments
The converter now uses blocking assignments for combinatorial always blocks in Verilog.
This is in line with generally accepted Verilog coding conventions.
No synthesis pragmas in Verilog output
The converter no longer outputs the synthesis pragmas full_case and parallel_case. These
pragmas do more harm than good as they can cause simulation-synthesis mismatches.
Synthesis tools should be able to infer the appropriate optimizations from the source code
directly.
Python version
MyHDL 0.7 requires Python 2.6, mainly because of its dependency on the new ast package.
Acknowledgments
Several people have contributed to MyHDL 0.7 by giving feedback, making suggestions,
fixing bugs and implementing features. In particular, I would like to thank Benoit
Allard, Günter Dannoritzer, Tom Dillon, Knut Eldhuset, Angel Ezquerra, Christopher Felton,
and Jian LUO.
Thanks to Francesco Balau for packaging MyHDL for Ubuntu.
I would also like to thank Easics for the opportunity to use MyHDL in industrial projects.
WHAT'S NEW IN MYHDL 0.6
Conversion to VHDL
Rationale
Since the MyHDL to Verilog conversion has been developed, a path to implementation from
MyHDL is available. Given the widespread support for Verilog, it could thus be argued that
there was no real need for a converter to VHDL.
However, it turns out that VHDL is still very much alive and will remain so for the
foreseeable future. This is especially true for the FPGA market, which is especially
interesting for MyHDL. It seems much more dynamic than the ASIC market. Moreover, because
of the nature of FPGA's, FPGA designers may be more willing to try out new ideas.
To convince designers to use a new tool, it should integrate with their current design
flow. That is why the MyHDL to VHDL converter is needed. It should lower the threshold for
VHDL designers to start using MyHDL.
Advantages
MyHDL to VHDL conversion offers the following advantages:
MyHDL integration in a VHDL-based design flow
Designers can start using MyHDL and benefit from its power and flexibility, within
the context of their proven design flow.
The converter automates a number of hard tasks
The converter automates a number of tasks that are hard to do in VHDL directly. For
example, when mixing unsigned and signed types it can be difficult to describe the
desired behavior correctly. In contrast, a MyHDL designer can use the high-level
intbv type, and let the converter deal with type conversions and resizings.
MyHDL as an IP development platform
The possibility to convert the same MyHDL source to equivalent Verilog and VHDL
creates a novel application: using MyHDL as an IP development platform. IP
developers can serve customers for both target languages from a single MyHDL code
base. Moreover, MyHDL's flexibility and parametrizability make it ideally suited to
this application.
Solution description
Approach
The approach followed to convert MyHDL code to VHDL is identical to the one followed for
conversion to Verilog in previous MyHDL releases.
In particular, the MyHDL code analyzer in the converter is identical for both target
languages. The goal is that all MyHDL code that can be converted to Verilog can be
converted to VHDL also, and vice versa. This has been achieved except for a few minor
issues due to limitations of the target languages.
User interface
Conversion to VHDL is implemented by the following function in the myhdl package:
toVHDL(func[, *args][, **kwargs])
Converts a MyHDL design instance to equivalent VHDL code. func is a function that
returns an instance. toVHDL calls func under its control and passes *args and
**kwargs to the call.
The return value is the same as the one returned by the call func(*args, **kwargs).
It can be assigned to an instance name. The top-level instance name and the
basename of the Verilog output filename is func.func_name by default.
toVHDL has the following attributes:
toVHDL.name
This attribute is used to overwrite the default top-level instance name and the
basename of the VHDL output.
toVHDL.component_declarations
This attribute can be used to add component declarations to the VHDL output. When a
string is assigned to it, it will be copied to the appropriate place in the output
file.
Type mapping
In contrast to Verilog, VHDL is a strongly typed language. The converter has to carefully
perform type inferencing, and handle type conversions and resizings appropriately. To do
this right, a well-chosen mapping from MyHDL types to VHDL types is crucial.
MyHDL types are mapped to VHDL types according to the following table:
┌─────────────────────────┬──────────────────────────┬───────┐
│MyHDL type │ VHDL type │ Notes │
├─────────────────────────┼──────────────────────────┼───────┤
│int │ integer │ │
├─────────────────────────┼──────────────────────────┼───────┤
│bool │ std_logic │ (1) │
├─────────────────────────┼──────────────────────────┼───────┤
│intbv with min >= 0 │ unsigned │ (2) │
├─────────────────────────┼──────────────────────────┼───────┤
│intbv with min < 0 │ signed │ (2) │
├─────────────────────────┼──────────────────────────┼───────┤
│enum │ dedicated enumeration │ │
│ │ type │ │
├─────────────────────────┼──────────────────────────┼───────┤
│tuple of int │ mapped to case statement │ (3) │
├─────────────────────────┼──────────────────────────┼───────┤
│list of bool │ array of std_logic │ │
├─────────────────────────┼──────────────────────────┼───────┤
│list of intbv with min │ array of unsigned │ (4) │
│>= 0 │ │ │
├─────────────────────────┼──────────────────────────┼───────┤
│list of intbv with min < │ array of signed │ (4) │
│0 │ │ │
└─────────────────────────┴──────────────────────────┴───────┘
Notes:
1. The VHDL std_logic type is defined in the standard VHDL package IEEE.std_logic_1164.
2. The VHDL unsigned and signed types used are those from the standard VHDL packages
IEEE.numeric_std.
3. A MyHDL tuple of int is used for ROM inference, and can only be used in a very specific
way: an indexing operation into the tuple should be the rhs of an assignment.
4. All list members should have identical value constraints.
The table as presented applies to MyHDL variables. They are mapped to VHDL variables
(except for the case of a tuple of int).
The converter also supports MyHDL signals that use bool, intbv or enum objects as their
underlying type. These are mapped to VHDL signals with a type as specified in the table
above.
The converter supports MyHDL list of signals provided the underlying signal type is either
bool or intbv. They may be mapped to a VHDL signal with a VHDL type as specified in the
table. However, list of signals are not always mapped to a corresponding VHDL signal. See
Conversion of lists of signals for more info.
Template transformation
There is a difference between VHDL and Verilog in the way in which sensitivity to signal
edges is specified. In Verilog, edge specifiers can be used directly in the sensitivity
list. In VHDL, this is not possible: only signals can be used in the sensitivity list. To
check for an edge, one uses the rising_edge() or falling_edge() functions in the code.
MyHDL follows the Verilog scheme to specify edges in the sensitivity list. Consequently,
when mapping such code to VHDL, it needs to be transformed to equivalent VHDL. This is an
important issue because it affects all synthesizable templates that infer sequential
logic.
We will illustrate this feature with some examples. This is the MyHDL code for a D
flip-flop:
@always(clk.posedge)
def logic():
q.next = d
It is converted to VHDL as follows:
DFF_LOGIC: process (clk) is
begin
if rising_edge(clk) then
q <= d;
end if;
end process DFF_LOGIC;
The converter can handle the more general case. For example, this is MyHDL code for a D
flip-flop with asynchronous set, asynchronous reset, and preference of set over reset:
@always(clk.posedge, set.negedge, rst.negedge)
def logic():
if set == 0:
q.next = 1
elif rst == 0:
q.next = 0
else:
q.next = d
This is converted to VHDL as follows:
DFFSR_LOGIC: process (clk, set, rst) is
begin
if (set = '0') then
q <= '1';
elsif (rst = '0') then
q <= '0';
elsif rising_edge(clk) then
q <= d;
end if;
end process DFFSR_LOGIC;
All cases with practical utility can be handled in this way. However, there are other
cases that cannot be transformed to equivalent VHDL. The converter will detect those cases
and give an error.
Conversion of lists of signals
Lists of signals are useful for many purposes. For example, they make it easy to create a
repetitive structure. Another application is the description of memory behavior.
The converter output is non-hierarchical. That implies that all signals are declared at
the top-level in VHDL or Verilog (as VHDL signals, or Verilog regs and wires.) However,
some signals that are a list member at some level in the design hierarchy may be used as a
plain signal at a lower level. For such signals, a choice has to be made whether to
declare a Verilog memory or VHDL array, or a number of plain signal names.
If possible, plain signal declarations are preferred, because Verilog memories and arrays
have some restrictions in usage and tool support. This is possible if the list syntax is
strictly used outside generator code, for example when lists of signals are used to
describe structure.
Conversely, when list syntax is used in some generator, then a Verilog memory or VHDL
array will be declared. The typical example is the description of RAM memories.
The converter in the previous MyHDL release had a severe restriction on the latter case:
it didn't allow that, for a certain signal, list syntax was used in some generator, and
plain signal syntax in another. This restriction, together with its rather obscure error
message, has caused regular user complaints. In this release, this restriction has been
lifted.
Conversion of test benches
Background
After conversion, we obviously want to verify that the VHDL or Verilog code works
correctly. In previous MyHDL versions, the proposed verification technique was
co-simulation: use the same MyHDL test bench to simulate the converted Verilog code and
the original MyHDL code. While co-simulation works well, there are a number of issues with
it:
• Co-simulation requires that the HDL simulator has an interface to its internal workings,
such as vpi for Verilog and vhpi for VHDL.
• vpi for Verilog is well-established and available for open-source simulators such as
Icarus and cver. However, vhpi for VHDL is much less established; it is unclear whether
there is an open source solution that is powerful enough for MyHDL's purposes.
• Even though vpi is a "standard", there are differences between various simulators.
Therefore, some customization is typically required per Verilog simulator.
• MyHDL co-simulation uses unix-style interprocess communication that doesn't work on
Windows natively. This is an exception to the rest of MyHDL that should run on any
Python platform.
The conclusion is that co-simulation is probably not a viable solution for the VHDL case,
and it has some disadvantages for Verilog as well.
The proposed alternative is to convert the test bench itself, so that both test bench and
design can be run in the HDL simulator. Of course, this is not a fully general solution
either, as there are important restrictions on the kind of code that can be converted.
However, with the additional features that have been developed, it should be a useful
solution for verifying converted code.
Print statement
In previous MyHDL versions, print statement conversion to Verilog was supported in a quick
and dirty way, by merely copying the format string without checks. With the advent of VHDL
conversion, this has now been implemented more rigorously. This was necessary because VHDL
doesn't work with format strings. Rather, the format string specification has to be
converted to a sequence of VHDL write and writeline calls.
A print statement with multiple arguments:
print arg1, arg2, ...
is supported. However, there are restrictions on the arguments. First, they should be of
one of the following forms:
arg
formatstring % arg
formatstring % (arg1, arg2, ...)
where arg is a bool, int, intbv, enum, or a Signal of these types.
The formatstring contains ordinary characters and conversion specifiers as in Python.
However, the only supported conversion specifiers are %s and %d. Justification and width
specification are thus not supported.
Printing without a newline:
print arg1 ,
is not supported. This is because the solution is based on std.textio. In VHDL std.textio,
subsequent write() calls to a line are only printed upon a writeline() call. As a normal
print implies a newline, the correct behavior can be guaranteed, but for a print without
newline this is not possible. In the future, other techniques may be used and this
restriction may be lifted.
Assert statement
An assert statement in Python looks as follow:
assert test_expression
It can be converted provided test_expression is convertible.
Delay objects
Delay objects are constructed as follows:
delay(t)
with t an integer. They are used in yield statements and as the argument of always
decorators, to specify delays. They can now be converted.
Methodology notes
The question is whether the conversion restrictions permit one to develop sufficiently
complex test benches. In this section, we present some insights about this.
The most important restrictions are the types that can be used. These remain
"hardware-oriented" as before.
Even in the previous MyHDL release, the "convertible subset" was much wider than the
"synthesis subset". For example, while and raise statement were already convertible.
The support for delay objects is the most important new feature to write high-level models
and test benches.
With the print statement, simple debugging can be done.
Of particular interest is the assert statement. Originally, assert statements were only
intended to insert debugging assertions in code. Recently, there is a tendency to use them
to write self-checking unit tests, controlled by unit test frameworks such as py.test. In
particular, they are a powerful way to write self-checking test benches for MyHDL designs.
As assert statements are now convertible, a whole test suite in MyHDL can be converted to
an equivalent test suite in Verilog and VHDL.
Finally, the same techniques as for synthesizable code can be used to master complexity.
In particular, any code outside generators is executed during elaboration, and therefore
not considered in the conversion process. This feature can for example be used for complex
calculations that set up constants or expected results. Furthermore, a tuple of ints can
be used to hold a table of values that will be mapped to a case statement in Verilog and
VHDL.
Conversion output verification
NOTE:
This functionality is not needed in a typical design flow. It is only relevant to debug
the MyHDL converter itself.
Approach
To verify the converter output, a methodology has been developed and implemented that
doesn't rely on co-simulation and works for both Verilog and VHDL.
The solution builds on the features explained in section Conversion of test benches. The
idea is basically to convert the test bench as well as the functional code. In particular,
print statements in MyHDL are converted to equivalent statements in the HDL. The
verification process consists of running both the MyHDL and the HDL simulation, comparing
the simulation output, and reporting any differences.
The goal is to make the verification process as easy as possible. The use of print
statements to debug a design is a very common and simple technique. The verification
process itself is implemented in a single function with an interface that is identical to
toVHDL and toVerilog.
As this is a native Python solution, it runs on any platform on which the HDL simulator
runs. Moreover, any HDL simulator can be used as no vpi or vhpi capabilities are needed.
Of course, per HDL simulator some customization is required to define the details on how
it is used. This needs to be done once per HDL simulator and is fully under user control.
Verification interface
All functions related to conversion verification are implemented in the myhdl.conversion
package. (To keep the myhdl namespace clean, they are not available from the myhdl
namespace directly.)
verify(func[, *args][, **kwargs])
Used like toVHDL. It converts MyHDL code, simulates both the MyHDL code and the HDL
code and reports any differences. The default HDL simulator is GHDL.
analyze(func[, *args][, **kwargs])
Used like toVHDL. It converts MyHDL code, and analyzes the resulting HDL. Used to
verify whether the HDL output is syntactically correct.
The two previous functions have the following attribute:
analyze.simulator
Used to set the name of the HDL analyzer. GHDL is the default.
verify.simulator
Used to set the name of the HDL simulator. GHDL is the default.
HDL simulator registration
To be able to use a HDL simulator to verify conversions, it needs to be registered first.
This is needed once per simulator (or rather, per set of analysis and simulation
commands). Registering is done with the following function:
registerSimulator(name=None, hdl=None, analyze=None, elaborate=None, simulate=None,
offset=0)
Registers a particular HDL simulator to be used by verify and analyze. name is the
name of the simulator. hdl specifies the HDL: "VHDL" or "Verilog". analyze is a
command string to analyze the HDL source code. elaborate is a command string to
elaborate the HDL code. This command is optional. simulate is a command string to
simulate the HDL code. offset is an integer specifying the number of initial lines
to be ignored from the HDL simulator output.
The command strings should be string templates that refer to the topname variable
that specifies the design name. The templates can also use the unitname variable
which is the lower case version of topname. The command strings can assume that a
subdirectory called work is available in the current working directory. Analysis
and elaboration results can be put there if desired.
The analyze function runs the analyze command. The verify function runs the
analyze command, then the elaborate command if any, and then the simulate command.
The GHDL simulator is registered by default, but its registration can be
overwritten if required.
Example: preregistered HDL simulators
A number of open-source HDL simulators are preregistered in the MyHDL distribution. If
they are installed in the typical way, they are readily available for conversion
verification. We will illustrate the registration process by showing the registrations of
these simulators.
GHDL registration:
registerSimulator(
name="GHDL",
hdl="VHDL",
analyze="ghdl -a --workdir=work pck_myhdl_%(version)s.vhd %(topname)s.vhd",
elaborate="ghdl -e --workdir=work -o %(unitname)s_ghdl %(topname)s",
simulate="ghdl -r %(unitname)s_ghdl"
)
Icarus registration:
registerSimulator(
name="icarus",
hdl="Verilog",
analyze="iverilog -o %(topname)s.o %(topname)s.v",
simulate="vvp %(topname)s.o"
)
cver registration:
registerSimulator(
name="cver",
hdl="Verilog",
analyze="cver -c -q %(topname)s.v",
simulate="cver -q %(topname)s.v",
offset=3
)
New modeling features
New signed() method for intbv
The intbv object has a new method signed that implements sign extension. The extended bit
is the msb bit of the bit representation of the object.
Clearly, this method only has an effect for intbv objects whose valid values are a finite
range of positive integers.
This method can be converted to VHDL and Verilog.
always_comb and list of signals
In the previous MyHDL release, one could use lists of signals in an always_comb block, but
they were not considered to infer the sensitivity list. To several users, this was
unexpected behavior, or even a bug.
In the present release, lists of signals are considered and the corresponding signals are
added to the sensitivity list. The converter to Verilog and VHDL is adapted accordingly.
Backwards incompatible changes
Decorator usage
The basic building block of a MyHDL design is a specialized Python generator.
In MyHDL 0.5, decorators were introduced to make it easier to create useful MyHDL
generators. Moreover, they make the code clearer. As a result, they are now the de facto
standard to describe hardware modules in MyHDL.
The implementation of certain tasks, such a signal tracing and conversion, can be
simplified significantly if decorators are used to create the generators. These
simplifications have now been adopted in the code. This means that decorator usage is
assumed. Legacy code written for the mentioned purposes without decorators, can always be
easily converted into code with decorators.
For pure modeling, it doesn't matter how generators are created and this will remain so.
Therefore, designers can continue to experiment with innovative modeling concepts in the
fullest generality.
instances() function
The instances function can be used to automatically lookup and return the instances that
are defined in a MyHDL module. In accordance with the section Decorator usage, its
functionality has been changed. Only generators created by decorators are considered when
looking up instances.
Conversion of printing without a newline
Printing without a newline (a print statement followed by a comma) is no longer supported
by the converter to Verilog. This is done to be compatible with the converter to VHDL.
Currently, the VHDL solution relies on std.textio and this implies that printing without a
newline cannot be reliably converted.
WHAT'S NEW IN MYHDL 0.5
Author Jan Decaluwe
Modeling
Creating generators with decorators
Introduction
Python 2.4 introduced a new feature called decorators. A decorator consists of special
syntax in front of a function declaration. It refers to a decorator function. The
decorator function automatically transforms the declared function into some other callable
object.
MyHDL 0.5 defines decorators that can be used to create ready-to-run generators from local
functions. The use of decorators results in clearer, more explicit code.
The @instance decorator
The @instance decorator is the most general decorator in MyHDL.
In earlier versions of MyHDL, local generator functions are typically used as follows:
def top(...):
...
def gen_func():
<generator body>
...
inst = gen_func()
...
return inst, ...
Note that the generator function gen_func is intended to be called exactly once, and that
its name is not necessary anymore afterwards. In MyHDL 0.5, this can be rewritten as
follows, using the @instance decorator:
def top(...):
...
@instance
def inst():
<generator body>
...
return inst, ...
Behind the curtains, the @instance decorator automatically creates a generator by calling
the generator function, and by reusing its name. Note that it is placed immediately in
front of the corresponding generator function, resulting in clearer code.
The @always decorator
The @always decorator is a specialized decorator that targets a very popular coding
pattern. It is used as follows:
def top(...):
...
@always(event1, event2, ...)
def inst()
<body>
...
return inst, ...
The meaning of this code is that the decorated function is executed whenever one of the
events occurs. The argument list of the decorator corresponds to the sensitivity list.
Appropriate events are edge specifiers, signals, and delay objects. The decorated function
is a classic function instead of a generator function.
Behind the curtains, the always decorator creates an enclosing while True loop
automatically, and inserts a yield statement with the sensitivity list.
The @always_comb decorator
The @always_comb decorator is used to describe combinatorial logic. It is nothing else
than the always_comb function from earlier MyHDL versions used as a decorator:
def top(...):
...
@always_comb
def comb_inst():
<combinatorial body>
...
return comb_inst, ...
The @always_comb decorator infers the inputs of the combinatorial logic and the
corresponding sensitivity list automatically.
More information
For more information about the background and the design decisions regarding MyHDL
decorators, see mep-100.
Recommended style changes
Decorator usage
The use of decorators has clear advantages in terms of code clarity. Therefore, it is
recommended that all local generators be created using decorators.
Edge specifiers
Signal edges are typically specified using the posedge and negedge functions in MyHDL.
However, these functions are simply wrappers around attributes with the same name. The
design decision to use functions have been reviewed and found questionable. In fact, using
the attributes directly instead has significant advantages, listed in order of increasing
significance:
• one character less to type
• more object-oriented style
• less symbols in the myhdl namespace
• no brackets, which is better for clarity
• no function call overhead
From MyHDL 0.5 on, it is therefore recommended to use the edge specifier attributes. For
example:
clk.posedge # instead of posedge(clk)
rst.negedge # instead of negedge(clk)
Deprecated features
Edge specifier functions
Functions posedge and negedge are deprecated. As discussed before, it is recommended to
use the signal attributes with the same name instead.
In MyHDL 0.5, the functions will be removed from all documentation and examples. They will
be removed from MyHDL in a future version.
processes() function
Function processes is deprecated. It looks up local generator functions and calls them to
create generators. When MyHDL 0.5 decorators are used as recommended, this functionality
becomes superfluous as it is part of the decorator functionality.
On the other hand, the companion function instances continues to be relevant and useful.
It merely looks up instances in a local namespace. Having a single lookup function will
also improve usability.
In MyHDL 0.5, the processes function will be removed from all documentation and examples.
It will be removed from MyHDL in a future version.
Backwards incompatible changes
Default initial value of an intbv instance
It has always been possible to construct an intbv instance without explicit initial value:
m = intbv()
Prior to MyHDL 0.4, the default initial value was 0. In MyHDL 0.5, this has been changed
to None. This is a first step towards support for X and Z functionality as found in other
HDLs. This may be occasionally useful :-) For example, it may be meaningful to initialize
memory locations to None to make sure that they will not be read before they have been
initialized. If None is supported, it seems also logical to make it the default initial
value, to be interpreted as "No value".
Warning: if you have calls like the above in your code, it will probably fail with MyHDL
0.5, as many integer-like operations are not supported with None values.
Workaround: change your existing code by using 0 as an explicit initial value, like so:
m = intbv(0)
Python version
Because of the usage of new features such as decorators, MyHDL 0.5 requires upgrading to
Python 2.4 or higher.
Verilog conversion
Decorator support
The Verilog converter was enhanced to support the proposed decorators.
Mapping a list of signals to a RAM memory
Certain synthesis tools can map Verilog memories to memory structures. For example, this
is supported by the Xilinx toolset. To support this interesting feature, the Verilog
converter now maps lists of signals in MyHDL to Verilog memories.
The following MyHDL example is a ram model that uses a list of signals to model the
internal memory.
def RAM(dout, din, addr, we, clk, depth=128):
""" Ram model """
mem = [Signal(intbv(0)[8:]) for i in range(depth)]
@always(clk.posedge)
def write():
if we:
mem[int(addr)].next = din
@always_comb
def read():
dout.next = mem[int(addr)]
return write, read
With the appropriate signal definitions for the interface ports, it is mapped by toVerilog
to the following Verilog code. Note how the list of signals mem is mapped to a Verilog
memory.
module RAM (
dout,
din,
addr,
we,
clk
);
output [7:0] dout;
wire [7:0] dout;
input [7:0] din;
input [6:0] addr;
input we;
input clk;
reg [7:0] mem [0:128-1];
always @(posedge clk) begin: _RAM_write
if (we) begin
mem[addr] <= din;
end
end
assign dout = mem[addr];
endmodule
Lists of signals can also be used in MyHDL to elegantly describe iterative hierarchical
structures. (See the MyHDL manual.) However, there is an important difference: such
signals will have a name at some level of the hierarchy, while in the case described
above, the individual signals are anonymous. The toVerilog converter detects which case we
are in. In the first case, the individual signals will still be declared in the Verilog
output, using the highest-level hierarchical name. It is only in the second case that the
list of signals is declared as a Verilog memory.
Mapping combinatorial logic to assign statements
When possible, combinatorial logic is now converted to Verilog assign statements. There
are two conditions for this to happen. First, the logic has to be explicitly described as
a combinatorial function using the @always_comb decorator. Secondly, the function has to
be simple enough so that a mapping to assign statements is possible: only signal
assignments are permitted. Otherwise, a Verilog always block is used as previously.
See the RAM model of the previous section for an example.
This was done because certain synthesis tools require assign statements to recognize code
templates.
Mapping a tuple of integers to a ROM memory
Some synthesis tools, such as the Xilinx tool, can infer a ROM memory from a case
statement. toVerilog has been enhanced to do the expansion into a case statement
automatically, based on a higher level description. The rom access is described in a
single line, by indexing into a tuple of integers. The tuple can be described manually,
but also by programmatical means. Note that a tuple is used instead of a list to stress
the read-only character of the memory.
The following example illustrates this functionality.
def rom(dout, addr, CONTENT):
@always_comb
def read():
dout.next = CONTENT[int(addr)]
return read
dout = Signal(intbv(0)[8:])
addr = Signal(intbv(0)[4:])
CONTENT = (17, 134, 52, 9)
toVerilog(rom, dout, addr, CONTENT)
The output Verilog code is as follows:
module rom (
dout,
addr
);
output [7:0] dout;
reg [7:0] dout;
input [3:0] addr;
always @(addr) begin: _rom_read
// synthesis parallel_case full_case
case (addr)
0: dout <= 17;
1: dout <= 134;
2: dout <= 52;
default: dout <= 9;
endcase
end
endmodule
Support for signed arithmetic
Getting signed representations right in Verilog is tricky. One issue is that a signed
representation is treated as a special case, and unsigned as the rule. For example,
whenever one of the operands in an expression is unsigned, all others are also treated
like unsigned. While this is understandable from a historical perspective (for backwards
compatibility reasons) it is the opposite from what one expects from a high-level point of
view, when working with negative numbers. The basic problem is that a Verilog user has to
deal with representation explicitly in all cases, even for abstract integer operations.
It would be much better to leave representational issues to a tool.
MyHDL doesn't make the distinction between signed and unsigned. The intbv class can handle
any kind of integer, including negative ones. If required, you can access the 2's
complement representation of an intbv object, but for integer operations such a counting,
there is no need to worry about this.
Of course, the Verilog converter has to deal with the representation carefully. MyHDL 0.4
avoided the issue by simply prohibiting intbv objects with negative values. MyHDL 0.5 adds
support for negative values and uses the signed Verilog representation to accomplish this.
The problematic cases are those when signed and unsigned representations are mixed in
Verilog expressions. The converter avoids this by making sure that signed arithmetic is
used whenever one of the operands is signed. Note that this is exactly the opposite of the
Verilog default. More specifically, the converter may convert an unsigned operand by
adding a sign bit and casting to a signed interpretation, using the Verilog $signed
function. Operands that are treated like this are positive intbv objects, slices and
subscripts of intbv objects, and bool objects.
Integer constants are treated as a special case. Unsized integer numbers were always
treated as signed numbers in Verilog. However, as their representation is minimally 32
bits wide, they usually don't give problems when mixed with unsigned numbers. Therefore,
integer constants don't cause signed casting of other operands in the same expression:
users would actually find it surprizing if they did.
Support for user-defined Verilog code
Introduction
In order to provide a path to implementation, MyHDL code can be converted to Verilog.
However, in some cases the conversion may fail or the result may not be acceptable. For
example:
• conversion will fail if the MyHDL code doesn't follow the rules of the convertible
subset
• a user may want to explicitly instantiate an existing Verilog module, instead of
converting the corresponding MyHDL code
• it may be necessary to include technology-dependent modules in the Verilog output
As a conclusion, MyHDL users need a method to include user-defined Verilog code during the
conversion process.
Solution
MyHDL 0.5 defines a hook that is understood by toVerilog but ignored by the MyHDL
simulator. The hook is called __verilog__. Its operation can be understood as a special
return value. When a MyHDL function defines __verilog__, the Verilog converter will use
its value instead of the regular return value.
The value of __verilog__ should be a format string that uses keys in its format
specifiers. The keys refer to the variable names in the context of the string.
Example:
def inc_comb(nextCount, count, n):
@always_comb
def logic():
nextCount.next = (count + 1) % n
__verilog__ = \
"""
assign %(nextCount)s = (%(count)s + 1) %% %(n)s;
"""
nextCount.driven = "wire"
return logic
In this example, conversion of the inc_comb function is bypassed and the user-defined
Verilog code is inserted instead. Note that the user-defined code refers to signals and
parameters in the MyHDL context by using format specifiers. During conversion, the
appropriate hierarchical names and parameter values will be filled in. Note also that the
format specifier indicator % needs to be escaped (by doubling it) if it is required in the
user-defined code.
There is one more issue that needs user attention. Normally, the Verilog converter infers
inputs, internal signals, and outputs. It also detects undriven and multiple driven
signals. To do this, it assumes that signals are not driven by default. It then processes
the code to find out which signals are driven from where. However, it cannot do this for
user-defined code. Without additional help, this will result in warnings or errors during
the inference process, or in compilation errors from invalid Verilog code. The user should
solve this by setting the driven attribute for signals that are driven from the
user-defined code. In the example code above, note the following assignment:
nextCount.driven = "wire"
This specifies that the nextCount signal is driven as a Verilog wire from this module. The
allowed values of the driven attribute are "wire" and "reg". The value specifies how the
user-defined Verilog code drives the signal in Verilog. To decide which value to use,
consider how the signal should be declared in Verilog after the user-defined code is
inserted.
Limitations
It is not possible to use the __verilog__ hook in a generator function - it should be in a
classic function. This is because in MyHDL those functions are completely run (elaborated)
before the conversion starts, while generator functions are not.
More info
For more information about the background and the design decisions regarding user-defined
Verilog code, see mep-101.
Backwards incompatible changes
Verilog conversion output filename
A Verilog conversion is performed with a call that looks as follows:
instance_name = toVerilog(func, ...)
In MyHDL 0.4, the Verilog output filename was called instance_name.v. In MyHDL 0.5, the
default output filename is func_name.v, where func_name is the name of the function,
available as the func.func_name attribute.
This was done for the following reasons. The MyHDL 0.4 was overly clever and therefore
complicated. It involves frame handling and parsing the source file for the assignment
pattern. Besides being too clever, it also had awkward limitations. For example, it was
not possible to construct a dynamic name for the instance, which is very un-Pythonic
behavior.
Both the implementation complexity and the limitations are gone with the new behavior: the
name of the top-level function argument is simply used. In addition, it is now possible to
specify a user-defined name for the instance as follows:
toVerilog.name = "my_name"
toVerilog(func, ....)
To support this feature, it was necessary to make toVerilog an instance of a class with a
call interface.
Warning: When existing converting code is re-run, the Verilog output filename will be
different than in 0.4.
Simulation
Performance optimizations
To improve the simulation performance of MyHDL, we mainly put our trust in Python
development itself. There are good reasons to be optimistic.
What MyHDL itself can do is to minimize the overhead of the simulation loop. In MyHDL 0.5,
a first step was taken in this respect.
MyHDL supports a number of "trigger objects". These are the objects that can occur in
yield statements, for example delay, posedge, Signal, and generator objects. Each of these
are handled differently and so the simulation loop has to account for the object type.
Prior to MyHDL 0.5, this type check was explicitly done for each occurrence of a yield
statement during simulation. As many generators will loop endlessly, it is clear that the
same things will be checked over and over again, resulting in an important overhead.
In MyHDL 0.5, all generators are predigested. Certain trigger object patterns that tend to
occur often are given specialized simulation handlers, so that continuously performing the
same type check is avoided. More specifically, they consist of generators that only
contain yield statements with a specific argument. Currently, 5 different kinds of
generators are recognized and accelerated, corresponding to the following yield statement
arguments:
• a delay object
• a Signal object
• a tuple of Signal objects
• a posedge or negedge object
• a tuple of posedge and/or negedge objects
Backwards incompatible changes
Waveform tracing output filename
Waveform tracing is initiated by a call that looks as follows:
instance_name = traceSignals(func, ...)
In MyHDL 0.4, the output filename was called instance_name.vcd. In MyHDL 0.5, the default
output filename is func_name.vcd, where func_name is the name of the function, available
as the func.func_name attribute.
This was done for the same reasons as in the similar case for toVerilog, as described
earlier.
A user-defined name for the output file can be specified as follows:
traceSignals.name = "my_name"
inst = traceSignals(func, ....)
Warning: When existing converting code is re-run, the vcd output filename will be
different than in 0.4.
WHAT'S NEW IN MYHDL 0.4: CONVERSION TO VERILOG
Author Jan Decaluwe
Introduction
MyHDL 0.4 supports the automatic conversion of a subset of MyHDL code to synthesizable
Verilog code. This feature provides a direct path from Python to an FPGA or ASIC
implementation.
MyHDL aims to be a complete design language, for tasks such as high level modeling and
verification, but also for implementation. However, prior to 0.4 a user had to translate
MyHDL code manually to Verilog or VHDL. Needless to say, this was inconvenient. With
MyHDL0.4, this manual step is no longer necessary.
Solution description
The solution works as follows. The hardware description should be modeled in MyHDL style,
and satisfy certain constraints that are typical for implementation-oriented hardware
modeling. Subsequently, such a design is converted to an equivalent model in the Verilog
language, using the function toVerilog from the MyHDLlibrary. Finally, a third-party
synthesis tool is used to convert the Verilog design to a gate implementation for an ASIC
or FPGA. There are a number of Verilog synthesis tools available, varying in price,
capabilities, and target implementation technology.
The conversion does not start from source files, but from a design that has been
elaborated by the Python interpreter. The converter uses the Python profiler to track the
interpreter’s operation and to infer the design structure and name spaces. It then
selectively compiles pieces of source code for additional analysis and for conversion.
This is done using the Python compiler package.
Features
The design is converted after elaboration
Elaboration refers to the initial processing of a hardware description to achieve a
representation of a design instance that is ready for simulation or synthesis. In
particular, structural parameters and constructs are processed in this step. In MyHDL, the
Python interpreter itself is used for elaboration. A Simulation object is constructed with
elaborated design instances as arguments. Likewise, the Verilog conversion works on an
elaborated design instance. The Python interpreter is thus used as much as possible.
The structural description can be arbitrarily complex and hierarchical
As the conversion works on an elaborated design instance, any modeling constraints only
apply to the leaf elements of the design structure, that is, the co-operating generators.
In other words, there are no restrictions on the description of the design structure:
Python’s full power can be used for that purpose. Also, the design hierarchy can be
arbitrarily deep.
Generators are mapped to Verilog always or initial blocks
The converter analyzes the code of each generator and maps it to a Verilog always blocks
if possible, and to an initial block otherwise. The converted Verilog design will be a
flat “net list of blocks”.
The Verilog module interface is inferred from signal usage
In MyHDL, the input or output direction of interface signals 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. Internal signals are given a
hierarchical name in the Verilog output.
Function calls are mapped to a unique Verilog function or task call
The converter analyzes function calls and function code to see if they should be mapped to
Verilog functions or to tasks. Python functions are much more powerful than Verilog
subprograms; for example, they are inherently generic, and they can be called with named
association. To support this power in Verilog, a unique Verilog function or task is
generated per Python function call.
If-then-else structures may be mapped to Verilog case statements
Python does not provide a case statement. However, the converter recognizes if-then-else
structures in which a variable is sequentially compared to items of an enumeration type,
and maps such a structure to a Verilog case statement with the appropriate synthesis
attributes.
Choice of encoding schemes for enumeration types
The enum function in MyHDL returns an enumeration type. This function takes an additional
parameter encoding that specifies the desired encoding in the implementation: binary, one
hot, or one cold. The Verilog converter generates the appropriate code.
The convertible subset
Introduction
Unsurprisingly, not all MyHDL code can be converted to Verilog. In fact, there are very
important restrictions. As the goal of the conversion functionality is implementation,
this should not be a big issue: anyone familiar with synthesis is used to similar
restrictions in the synthesizable subset of Verilog and VHDL. The converter attempts to
issue clear error messages when it encounters a construct that cannot be converted.
In practice, the synthesizable subset usually refers to RTL synthesis, which is by far the
most popular type of synthesis today. There are industry standards that define the RTL
synthesis subset. However, those were not used as a model for the restrictions of the
MyHDL converter, but as a minimal starting point. On that basis, whenever it was judged
easy or useful to support an additional feature, this was done. For example, it is
actually easier to convert while loops than for loops even though they are not
RTL-synthesizable. As another example, print is supported because it’s so useful for
debugging, even though it’s not synthesizable. In summary, the convertible subset is a
superset of the standard RTL synthesis subset, and supports synthesis tools with more
advanced capabilities, such as behavioral synthesis.
Recall that any restrictions only apply to the design post elaboration. In practice, this
means that they apply only to the code of the generators, that are the leaf functional
blocks in a MyHDL design.
Coding style
A natural restriction on convertible code is that it should be written in MyHDL style:
cooperating generators, communicating through signals, and with yield statements
specifying wait points and resume conditions. Supported resume conditions are a signal
edge, a signal change, or a tuple of such conditions.
Supported types
The most important restriction regards object types. Verilog is an almost typeless
language, while Python is strongly (albeit dynamically) typed. The converter has to infer
the types of names used in the code, and map those names to Verilog variables.
Only a limited amount of types can be converted. Python int and long objects are mapped to
Verilog integers. All other supported types are mapped to Verilog regs (or wires), and
therefore need to have a defined bit width. The supported types are the Python bool type,
the MyHDL intbv type, and MyHDL enumeration types returned by function enum. The latter
objects can also be used as the base object of a Signal.
intbv objects must be constructed so that a bit width can be inferred. This can be done by
specifying minimum and maximum values, e.g. as follows:
index = intbv(0, min=0, max=2**N)
Alternatively, a slice can be taken from an intbv object as follows:
index = intbv(0)[N:]
Such as slice returns a new intbv object, with minimum value 0 , and maximum value 2**N.
Supported statements
The following is a list of the statements that are supported by the Verilog converter,
possibly qualified with restrictions or usage notes.
The break statement.
The continue statement.
The def statement.
The for statement.
The only supported iteration scheme is iterating through sequences of integers
returned by built-in function range or MyHDLfunction downrange. The optional else
clause is not supported.
The if statement.
if, elif, and else clauses are fully supported.
The pass statement.
The print statement.
When printing an interpolated string, the format specifiers are copied verbatim to
the Verilog output. Printing to a file (with syntax ’>>’) is not supported.
The raise statement.
This statement is mapped to Verilog statements that end the simulation with an
error message.
The return statement.
The yield statement.
The yielded expression can be a signal, a signal edge as specified by
MyHDL functions posedge or negedge, or a tuple of signals and edge specifications.
The while statement.
The optional else clause is not supported.
Methodology notes
Simulation
In the Python philosophy, the run-time rules. The Python compiler doesn’t attempt to
detect a lot of errors beyond syntax errors, which given Python’s ultra-dynamic nature
would be an almost impossible task anyway. To verify a Python program, one should run it,
preferably using unit testing to verify each feature.
The same philosophy should be used when converting a MyHDL description to Verilog: make
sure the simulation runs fine first. Although the converter checks many things and
attempts to issue clear error messages, there is no guarantee that it does a meaningful
job unless the simulation runs fine.
Conversion output verification
It is always prudent to verify the converted Verilog output. To make this task easier, the
converter also generates a test bench that makes it possible to simulate the Verilog
design using the Verilog co-simulation interface. This permits one to verify the Verilog
code with the same test bench used for the MyHDL code. This is also how the Verilog
converter development is being verified.
Assignment issues
Name assignment in Python
Name assignment in Python is a different concept than in many other languages. This point
is very important for effective modeling in Python, and even more so for synthesizable
MyHDL code. Therefore, the issues are discussed here explicitly.
Consider the following name assignments:
a = 4
a = ``a string''
a = False
In many languages, the meaning would be that an existing variable a gets a number of
different values. In Python, such a concept of a variable doesn’t exist. Instead,
assignment merely creates a new binding of a name to a certain object, that replaces any
previous binding. So in the example, the name a is bound a number of different objects in
sequence.
The Verilog converter has to investigate name assignment and usage in MyHDL code, and to
map names to Verilog variables. To achieve that, it tries to infer the type and possibly
the bit width of each expression that is assigned to a name.
Multiple assignments to the same name can be supported if it can be determined that a
consistent type and bit width is being used in the assignments. This can be done for
boolean expressions, numeric expressions, and enumeration type literals. In Verilog, the
corresponding name is mapped to a single bit reg, an integer, or a reg with the
appropriate width, respectively.
In other cases, a single assignment should be used when an object is created. Subsequent
value changes are then achieved by modification of an existing object. This technique
should be used for Signal and intbv objects.
Signal assignment
Signal assignment in MyHDL is implemented using attribute assignment to attribute next.
Value changes are thus modeled by modification of the existing object. The converter
investigates the Signal object to infer the type and bit width of the corresponding
Verilog variable.
intbv objects
Type intbv is likely to be the workhorse for synthesizable modeling in MyHDL. An intbv
instance behaves like a (mutable) integer whose individual bits can be accessed and
modified. Also, it is possible to constrain its set of values. In addition to error
checking, this makes it possible to infer a bit width, which is required for
implementation.
In Verilog, an intbv instance will be mapped to a reg with an appropriate width. As noted
before, it is not possible to modify its value using name assignment. In the following, we
will show how it can be done instead. Consider:
a = intbv(0)[8:]
This is an intbv object with initial value 0 and bit width 8. The change its value to 5,
we can use slice assignment:
a[8:] = 5
The same can be achieved by leaving the bit width unspecified, which has the meaning to
change “all” bits:
a[:] = 5
Often the new value will depend on the old one. For example, to increment an intbv with
the technique above:
a[:] = a + 1
Python also provides augmented assignment operators, which can be used to implement
in-place operations. These are supported on intbv objects and by the converter, so that
the increment can also be done as follows:
a += 1
Converter usage
We will demonstrate the conversion process by showing some examples.
A small design with a single generator
Consider the following MyHDL code for an incrementer module:
def inc(count, enable, clock, reset, n):
""" Incrementer with enable.
count -- output
enable -- control input, increment when 1
clock -- clock input
reset -- asynchronous reset input
n -- counter max value
"""
def incProcess():
while 1:
yield posedge(clock), negedge(reset)
if reset == ACTIVE_LOW:
count.next = 0
else:
if enable:
count.next = (count + 1) % n
return incProcess()
In Verilog terminology, function inc corresponds to a module, while generator function
incProcess roughly corresponds to an always block.
Normally, to simulate the design, we would “elaborate” an instance as follows:
m = 8
n = 2 ** m
count = Signal(intbv(0)[m:])
enable = Signal(bool(0))
clock, reset = [Signal(bool()) for i in range(2)]
inc_inst = inc(count, enable, clock, reset, n=n)
incinst is an elaborated design instance that can be simulated. To convert it to Verilog,
we change the last line as follows:
inc_inst = toVerilog(inc, count, enable, clock, reset, n=n)
Again, this creates an instance that can be simulated, but as a side effect, it also
generates an equivalent Verilog module in file . The Verilog code looks as follows:
module inc_inst (
count,
enable,
clock,
reset
);
output [7:0] count;
reg [7:0] count;
input enable;
input clock;
input reset;
always @(posedge clock or negedge reset) begin: _MYHDL1_BLOCK
if ((reset == 0)) begin
count <= 0;
end
else begin
if (enable) begin
count <= ((count + 1) % 256);
end
end
end
endmodule
You can see the module interface and the always block, as expected from the MyHDL design.
Converting a generator directly
It is also possible to convert a generator directly. For example, consider the following
generator function:
def bin2gray(B, G, width):
""" Gray encoder.
B -- input intbv signal, binary encoded
G -- output intbv signal, gray encoded
width -- bit width
"""
Bext = intbv(0)[width+1:]
while 1:
yield B
Bext[:] = B
for i in range(width):
G.next[i] = Bext[i+1] ^ Bext[i]
As before, you can create an instance and convert to Verilog as follows:
width = 8
B = Signal(intbv(0)[width:])
G = Signal(intbv(0)[width:])
bin2gray_inst = toVerilog(bin2gray, B, G, width)
The generated Verilog code looks as follows:
module bin2gray_inst (
B,
G
);
input [7:0] B;
output [7:0] G;
reg [7:0] G;
always @(B) begin: _MYHDL1_BLOCK
integer i;
reg [9-1:0] Bext;
Bext[9-1:0] = B;
for (i=0; i<8; i=i+1) begin
G[i] <= (Bext[(i + 1)] ^ Bext[i]);
end
end
endmodule
A hierarchical design
The hierarchy of convertible designs can be arbitrarily deep.
For example, suppose we want to design an incrementer with Gray code output. Using the
designs from previous sections, we can proceed as follows:
def GrayInc(graycnt, enable, clock, reset, width):
bincnt = Signal(intbv()[width:])
INC_1 = inc(bincnt, enable, clock, reset, n=2**width)
BIN2GRAY_1 = bin2gray(B=bincnt, G=graycnt, width=width)
return INC_1, BIN2GRAY_1
According to Gray code properties, only a single bit will change in consecutive values.
However, as the bin2gray module is combinatorial, the output bits may have transient
glitches, which may not be desirable. To solve this, let’s create an additional level of
hierarchy and add an output register to the design. (This will create an additional
latency of a clock cycle, which may not be acceptable, but we will ignore that here.)
def GrayIncReg(graycnt, enable, clock, reset, width):
graycnt_comb = Signal(intbv()[width:])
GRAY_INC_1 = GrayInc(graycnt_comb, enable, clock, reset, width)
def reg():
while 1:
yield posedge(clock)
graycnt.next = graycnt_comb
REG_1 = reg()
return GRAY_INC_1, REG_1
We can convert this hierarchical design as before:
width = 8
graycnt = Signal(intbv()[width:])
enable, clock, reset = [Signal(bool()) for i in range(3)]
GRAY_INC_REG_1 = toVerilog(GrayIncReg, graycnt, enable, clock, reset, width)
The Verilog output code looks as follows:
module GRAY_INC_REG_1 (
graycnt,
enable,
clock,
reset
);
output [7:0] graycnt;
reg [7:0] graycnt;
input enable;
input clock;
input reset;
reg [7:0] graycnt_comb;
reg [7:0] _GRAY_INC_1_bincnt;
always @(posedge clock or negedge reset) begin: _MYHDL1_BLOCK
if ((reset == 0)) begin
_GRAY_INC_1_bincnt <= 0;
end
else begin
if (enable) begin
_GRAY_INC_1_bincnt <= ((_GRAY_INC_1_bincnt + 1) % 256);
end
end
end
always @(_GRAY_INC_1_bincnt) begin: _MYHDL4_BLOCK
integer i;
reg [9-1:0] Bext;
Bext[9-1:0] = _GRAY_INC_1_bincnt;
for (i=0; i<8; i=i+1) begin
graycnt_comb[i] <= (Bext[(i + 1)] ^ Bext[i]);
end
end
always @(posedge clock) begin: _MYHDL9_BLOCK
graycnt <= graycnt_comb;
end
endmodule
Note that the output is a flat “net list of blocks”, and that hierarchical signal names
are generated as necessary.
Optimizations for finite state machines
As often in hardware design, finite state machines deserve special attention.
In Verilog and VHDL, finite state machines are typically described using case statements.
Python doesn’t have a case statement, but the converter recognizes particular if-then-else
structures and maps them to case statements. This optimization occurs when a variable
whose type is an enumerated type is sequentially tested against enumeration items in an
if-then-else structure. Also, the appropriate synthesis pragmas for efficient synthesis
are generated in the Verilog code.
As a further optimization, function enum was enhanced to support alternative encoding
schemes elegantly, using an additional parameter encoding. For example:
t_State = enum('SEARCH', 'CONFIRM', 'SYNC', encoding='one_hot')
The default encoding is ’binary’; the other possibilities are ’onehot’ and ’onecold’. This
parameter only affects the conversion output, not the behavior of the type. The generated
Verilog code for case statements is optimized for an efficient implementation according to
the encoding. Note that in contrast, a Verilog designer has to make nontrivial code
changes to implement a different encoding scheme.
As an example, consider the following finite state machine, whose state variable uses the
enumeration type defined above:
FRAME_SIZE = 8
def FramerCtrl(SOF, state, syncFlag, clk, reset_n):
""" Framing control FSM.
SOF -- start-of-frame output bit
state -- FramerState output
syncFlag -- sync pattern found indication input
clk -- clock input
reset_n -- active low reset
"""
index = intbv(0, min=0, max=8) # position in frame
while 1:
yield posedge(clk), negedge(reset_n)
if reset_n == ACTIVE_LOW:
SOF.next = 0
index[:] = 0
state.next = t_State.SEARCH
else:
SOF.next = 0
if state == t_State.SEARCH:
index[:] = 0
if syncFlag:
state.next = t_State.CONFIRM
elif state == t_State.CONFIRM:
if index == 0:
if syncFlag:
state.next = t_State.SYNC
else:
state.next = t_State.SEARCH
elif state == t_State.SYNC:
if index == 0:
if not syncFlag:
state.next = t_State.SEARCH
SOF.next = (index == FRAME_SIZE-1)
else:
raise ValueError("Undefined state")
index[:]= (index + 1) % FRAME_SIZE
The conversion is done as before:
SOF = Signal(bool(0))
syncFlag = Signal(bool(0))
clk = Signal(bool(0))
reset_n = Signal(bool(1))
state = Signal(t_State.SEARCH)
framerctrl_inst = toVerilog(FramerCtrl, SOF, state, syncFlag, clk, reset_n)
The Verilog output looks as follows:
module framerctrl_inst (
SOF,
state,
syncFlag,
clk,
reset_n
);
output SOF;
reg SOF;
output [2:0] state;
reg [2:0] state;
input syncFlag;
input clk;
input reset_n;
always @(posedge clk or negedge reset_n) begin: _MYHDL1_BLOCK
reg [3-1:0] index;
if ((reset_n == 0)) begin
SOF <= 0;
index[3-1:0] = 0;
state <= 3'b001;
end
else begin
SOF <= 0;
// synthesis parallel_case full_case
casez (state)
3'b??1: begin
index[3-1:0] = 0;
if (syncFlag) begin
state <= 3'b010;
end
end
3'b?1?: begin
if ((index == 0)) begin
if (syncFlag) begin
state <= 3'b100;
end
else begin
state <= 3'b001;
end
end
end
3'b1??: begin
if ((index == 0)) begin
if ((!syncFlag)) begin
state <= 3'b001;
end
end
SOF <= (index == (8 - 1));
end
default: begin
$display("Verilog: ValueError(Undefined state)");
$finish;
end
endcase
index[3-1:0] = ((index + 1) % 8);
end
end
endmodule
Known issues
Negative values of intbv instances are not supported.
The intbv class is quite capable of representing negative values. However, the
signed type support in Verilog is relatively recent and mapping to it may be
tricky. In my judgment, this was not the most urgent requirement, so I decided to
leave this for later.
Verilog integers are 32 bit wide
Usually, Verilog integers are 32 bit wide. In contrast, Python is moving toward
integers with undefined width. Python int and long variables are mapped to Verilog
integers; so for values wider than 32 bit this mapping is incorrect.
Synthesis pragmas are specified as Verilog comments.
The recommended way to specify synthesis pragmas in Verilog is through attribute
lists. However, my Verilog simulator (Icarus) doesn’t support them for case
statements (to specify parallelcase and fullcase pragmas). Therefore, I still used
the old but deprecated method of synthesis pragmas in Verilog comments.
Inconsistent place of the sensitivity list inferred from alwayscomb.
The semantics of alwayscomb, both in Verilog and MyHDL, is to have an implicit
sensitivity list at the end of the code. However, this may not be synthesizable.
Therefore, the inferred sensitivity list is put at the top of the corresponding
always block. This may cause inconsistent behavior at the start of the simulation.
The workaround is to create events at time 0.
Non-blocking assignments to task arguments don’t work.
I didn’t get non-blocking (signal) assignments to task arguments to work. I don’t
know yet whether the issue is my own, a Verilog issue, or an issue with my Verilog
simulator Icarus. I’ll need to check this further.
WHAT’S NEW IN MYHDL 0.3
Author Jan Decaluwe
VCD output for waveform viewing
[image: image] [image]
MyHDL now has support for waveform viewing. During simulation, signal changes can be
written to a VCD output file that can be loaded into a waveform viewer tool such as
gtkwave.
The user interface of this feature consists of a single function, traceSignals. To explain
how it works, recall that in MyHDL, an instance is created by assigning the result of a
function call to an instance name. For example:
tb_fsm = testbench()
To enable VCD tracing, the instance should be created as follows instead:
tb_fsm = traceSignals(testbench)
All signals in the instance hierarchy will be traced in a VCD file called . Note that
first the argument of traceSignals consists of the uncalled function. By calling the
function under its control, traceSignals gathers information about the hierarchy and the
signals to be traced. In addition to a function argument, traceSignals accepts an
arbitrary number of non-keyword and keyword arguments that will be passed to the function
call.
Signals are dumped in a suitable format. This format is inferred at the Signal
construction time, from the type of the initial value. In particular, bool signals are
dumped as single bits. (This only works starting with Python 2.3, when bool has become a
separate type). Likewise, intbv signals with a defined bit width are dumped as bit
vectors. To support the general case, other types of signals are dumped as a string
representation, as returned by the standard str function.
[warning] Support for literal string representations is not part of the VCD standard. It
is specific to gtkwave. To generate a standard VCD file, you need to use signals with a
defined bit width only.
Enumeration types
It is often desirable to define a set of identifiers. A standard Python idiom for this
purpose is to assign a range of integers to a tuple of identifiers, like so:
>>> SEARCH, CONFIRM, SYNC = range(3)
>>> CONFIRM
1
However, this technique has some drawbacks. Though it is clearly the intention that the
identifiers belong together, this information is lost as soon as they are defined. Also,
the identifiers evaluate to integers, whereas a string representation of the identifiers
would be preferable. To solve these issues, we need an enumeration type.
MyHDL 0.3 supports enumeration types by providing a function enum. The arguments to enum
are the string representations of the identifiers, and its return value is an enumeration
type. The identifiers are available as attributes of the type. For example:
>>> from myhdl import enum
>>> t_State = enum('SEARCH', 'CONFIRM', 'SYNC')
>>> t_State
<Enum: SEARCH, CONFIRM, SYNC>
>>> t_State.CONFIRM
CONFIRM
Enumeration types are often used for the state variable in a finite state machine. In the
waveform in Section 1, you see a Signal called state. Note how the waveforms show the
string representation of the enumeration type identifiers The state signal has been
constructed with an enumeration type identifier as its initial value, as follows:
state = Signal(t_State.SEARCH)
Inferring the sensitivity list for combinatorial logic
In MyHDL, combinatorial logic is described by a generator function with a sensitivity list
that contains all inputs signals (the signals that are read inside the function).
It may be easy to forget some input signals, especially it there are a lot of them or if
the code is being modified. There are various ways to solve this. One way is to use a
sophisticated editor. Another way is direct language support. For example, recent versions
of Verilog have the always @* construct, that infers all input signals. The
SystemVerilog 3.1 standard improves on this by introducing the always_comb block with
slightly enhanced semantics.
MyHDL 0.3 provides a function called always_comb which is named and modeled after the
SystemVerilog counterpart. always_comb takes a classic local function as its argument.
This function should specify the combinatorial logic behavior. always_comb returns a
generator that is sensitive to all inputs, and that will run the function whenever an
input changes.
For example, suppose that we have a mux module described as follows:
def mux(z, a, b, sel):
""" Multiplexer.
z -- mux output
a, b -- data inputs
sel -- control input
"""
def logic()
while 1:
yield a, b, sel
if sel == 1:
z.next = a
else:
z.next = b
mux_logic = logic()
return mux_logic
Using always_comb, we can describe it as follows instead:
def mux(z, a, b, sel):
""" Multiplexer.
z -- mux output
a, b -- data inputs
sel -- control input
"""
def logic()
if sel == 1:
z.next = a
else:
z.next = b
mux_logic = always_comb(logic)
return mux_logic
Note that in the first version, the sensitivity list is at the beginning of the generator
function code. This is traditionally done in synthesizable RTL style modeling. However,
the semantics of this style are not entirely correct: at the start of the simulation, the
combinatorial output will not reflect the initial state of the inputs. always_comb solves
this by putting the sensitivity list at the end of the code.
Inferring the list of instances
In MyHDL, the instances defined in a top level function need to be returned explicitly.
The following is a schematic example:
def top(...):
...
instance_1 = module_1(...)
instance_2 = module_2(...)
...
instance_n = module_n(...)
...
return instance_1, instance_2, ... , instance_n
It may be convenient to assemble the list of instances automatically, especially if there
are many instances. For this purpose, MyHDL 0.3 provides the function instances. It is
used as follows:
from myhdl import instances
def top(...):
...
instance_1 = module_1(...)
instance_2 = module_2(...)
...
instance_n = module_n(...)
...
return instances()
Function instances uses introspection to inspect the type of the local variables defined
by the calling function. All variables that comply with the definition of an instance are
assembled in a list, and that list is returned.
Inferring the list of processes
In addition to instances, a top level function may also define local generators functions,
which I will call processes because of the analogy with VHDL. Like instances, processes
need to be returned explicitly, with the qualification that they have to be called first
to turn them into generators. The following is a schematic example:
def top(...):
...
def process_1():
...
def process_2():
...
...
def process_n():
...
...
return process_1(), process_2(), ..., process_n()
As for instances, it may be more convenient to assemble the list of processes
automatically. One option is to turn each process into an instance by calling it and
assigning the returned generator to a local variable. Those instances will then be found
by the instances function described in Section 4.
Another option is to use the function processes provided by MyHDL 0.3. This function uses
introspection to find the processes, calls each of them, and assembles the returned
generators into a list. It can be used as follows:
from myhdl import processes
def top(...):
...
def process_1():
...
def process_2():
...
...
def process_n():
...
...
return processes()
To conclude, a top level function with both instances and processes can use the following
idiomatic code to return all of them:
return instances(), processes()
Class intbv enhancements
Class intbv has been enhanced with new features.
It is now possible to leave the left index of a slicing operation unspecified. The meaning
is to access “all” higher order bits. For example:
>>> from myhdl import intbv
>>> n = intbv()
>>> hex(n)
'0x0'
>>> n[:] = 0xde
>>> hex(n)
'0xde'
>>> n[:8] = 0xfa
>>> hex(n)
'0xfade'
>>> n[8:] = 0xb4
>>> hex(n)
'0xfab4'
intbv objects now have min and max attributes that can be specified at construction time.
The meaning is that only values within range(min, max) are permitted. The default value
for these attributes is None, meaning “infinite”. For example (traceback output shortened
for clarity):
>>> n = intbv(min=-17, max=53)
>>> n
intbv(0)
>>> n.min
-17
>>> n.max
53
>>> n[:] = 28
>>> n
intbv(28)
>>> n[:] = -18
Traceback (most recent call last):
....
ValueError: intbv value -18 < minimum -17
>>> n[:] = 53
Traceback (most recent call last):
....
ValueError: intbv value 53 >= maximum 53
When a slice is taken from an intbv object, the return value is a new intbv object with a
defined bit width. As in Verilog, the value of the new intbv object is always positive,
regardless of the sign of the original value. In addition, the min and max attributes are
set implicitly:
>>> v = intbv()[6:]
>>> v
intbv(0)
>>> v.min
0
>>> v.max
64
Lastly, a small change was implemented with regard to binary operations. In previous
versions, both numeric and bit-wise operations always returned a new intbv object, even in
mixed-mode operations with int objects. This has changed: numeric operations return an
int, and bitwise operations return a intbv. In this way, the return value corresponds
better to the nature of the operation.
Function concat
In previous versions, the intbv class provided a method. This method is no longer
available. Instead, there is now a concat function that supports a much broader range of
objects.
A function is more natural because MyHDL objects of various types can be concatenated:
intbv objects with a defined bit width, bool objects, the corresponding signal objects,
and bit strings. All these objects have a defined bit width. Moreover, the first argument
doesn’t need to have a defined bit width. It can also be an unsized intbv, an int, a long,
or a corresponding signal object. Function concat returns an intbv object.
Python 2.3 support
Python 2.3 was released on July 29, 2003, and as of this writing, it is the latest stable
Python release. MyHDL 0.3 works with both Python 2.2 and Python 2.3. In good Python
tradition, MyHDL code developed with Python 2.2 should run without changes or problems in
Python 2.3.
In general, I am not that keen on early upgrading. However, as it happens, the evolution
of Python enables features that are really important or even crucial to MyHDL. Python 2.2
generators are the best example: they are the cornerstone of MyHDL. But Python 2.3 also
has significant benefits, which I will summarize below.
First, generators and the yield statement are a default Python 2.3 feature. This means
that statements are no longer required.
Second, Python 2.3 has a bool type, which is implemented as a subtype of int. For general
Python use, the implications are rather limited - the main difference is that logical
result values will print as False and True instead of 0 and 1. However, in MyHDL, I can
use the bool type to infer a bit width. If a Signal is constructed with a bool value, it
is a single bit Signal. One application is waveform viewing as in Section 1 In the
waveform, note how single bit signals are displayed as level changes. With Python 2.2, the
waveforms of these signals would only show value changes, which is not as clear for single
bits.
Finally, Python 2.3 is significantly faster. MyHDL code runs 25–35% faster in Python 2.3.
This is a very nice speedup compared to the small burden of a straightforward upgrade.
Python is a very stable language, so upgrading to Python 2.3 is virtually risk free. Given
the additional benefits, I recommend MyHDL users to do so as soon as possible. For the
next major MyHDLrelease, the new features will become required and only Python 2.3 (and
higher) will be supported.
• genindex
• search
AUTHOR
Jan Decaluwe
COPYRIGHT
2019, Jan Decaluwe
October 18, 2019 MYHDL(1)