myhdl/doc/manual/background.tex

\chapter{Background information \label{background}}

\section{Prerequisites \label{prerequisites}}

You need a basic understanding of Python to use \myhdl{}.
If you don't know Python, you will take comfort in knowing
that it is probably one of the easiest programming languages to
learn~\footnote{You must be bored by such claims, but in Python's
case it's true.}. Learning Python is also one of the better time
investments that engineering professionals can make~\footnote{I am not
biased.}.

For beginners, \url{http://www.python.org/doc/current/tut/tut.html} is
probably the best choice for an on-line tutorial. For alternatives,
see \url{http://www.python.org/doc/Newbies.html}.

A working knowledge of a hardware description language such as Verilog
or VHDL is helpful. 

\section{A small tutorial on generators \label{tutorial}}

Generators are a recent Python feature, introduced in
Python 2.2. Therefore, there isn't a lot of tutorial material
available yet. Because generators are the key concept in
\myhdl{}, I include a small tutorial here.

Consider the following nonsensical function:

\begin{verbatim}
def function():
    for i in range(5):
        return i
\end{verbatim}

You can see why it doesn't make a lot of sense. As soon as the first
loop iteration is entered, the function returns:

\begin{verbatim}
>>> function()
0
\end{verbatim}

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
\keyword{return} with \keyword{yield}:

\begin{verbatim}
def generator():
    for i in range(5):
        yield i
\end{verbatim}

Now we get:

\begin{verbatim}
>>> generator()
<generator object at 0x815d5a8>
\end{verbatim}

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 \function{next()} method:

\begin{verbatim}
>>> 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
\end{verbatim}

Now we can generate the subsequent values from the for loop on demand,
until they are exhausted. What happens is that the
\keyword{yield} statement is like a
\keyword{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 a further value by calling the
generator's \function{next()} method. We can say that generators are
\dfn{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 \dfn{processes} in VHDL and \dfn{always blocks} in
Verilog. Like in those languages, 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 define the condition upon which the
generator should resume. In other words, \keyword{yield}
statements work as generalized 
    \index{sensitivity list}%
sensitivity lists. 

If you want to know more about generators, consult the on-line Python
documentation, e.g. at \url{http://www.python.org/doc/2.2.2/whatsnew}. 

\begin{notice}[warning]
As mentioned earlier, generators were introduced in Python 2.2. In
that version, they were introduced as a ``future'' feature that has to
be enabled explicitly. In Python 2.3, which is the latest stable
Python version at the time of this writing, generators are enabled by
default.

Besides generators, Python 2.3 has several other interesting new
features, and it runs 25--35\% faster than Python 2.2. For this
reasons, I recommend MyHDL users to upgrade to Python 2.3. The next
major release of MyHDL will rely on on the new features and will
require Python 2.3 or higher.

In the mean time, if you use Python 2.2, you have to include the
following line at the start of all code that defines generator
functions:

\begin{verbatim}
from __future__ import generators
\end{verbatim}

From Python 2.3 on, this line may still be in the code, though it will
not have an effect anymore.
\end{notice}