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 \code{yield}
statement (instead of \code{return} statement). In \myhdl\, a
\code{yield} statement has a similar purpose as a \code{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 \code{always} block or a
VHDL \code{process}.

In \myhdl\, the basic simulation objects are generators. Generators
are created by calling a generator function. For example, variable
\code{gen} refers to a generator. To simulate this generator, we pass
it as an argument to a code{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
\code{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 determinism. Therefore, hardware
languages use special objects to support deterministic communication
between concurrent regions. \myhdl\ has as \code{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
\code{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 \code{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. The signals
they operated on were defined in their enclosing scope. 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 as follows to make it more general and reusable:

\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.