myhdl/doc/reference.tex

\chapter{Reference}


\myhdl\ is implemented as a Python package called \code{myhdl}. This
chapter describes the objects that are exported by this package.

\section{The \class{Simulation} class}
\begin{classdesc}{Simulation}{arg \optional{, arg \moreargs}}
Class to construct a new simulation. Each argument is either be a
\myhdl\ generator, or a nested sequence of such generators. (A nested
sequence is defined as a sequence in which each item may itself be a
nested sequence.) See section~\ref{myhdl-generators} for the
definition of \myhdl\ generators and their interaction with a
\class{Simulation} object.
\end{classdesc}

A \class{Simulation} object has the following method:

\begin{methoddesc}[Simulation]{run}{\optional{duration}}
Run the simulation forever (by default) or for a specified duration.
\end{methoddesc}

\section{The \class{Signal} class}
\label{signal}
\begin{classdesc}{Signal}{val \optional{, delay}}
This class is used to construct a new signal and to initialize its
value to \var{val}. Optionally, a delay can be specified.
\end{classdesc}

A \class{Signal} object has the following attributes:

\begin{memberdesc}[Signal]{next}
Read-write attribute that represents the next value of the signal.
\end{memberdesc}

\begin{memberdesc}[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 directly assigned to the \code{next}
attribute of another Signal object, its current value is assigned
instead.
\end{memberdesc}



\section{\myhdl\ generators and trigger objects}
\label{myhdl-generators}
\myhdl\ generators are standard Python generators with specialized
\keyword{yield} statements. In hardware description languages, the equivalent
statements are called \emph{sensitivity lists}. The general format
of \keyword{yield} statements in in \myhdl\ generators is:

\hspace{\leftmargin}\keyword{yield} \var{clause \optional{, clause ...}}

After a simulation object executes a \keyword{yield} statement, it
suspends execution of the generator. At the same time, each
\var{clause} is a \emph{trigger object} which defines the condition
upon which the generator should be resumed. However, per invocation of a
\keyword{yield} statement, the generator is resumed exactly once,
regardless of the number of clauses. This happens as soon as one
of the objects triggers; subsequent triggers are
neglected. (However, as a result of the resumption, it is possible
that the same \keyword{yield} statement is invoked again, and that a
subsequent trigger still triggers the generator.)

In this section, the trigger objects and their functionality will be
described. 

\begin{funcdesc}{posedge}{signal}
Return a trigger object that specifies that the generator should
resume on a rising edge on the signal. A rising edge means a change
from false to true.
\end{funcdesc}

\begin{funcdesc}{negedge}{signal}
Return a trigger object that specifies that the generator should
resume on a falling edge on the signal. A falling edge means a change
from true to false.
\end{funcdesc}

\begin{funcdesc}{delay}{t}
Return a trigger object that specifies that the generator should
resume after a delay \var{t}.
\end{funcdesc}

\begin{funcdesc}{join}{arg \optional{, arg \moreargs}}
Join a number of trigger objects together and return a joined
trigger object.  The effect is that the joined trigger object will
trigger when \emph{all} of its arguments have triggered.
\end{funcdesc}

In addition, some objects can directly function as trigger
objects. These are the objects of the following types:

\begin{datadesc}{Signal}
For the full description of the \class{Signal} class, see
section~\ref{signal}.

A signal is a trigger object. Whenever a signal changes value, the
generator is triggered.
\end{datadesc}

\begin{datadesc}{GeneratorType}
\myhdl\ generators can itself be used as trigger objects. 
This corresponds to spawning a new generator, while the original
generator waits for it to complete.  In other words, the original
generator is triggered when the spawned generator completes.
\end{datadesc}

In addition, as a special case, the Python \code{None} object can be
present in  a \code{yield} statement:

\begin{datadesc}{None}
This is the do-nothing trigger object. The generator immediately
resumes, as if no \code{yield} statement were present. This can be
useful if the \code{yield} statement also has generator clauses: those
generators are spawned, while the original generator resumes
immediately.

\end{datadesc}



\section{Miscellaneous objects}

The following objects can be convenient in \myhdl\ modeling.

\begin{excclassdesc}{StopSimulation}{}
Base exception that is caught by the \code{Simulation.run} method to
stop a simulation. Can be subclassed and raised in generator code.
\end{excclassdesc}

\begin{funcdesc}{now}{}
Return the current simulation time.
\end{funcdesc}

\begin{funcdesc}{downrange}{high \optional{, low=0}}
Generates a downward range list of integers. Modeled after the
standard \code{range} function, but works in the downward
direction. The returned interval is half-open, with the \var{high}
index not included. \var{low} is optional and defaults to zero.

This function is especially useful with the \class{intbv} class, that
also works with downward indexing.
\end{funcdesc}

\begin{funcdesc}{bin}{num \optional{, width}}
Return a representation as a bit string.  If \var{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
\code{hex} and \code{oct}. A binary string representation is often
needed in hardware design.
\end{funcdesc}


\section{The \class{intbv} class}

\begin{classdesc}{intbv}{arg}
This class represents \class{int}-like objects with some additional
features that make it suitable for hardware design. The constructor
argument can be an \class{int}, a \class{long}, an \class{intbv} or a
bit string (a string with only '0's or '1's). For a bit string
argument, the value is calculated as \code{int(\var{bitstring}, 2)}. 
\end{classdesc}

Unlike \class{int} objects, \class{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, \class{intbv} is not a subclass from \class{int},
even though \class{int} provides most of the desired
functionality. (It is not possible to derive a mutable subtype from
an immutable base type.)

An \class{intbv} object supports the same comparison, numeric,
bitwise, logical, and conversion operations as \class{int} objects. See
\url{http://www.python.org/doc/current/lib/typesnumeric.html} for more
information on such operations. In all binary operations,
\class{intbv} objects can work together with \class{int} objects; in
those cases the return type is an \class{intbv} object.

In addition, \class{intbv} objects support indexing and slicing
operations:

\begin{tableiii}{clc}{code}{Operation}{Result}{Notes}
  \lineiii{\var{bv}[\var{i}]}
	  {item \var{i} of \var{bv}}
	  {(1)}
  \lineiii{\var{bv}[\var{i}] = \var{x}}  
	  {item \var{i} of \var{bv} is replaced by \var{x}} 
          {(1)}
  \lineiii{\var{bv}[\var{i}:\var{j}]} 
          {slice of \var{bv} from \var{i} downto \var{j}} 
          {(2)(3)}
  \lineiii{\var{bv}[\var{i}:\var{j}] = \var{t}} 
  	  {slice of \var{bv} from \var{i} downto \var{j} is replaced
          by \var{t}} 
          {(2)(4)}
\end{tableiii}

\begin{description}
\item[(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
	  \class{intbv} value is decomposed as a sum of powers of 2,
	  the bit with index \var{i} corresponds to the term
	  \code{2**i}.

\item[(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 \emph{leftmost} bit in this
	  case. As in standard Python, this takes care of one-off
	  issues in many practical cases: in particular,
	  \code{bv[\var{i}:]} returns \var{i} bits;
	  \code{bv[\var{i}:\var{j}]} has \code{\var{i}-\var{j}}
	  bits. As \class{intbv} objects have no explicitly defined
	  bit width, the high index \var{j} has no default value and
	  cannot be omitted, while the low index \var{j} defaults to
	  \code{0}.

\item[(3)] The value returned from a slicing operation is always
	  positive; higher order bits are implicitly assumed to be
	  zero. The bit width is implicitly stored in the returned bit
	  width, so that the returned object can be used in
	  concatenations and as an iterator.

\item[(4)] In setting a slice, it is checked whether the slice is wide
	  enough to accept all significant bits of the value.
\end{description}

In addition, \class{intbv} objects support a concatenation method:

\begin{methoddesc}[intbv]{concat}{\optional{arg \moreargs}}
Concatenate the arguments to an \class{intbv} object. Naturally, the
concatenation arguments need to have a defined bit width. Therefore,
if they are \class{intbv} objects, they have to be the return values
of a slicing operation. Alternatively, they may be bit strings.

In contrast to all other arguments, the implicit \var{self} argument
doesn't need to have a defined bit with. This is due to the fact that
concatenation occurs at the lsb (rightmost) side.

It may be clearer to call this method as an unbound method with an
explicit first \class{intbv} argument.
\end{methoddesc}

In addition, an \class{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 \class{intbv} objects with a
defined bit width.