myhdl/doc/informal.tex

\chapter{Introduction to \myhdl\ }

\section{A basic \myhdl\ simulation}

We will introduce \myhdl\ with a classical \code{Hello World} style
example. Here are the contents of a \myhdl\ simulation script called
\file{Hello1.py}:

\begin{verbatim}
from myhdl import delay, now, Simulation

def sayHello():
    while 1:
        yield delay(10)
        print "%s Hello World!" % now()

gen = sayHello()
sim = Simulation(gen)
sim.run(30)

\end{verbatim}

When we run this script, we get the following output: 

\begin{verbatim}
% python Hello1.py
10 Hello World!
20 Hello World!
30 Hello World!
StopSimulation: Simulated for duration 30

\end{verbatim}

The first line of the script imports a
number of objects from the \code{myhdl} package. In good Python style, and
unlike most other languages, we can only use identifiers that are
\emph{literally} defined in the source file \footnote{I don't want to
explain the \samp{import *} syntax}.

Next, we define a generator function called
\code{sayHello}. This is a generator function (as opposed to
a classic Python function) because it contains a \keyword{yield}
statement (instead of \keyword{return} statement). In \myhdl\, a
\keyword{yield} statement has a similar purpose as a \keyword{wait}
statement in VHDL: the statement suspends execution of the function,
and its clauses specify when the function should resume. In this case,
there is a \code{delay} clause, that specifies the required delay.

To make sure that the generator runs ``forever'', we wrap its behavior
in a \code{while 1} loop. This is as standard Python idiom, and it is
the \myhdl\ equivalent to a Verilog \keyword{always} block or a
VHDL \keyword{process}.

In \myhdl\, the basic simulation objects are generators. Generators
are created by calling generator functions. For example, variable
\code{gen} refers to a generator. To simulate this generator, we pass
it as an argument to a \class{Simulation} object constructor.  We then
run the simulation for the desired amount of time.


\section{Concurrent generators and signals}

In the previous section, we simulated a single generator. Of course,
real hardware descriptions are not like that: in fact, they are
typically massively concurrent. \myhdl\ supports this by allowing an
arbitrary number of concurrent generators. More specifically, a
\class{Simulation} constructor can take an arbitrary number of
arguments, each of which can be a generator or a nested list of
generators.

With concurrency comes the problem of deterministic
communication. Therefore, hardware languages use special objects to
support deterministic communication between concurrent
regions. \myhdl\ has as \class{Signal} object which is roughly modelled
after VHDL signals.

We will demonstrate these concepts by extending our first example. We
introduce a clock signal, driven by a second generator. The
\code{sayHello} generator function is modified to wait for a rising
edge (\code{posedge}) of the clock instead of a delay. The resulting
script is as follows:

\begin{verbatim}
from myhdl import Signal, delay, posedge, now, Simulation

clk = Signal(0)

def clkGen():
    while 1:
        yield delay(10)
        clk.next = 1
        yield delay(10)
        clk.next = 0

def sayHello():
    while 1:
        yield posedge(clk)
        print "%s Hello World!" % now()

sim = Simulation(clkGen(), sayHello())
sim.run(50)

\end{verbatim}

When we run this script, we get:

\begin{verbatim}
% python Hello2.py
10 Hello World!
30 Hello World!
50 Hello World!
StopSimulation: Simulated for duration 50

\end{verbatim}

The \code{clk} signal is constructed with an initial value
\code{0}. In the clock generator function \code{clkGen}, it is then
continuously toggled after a certain delay. In \myhdl{}, a the next
value of a signal is specified by assigning to its \code{next}
attribute. This is the \myhdl\ equivalent of VHDL signal assignments
and Verilog's non-blocking assignments.

The \code{sayHello} generator function shows a second form of a
\keyword{yield} statement: \samp{yield posedge(\var{aSignal})}. Again,
the generator will suspend execution at that point, but in this case
it specifies that it should resume when there is a rising edge on the
signal.

The \class{Simulation} constructor now takes two generator arguments
that run concurrently throughout the simulation.

\section{Parameters and instantiations}

So far, the generator function examples had no parameters. For
example, the \code{clk} signal was defined in the enclosing scope of
the generator functions. However, to make the code reusable we will
want to pass arguments through a parameter list. For example, we can
change the clock generator function to make it more general
and reusable, as follows:

\begin{verbatim}
def clkGen(clock, period=20):
    lowTime = int(period/2)
    highTime = period - lowTime
    while 1:
        yield delay(lowTime)
        clock.next = 1
        yield delay(highTime)
        clock.next = 0

\end{verbatim}

The clock signal is now a parameter of the function. Also, the clock
period is a parameter with a default value of \code{20}.

Similarly, the \code{sayHello} function can be made more general:

\begin{verbatim}
def sayHello(clock, to="World!"):
    while 1:
        yield posedge(clock)
        print "%s Hello %s" % (now(), to)

\end{verbatim}

XXX

Multiple generators can be created by multiple calls to a generator
function, possibly with different parameters. This is analogous to the
concept of \emph{instantiation} in hardware description
languages. \myhdl\ supports hierarchy and instantiations through
higher level functions that return multiple generators.

\begin{verbatim}
def talk():

    clk1 = Signal(0)
    clk2 = Signal(0)
    
    clkGen1 = clkGen(clk1)
    clkGen2 = clkGen(clock=clk2, period=19)
    sayHello1 = sayHello(clock=clk1)
    sayHello2 = sayHello(to="MyHDL", clock=clk2)

    return (clkGen1, clkGen2, sayHello1, sayHello2) 

sim = Simulation(talk())
sim.run(50)

\end{verbatim}

This produces the following output:

\begin{verbatim}
% python Hello3.py
9 Hello MyHDL
10 Hello World!
28 Hello MyHDL
30 Hello World!
47 Hello MyHDL
50 Hello World!
StopSimulation: Simulated for duration 50

\end{verbatim}

Like in standard Python, positional or named parameter association can
be used, or a mix of the two \footnote{All positional parameters have
to come before any named parameter.}. These styles are demonstrated in
the example. Named association is very useful if there are a lot of
parameters.